> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Location Data

> Seven endpoints for POIs, permits, traffic counts, jobs, H3 cells, and neighborhood scoring data — the raw signals behind Locus territory intelligence.

## `GET` `/api/pois`

Nearby points of interest with ratings and photos.

**Query parameters**

| Name     | Type  | Required | Default | Description                      |
| -------- | ----- | -------- | ------- | -------------------------------- |
| `lat`    | float | ✓        |         | Latitude.                        |
| `lng`    | float | ✓        |         | Longitude.                       |
| `radius` | float |          | `0.5`   | Radius in km (max 10).           |
| `limit`  | int   |          | `50`    | Max results to return (max 200). |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/pois?lat=37.7749&lng=-122.4194&radius=0.5"
```

**Response**

```json theme={null}
{
  "pois": [
    {
      "id": "abc123",
      "name": "Blue Bottle Coffee",
      "primary_type": "cafe",
      "rating": 4.5,
      "review_count": 342,
      "photo_reference": "Aap_uE...",
      "distance_m": 120
    }
  ]
}
```

| Field                    | Type   | Description                                     |
| ------------------------ | ------ | ----------------------------------------------- |
| `pois`                   | array  | Array of nearby point-of-interest objects.      |
| `pois[].id`              | string | Unique POI identifier.                          |
| `pois[].name`            | string | Business name.                                  |
| `pois[].primary_type`    | string | Business type category.                         |
| `pois[].rating`          | float  | Average rating (0-5).                           |
| `pois[].review_count`    | int    | Total number of reviews.                        |
| `pois[].photo_reference` | string | Photo reference for use with /api/places-photo. |
| `pois[].distance_m`      | float  | Distance from query point in meters.            |

## `GET` `/api/permits`

Building permits near a location with value aggregation.

**Query parameters**

| Name     | Type  | Required | Default | Description            |
| -------- | ----- | -------- | ------- | ---------------------- |
| `lat`    | float | ✓        |         | Latitude.              |
| `lng`    | float | ✓        |         | Longitude.             |
| `radius` | float |          | `1.0`   | Radius in km (max 10). |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/permits?lat=37.7749&lng=-122.4194"
```

**Response**

```json theme={null}
{
  "total_permits": 47,
  "total_value": 12500000,
  "by_type": {
    "new_construction": 12,
    "renovation": 28,
    "demolition": 7
  },
  "permits": [
    {
      "id": "P-2025-1234",
      "permit_type": "new_construction",
      "status": "issued",
      "address": "123 Market St",
      "estimated_cost": 2500000,
      "issue_date": "2025-11-15"
    }
  ]
}
```

| Field           | Type   | Description                                |
| --------------- | ------ | ------------------------------------------ |
| `total_permits` | int    | Total number of permits in the radius.     |
| `total_value`   | float  | Sum of estimated\_cost across all permits. |
| `by_type`       | object | Permit count grouped by type.              |
| `permits`       | array  | Up to 10 most recent permit records.       |

## `GET` `/api/traffic`

Real-time traffic flow data.

**Query parameters**

| Name  | Type  | Required | Default | Description |
| ----- | ----- | -------- | ------- | ----------- |
| `lat` | float | ✓        |         | Latitude.   |
| `lng` | float | ✓        |         | Longitude.  |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/traffic?lat=37.7749&lng=-122.4194"
```

**Response**

```json theme={null}
{
  "current_speed": 28,
  "free_flow_speed": 45,
  "congestion_ratio": 0.62,
  "congestion_level": "moderate",
  "road_category": "arterial"
}
```

| Field              | Type   | Description                                |
| ------------------ | ------ | ------------------------------------------ |
| `current_speed`    | int    | Current speed in mph.                      |
| `free_flow_speed`  | int    | Free-flow speed in mph (no traffic).       |
| `congestion_ratio` | float  | Ratio of current to free-flow speed (0-1). |
| `congestion_level` | string | Human-readable congestion level.           |
| `road_category`    | string | Road type classification.                  |

## `GET` `/api/jobs`

Local job market data.

**Query parameters**

| Name  | Type  | Required | Default | Description |
| ----- | ----- | -------- | ------- | ----------- |
| `lat` | float | ✓        |         | Latitude.   |
| `lng` | float | ✓        |         | Longitude.  |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/jobs?lat=37.7749&lng=-122.4194"
```

**Response**

```json theme={null}
{
  "total_postings": 1243,
  "avg_salary": 95000,
  "top_categories": [
    { "name": "IT Jobs", "count": 412 },
    { "name": "Engineering", "count": 198 }
  ],
  "top_companies": [
    { "name": "Salesforce", "count": 87 },
    { "name": "Google", "count": 64 }
  ]
}
```

| Field            | Type  | Description                                   |
| ---------------- | ----- | --------------------------------------------- |
| `total_postings` | int   | Total active job postings near this location. |
| `avg_salary`     | float | Average listed salary in USD.                 |
| `top_categories` | array | Top job categories by count.                  |
| `top_companies`  | array | Top hiring companies by posting count.        |

## `GET` `/api/cells`

H3 heatmap cells for a metro area.

**Query parameters**

| Name    | Type   | Required | Default | Description                                   |
| ------- | ------ | -------- | ------- | --------------------------------------------- |
| `metro` | string |          | `sf`    | Metro slug (e.g. sf, nyc, la, chi, mia, atx). |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/cells?metro=sf"
```

**Response**

```json theme={null}
{
  "cells": [
    {
      "h3_index": "882a100d63fffff",
      "priority": 0.85,
      "center_lat": 37.7749,
      "center_lng": -122.4194
    }
  ]
}
```

| Field                | Type   | Description                                 |
| -------------------- | ------ | ------------------------------------------- |
| `cells`              | array  | Array of H3 hexagonal cells.                |
| `cells[].h3_index`   | string | H3 hex index at resolution 8.               |
| `cells[].priority`   | float  | Priority score for heatmap rendering (0-1). |
| `cells[].center_lat` | float  | Latitude of the hex center.                 |
| `cells[].center_lng` | float  | Longitude of the hex center.                |

## `GET` `/api/neighborhood-score`

Aggregated scores for an H3 neighborhood (resolution-7 parent cell). Returns the average of all resolution-8 child cells within the neighborhood. Fast, cached response.

**Query parameters**

| Name      | Type   | Required | Default   | Description                                                                              |
| --------- | ------ | -------- | --------- | ---------------------------------------------------------------------------------------- |
| `h3Index` | string | ✓        |           | Resolution-8 H3 cell index. The endpoint automatically resolves the parent neighborhood. |
| `profile` | string |          | `general` | Scoring profile.                                                                         |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/neighborhood-score?h3Index=882a100d63fffff&profile=general"
```

**Response**

```json theme={null}
{
  "composite": 68.4,
  "confidence": 0.89,
  "scoreLow": 62.1,
  "scoreHigh": 74.7,
  "coverageLevel": "high",
  "groups": {
    "businessVitality": { "score": 72, "confidence": 0.91 },
    "populationMomentum": { "score": 65, "confidence": 0.87 },
    "demographics": { "score": 71, "confidence": 0.93 },
    "economicStrength": { "score": 67, "confidence": 0.88 },
    "developmentPipeline": { "score": 60, "confidence": 0.82 },
    "accessibility": { "score": 78, "confidence": 0.95 },
    "safetyEnvironment": { "score": 55, "confidence": 0.84 },
    "amenityDemand": { "score": 73, "confidence": 0.90 }
  },
  "cellCount": 7,
  "neighborhoodH3": "872a100d6ffffff",
  "profile": "general"
}
```

| Field                    | Type   | Description                                      |
| ------------------------ | ------ | ------------------------------------------------ |
| `composite`              | float  | Average composite score across the neighborhood. |
| `scoreLow` / `scoreHigh` | float  | Confidence interval bounds.                      |
| `coverageLevel`          | string | Data coverage: `high`, `medium`, or `low`.       |
| `cellCount`              | int    | Number of resolution-8 cells averaged.           |
| `neighborhoodH3`         | string | Resolution-7 parent H3 index.                    |

## `GET` `/api/neighborhoods/score`

Score a named neighborhood by running the full scoring engine across cells within its boundary. More detailed than `/api/neighborhood-score` — includes tier classification, summary text, and the neighborhood boundary geometry.

**Query parameters**

| Name         | Type   | Required | Default   | Description                                      |
| ------------ | ------ | -------- | --------- | ------------------------------------------------ |
| `metro_slug` | string | ✓        |           | Metro slug (e.g. `sf`, `nyc`).                   |
| `name`       | string | ✓        |           | Neighborhood name (e.g. `Hayes Valley`, `SoMa`). |
| `profile`    | string |          | `general` | Scoring profile.                                 |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/neighborhoods/score?metro_slug=sf&name=Hayes+Valley"
```

**Response**

```json theme={null}
{
  "neighborhood": {
    "name": "Hayes Valley",
    "metro_slug": "sf",
    "cell_count": 14,
    "sampled_cells": 10,
    "population": 8200,
    "source": "census_places"
  },
  "score": {
    "composite": 74,
    "tier": "A",
    "tierDescription": "Strong fundamentals with active development signals",
    "summary": "Hayes Valley scores well for business vitality and accessibility, driven by dense retail corridors and strong transit access.",
    "confidence": 0.91,
    "scoreLow": 68,
    "scoreHigh": 80,
    "coverageLevel": "high",
    "sourcesUsed": 18,
    "sourcesTotal": 22,
    "profile": "general",
    "groups": {
      "businessVitality": { "score": 82, "tier": "A", "confidence": 0.93 },
      "accessibility": { "score": 88, "tier": "A+", "confidence": 0.96 }
    }
  }
}
```

| Field                        | Type   | Description                                                                    |
| ---------------------------- | ------ | ------------------------------------------------------------------------------ |
| `neighborhood.cell_count`    | int    | Total H3 cells in the boundary.                                                |
| `neighborhood.sampled_cells` | int    | Number of cells actually scored (up to 10).                                    |
| `score.tier`                 | string | Letter grade: `A+`, `A`, `B+`, `B`, `C`, `D`, `F`.                             |
| `score.summary`              | string | AI-generated narrative summary of the neighborhood's strengths and weaknesses. |
| `score.groups`               | object | Per-group scores with tier and confidence.                                     |