> ## 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.

# Predictions

> Two endpoints for survival-curve lead-lag analysis between Locus signal groups — predict which neighborhoods will gentrify, decline, or see permit surges.

## `GET` `/api/lead-lag`

<Note>Requires Bearer token.</Note>

Survival curve analysis showing how one signal leads or lags another. Useful for predicting which neighborhoods will gentrify, decline, or see permit surges.

**Query parameters**

| Name         | Type   | Required | Default | Description                                                        |
| ------------ | ------ | -------- | ------- | ------------------------------------------------------------------ |
| `cause`      | string | ✓        |         | Leading signal group (e.g. businessVitality, populationMomentum).  |
| `effect`     | string | ✓        |         | Lagging signal group (e.g. developmentPipeline, economicStrength). |
| `metro`      | string |          |         | Metro slug filter. Omit for all metros.                            |
| `lag_months` | int    |          | `12`    | Maximum lag window in months (1-24).                               |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/lead-lag?cause=businessVitality&effect=developmentPipeline&metro=sf" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json theme={null}
{
  "cause": "businessVitality",
  "effect": "developmentPipeline",
  "metro": "sf",
  "peak_lag_months": 6,
  "peak_correlation": 0.72,
  "survival_curve": [
    { "month": 0, "correlation": 0.12 },
    { "month": 3, "correlation": 0.45 },
    { "month": 6, "correlation": 0.72 },
    { "month": 9, "correlation": 0.58 },
    { "month": 12, "correlation": 0.31 }
  ],
  "interpretation": "Business vitality changes lead development pipeline activity by ~6 months in SF."
}
```

| Field              | Type   | Description                                          |
| ------------------ | ------ | ---------------------------------------------------- |
| `peak_lag_months`  | int    | Month offset where correlation is strongest.         |
| `peak_correlation` | float  | Pearson correlation at peak lag (0-1).               |
| `survival_curve`   | array  | Monthly correlation values over the lag window.      |
| `interpretation`   | string | Human-readable summary of the lead-lag relationship. |

## `GET` `/api/permits/predict`

<Note>Requires Bearer token.</Note>

Sequence prediction for building permit activity at the H3 cell level. Uses historical permit patterns to forecast future issuance.

**Query parameters**

| Name       | Type   | Required | Default | Description                        |
| ---------- | ------ | -------- | ------- | ---------------------------------- |
| `h3_index` | string | ✓        |         | H3 hex index at resolution 8.      |
| `horizon`  | int    |          | `6`     | Forecast horizon in months (1-12). |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/permits/predict?h3_index=882a100d63fffff&horizon=6" \
  -H "Authorization: Bearer al_your_key_here"
```

**Response**

```json theme={null}
{
  "h3_index": "882a100d63fffff",
  "historical_avg_monthly": 4.2,
  "forecast": [
    { "month": "2026-04", "predicted_permits": 5, "confidence": 0.85 },
    { "month": "2026-05", "predicted_permits": 6, "confidence": 0.78 },
    { "month": "2026-06", "predicted_permits": 4, "confidence": 0.71 },
    { "month": "2026-07", "predicted_permits": 7, "confidence": 0.65 },
    { "month": "2026-08", "predicted_permits": 5, "confidence": 0.59 },
    { "month": "2026-09", "predicted_permits": 4, "confidence": 0.52 }
  ],
  "trend": "increasing",
  "model": "arima_h3_v2"
}
```

| Field                          | Type   | Description                                                 |
| ------------------------------ | ------ | ----------------------------------------------------------- |
| `historical_avg_monthly`       | float  | Average monthly permits over the last 12 months.            |
| `forecast`                     | array  | Monthly predictions with confidence intervals.              |
| `forecast[].predicted_permits` | int    | Predicted permit count for the month.                       |
| `forecast[].confidence`        | float  | Model confidence (0-1), decreases with horizon.             |
| `trend`                        | string | Overall trend direction: increasing, stable, or decreasing. |