========================================================================
# Quickstart
Source: https://docs.padstats.io/docs/getting-started/quickstart
========================================================================

# Quickstart

Get a property valuation from the PadStats API in under 5 minutes.

## 1. Get your API key

Sign up at [dashboard.padstats.io](https://dashboard.padstats.io) to receive your API key.

## 2. Make your first request

```bash
curl -X POST https://api.padstats.io/v1/avm/property \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, Austin, TX 78701",
    "property_type": "houses",
    "total_bedrooms": 3,
    "total_bathrooms": 2,
    "living_area": 1800,
    "year_built": 1998
  }'
```

## 3. Read the response

```json
{
  "address_info": {
    "formatted_address": "123 Main St, Austin, TX 78701",
    "street_address": "123 Main St",
    "city": "Austin",
    "state": "Texas",
    "state_code": "TX",
    "county": "Travis County",
    "postal_code": "78701",
    "latitude": 30.2672,
    "longitude": -97.7431,
    "geohash8": "9v6kn2pb",
    "census_geoids": {
      "state_fips": "48",
      "county_fips": "453",
      "tract_fips": "002100",
      "block_fips": "1"
    }
  },
  "valuation": {
    "point_value": 487000,
    "confidence_interval_95": {
      "lower": 452000,
      "upper": 522000
    },
    "probabilistic_distribution": {
      "mean": 487000,
      "std": 35700,
      "median": 485000
    }
  }
}
```

`point_value` is the estimated market value in dollars. `confidence_interval_95` gives the 95% confidence range.

## Other quick examples

**Get flood zone for a property:**

```bash
curl "https://api.padstats.io/v1/flood-zone?address=123+Main+St,+Austin,+TX+78701" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Get multiple data types in one call:**

```bash
curl -X POST https://api.padstats.io/v1/comprehensive \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": ["property-avm", "flood-zone", "fire-risk"],
    "address": "123 Main St, Austin, TX 78701",
    "beds": 3,
    "baths": 2,
    "living_area": 1800,
    "year_built": 1998,
    "property_type": "houses"
  }'
```

## Next steps

- [Authentication](./authentication) — API key format, security, and error codes
- [Sandbox](./sandbox) — Test interactively without writing code
- [Property Valuation Guide](../guides/property-valuation) — All AVM request fields explained
- [API Reference](/docs/api/padstats-intelligence-api) — Full endpoint reference


========================================================================
# Authentication
Source: https://docs.padstats.io/docs/getting-started/authentication
========================================================================

# Authentication

The PadStats API uses API keys for authentication. Pass your key in the `X-API-Key` header on every request.

```bash
curl -X POST https://api.padstats.io/v1/avm/property \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

## Getting an API key

API keys are issued from the [PadStats dashboard](https://dashboard.padstats.io). Each key is tied to your account and plan tier.

## Using your key

```python title="Python"
import requests

response = requests.post(
    "https://api.padstats.io/v1/avm/property",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "address": "123 Main St, Austin, TX 78701",
        "total_bedrooms": 3,
        "total_bathrooms": 2,
    }
)
```

```javascript title="JavaScript"
const response = await fetch("https://api.padstats.io/v1/avm/property", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    address: "123 Main St, Austin, TX 78701",
    total_bedrooms: 3,
    total_bathrooms: 2,
  }),
});
```

## Security best practices

- **Never expose your API key in client-side code or public repositories.** Store it as an environment variable.
- **Use one key per environment** (development, staging, production) so you can rotate or revoke each independently.
- **Rotate immediately** if you suspect a key has been compromised — issue a new key from the dashboard and invalidate the old one.

## Error responses

| Status | Meaning |
|--------|---------|
| `401 Unauthorized` | Key is missing or malformed |
| `403 Forbidden` | Key is valid but does not have access to this endpoint or plan tier |
| `422 Unprocessable Entity` | Request body failed validation — check the `detail` field for field-level errors |
| `429 Too Many Requests` | Rate limit exceeded for your plan tier |


========================================================================
# Sandbox & Interactive Testing
Source: https://docs.padstats.io/docs/getting-started/sandbox
========================================================================

# Sandbox & Interactive Testing

## Scalar interactive console

A live interactive console is available directly on the API server at `/docs/scalar`. You can type in any address, fill out request parameters, and execute real API calls in your browser — no code required.

Every endpoint in the [API Reference](/docs/api/padstats-intelligence-api) also includes a **Try It** panel where you can send requests inline.

## Using a sandbox API key

:::warning
Do not paste your production API key into browser-based tools. Use your **sandbox key** for all interactive testing.
:::

Your sandbox key is available in the [dashboard](https://dashboard.padstats.io) under **API Keys → Sandbox**. It has the same endpoint access as your production key but is rate-limited and isolated from production billing.

## Testing with curl

All examples in this documentation use `curl`. The fastest way to test any endpoint is to copy an example, replace `YOUR_API_KEY`, and run it in your terminal.

```bash
# Verify your key works
curl https://api.padstats.io/health -H "X-API-Key: YOUR_API_KEY"
# Expected: {"status": "healthy", "version": "..."}
```

## Postman collection

A Postman collection with all 28 endpoints is available to download and import directly:

**[Download padstats-api.postman_collection.json](/padstats-api.postman_collection.json)**

After importing, set the `apiKey` collection variable to your API key and the `baseUrl` to `https://api.padstats.io`. All requests will pick up those values automatically.


========================================================================
# Property Valuation (AVM)
Source: https://docs.padstats.io/docs/guides/property-valuation
========================================================================

# Property Valuation

The PadStats AVM (Automated Valuation Model) produces instant property valuations using an ensemble of XGBoost, LightGBM, and CatBoost models trained on local sale comparables and property attributes.

## Endpoints

| Endpoint | Description |
|----------|-------------|
| `POST /v1/avm/property` | Single-family, townhome, condo, and small multifamily (2–4 unit) |
| `GET /v1/avm/property` | Same, via query parameters |
| `POST /v1/avm/rental` | Rental rate estimates per unit |
| `GET /v1/avm/rental` | Same, via query parameters (single unit) |
| `POST /v1/avm/multifamily` | Large multifamily buildings (5+ units) |
| `GET /v1/avm/multifamily` | Same, via query parameters |
| `POST /v1/avm/batch/property` | Async batch — submit up to 500 properties |
| `POST /v1/avm/batch/rental` | Async batch — rental |
| `POST /v1/avm/batch/multifamily` | Async batch — multifamily |
| `GET /v1/avm/batch/{job_id}` | Poll batch job status and retrieve results |

---

## Property AVM

### Minimal request

The minimum required fields are a location plus bedrooms and bathrooms:

```bash
curl -X POST https://api.padstats.io/v1/avm/property \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "456 Oak Ave, Tampa, FL 33602",
    "total_bedrooms": 3,
    "total_bathrooms": 2
  }'
```

### Full request with all fields

```json
{
  "address": "456 Oak Ave, Tampa, FL 33602",
  "total_bedrooms": 3,
  "total_bathrooms": 2,
  "living_area": 1650,
  "lot_size": 6500,
  "year_built": 2004,
  "property_type": "houses",
  "has_private_pool": true,
  "has_basement": false,
  "central_air": true,
  "garage_spaces": 2,
  "num_stories": 1,
  "condition_score": 3.5,
  "walk_score": 62,
  "radius_mi": 5.0,
  "lookback_months": 12,
  "num_comparables": 5
}
```

### Request fields

**Location** — provide one of `address` or (`latitude` + `longitude`):

| Field | Type | Description |
|-------|------|-------------|
| `address` | string | Full street address |
| `latitude` | float | Latitude (-90 to 90) |
| `longitude` | float | Longitude (-180 to 180) |

**Property fields:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `total_bedrooms` | int | Yes | Number of bedrooms (0–50) |
| `total_bathrooms` | float | Yes | Number of bathrooms (0–50) |
| `living_area` | int | No | Living area in sqft |
| `lot_size` | int | No | Lot size in sqft |
| `year_built` | int | No | Year built (1800–2030) |
| `property_type` | string | No | `houses`, `townhomes`, `condos`, `small_multifamily` |
| `total_units` | int | No | Units in building (1–4). For `small_multifamily`, defaults to 2 if omitted. |
| `has_private_pool` | bool | No | Default: `false` |
| `has_basement` | bool | No | Default: `false` |
| `central_air` | bool | No | Default: `false` |
| `garage_spaces` | int | No | Default: `0` |
| `num_stories` | int | No | 1–5 |
| `condition_score` | float | No | 0–5 scale (0 = poor, 5 = excellent) |
| `walk_score` | int | No | 0–100 |

**Search parameters:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `radius_mi` | float | 5.0 | Search radius for comparables (0.1–10.0 miles) |
| `lookback_months` | int | — | Months to look back for sale comparables (1–36) |
| `num_comparables` | int | 0 | Comparable properties to return (0–20). Set to `0` to skip the comparables query and get the fastest response. |
| `date` | string | today | As-of date for the valuation (`YYYY-MM-DD`) |

### Response

```json
{
  "address_info": {
    "formatted_address": "456 Oak Ave, Tampa, FL 33602",
    "street_address": "456 Oak Ave",
    "city": "Tampa",
    "state": "Florida",
    "state_code": "FL",
    "county": "Hillsborough County",
    "postal_code": "33602",
    "latitude": 27.9478,
    "longitude": -82.4584,
    "geohash8": "dhvrgkqp",
    "census_geoids": {
      "state_fips": "12",
      "county_fips": "057",
      "tract_fips": "010100",
      "block_fips": "1"
    }
  },
  "valuation": {
    "point_value": 412000,
    "confidence_interval_95": {
      "lower": 381000,
      "upper": 443000
    },
    "box_plot_params": {
      "min": 350000,
      "q1": 390000,
      "median": 410000,
      "q3": 435000,
      "max": 480000
    },
    "probabilistic_distribution": {
      "mean": 412000,
      "std": 31000,
      "median": 410000
    },
    "model_predictions": {
      "xgboost": 408000,
      "lightgbm": 415000,
      "catboost": 413000
    }
  },
  "comparables": {
    "properties": [ ... ],
    "statistics": { ... }
  }
}
```

### `property_type` values

| Value | Description |
|-------|-------------|
| `houses` | Single-family detached homes |
| `townhomes` | Attached townhouses |
| `condos` | Condominium units |
| `small_multifamily` | 2–4 unit properties |

:::tip
When `property_type` is `small_multifamily` and `total_units` is omitted or set to `1`, the API defaults `total_units` to `2`. Always pass the actual unit count when you have it.
:::

---

## Rental AVM

Returns estimated monthly rent for one or more units in a property.

```json
{
  "address": "789 Elm St, Nashville, TN 37201",
  "property_type": "small_multifamily",
  "total_units": 4,
  "central_air": true,
  "in_unit_laundry": true,
  "off_street_parking": true,
  "units": [
    { "bedrooms": 2, "bathrooms": 1, "size": 900 },
    { "bedrooms": 1, "bathrooms": 1, "size": 650 }
  ]
}
```

The `units` array accepts individual unit specs. Each unit takes `bedrooms` (int), `bathrooms` (float), `size` (sqft, optional), and `fully_furnished` (bool, default `false`).

For a **GET request** (single-unit shorthand), pass `bedrooms` and `bathrooms` as query parameters directly — no `units` array needed:

```bash
curl "https://api.padstats.io/v1/avm/rental?address=789+Elm+St,+Nashville,+TN+37201&bedrooms=2&bathrooms=1&size=900&property_type=houses" \
  -H "X-API-Key: YOUR_API_KEY"
```

---

## Multifamily AVM

For buildings with **5 or more units**. Returns a whole-building valuation.

```json
{
  "address": "100 Harbor Blvd, Miami, FL 33132",
  "total_bedrooms": 24,
  "total_bathrooms": 24,
  "total_units": 12,
  "living_area": 14400,
  "year_built": 1985,
  "num_stories": 3,
  "central_air": true
}
```

:::note
`total_units` is **required** for the multifamily endpoint and must be **≥ 5**. Use the property AVM for 2–4 unit buildings.
:::

---

## Performance tips

- `num_comparables: 0` skips the comparables database query — use this for batch workloads where you only need the valuation, not comparable listings.
- For single properties, typical response times are 1–3 seconds.
- For large volumes, use the [batch endpoints](./batch-processing).


========================================================================
# Batch Processing
Source: https://docs.padstats.io/docs/guides/batch-processing
========================================================================

# Batch Processing

For high-volume workloads, the batch endpoints let you submit up to **500 properties per job** asynchronously. Instead of waiting for each valuation synchronously, you submit a job, receive a `job_id`, and poll for completion.

## Endpoints

| Endpoint | Description |
|----------|-------------|
| `POST /v1/avm/batch/property` | Submit a property valuation batch |
| `POST /v1/avm/batch/rental` | Submit a rental valuation batch |
| `POST /v1/avm/batch/multifamily` | Submit a multifamily valuation batch |
| `GET /v1/avm/batch/{job_id}` | Poll job status and retrieve results |

---

## Step 1 — Submit a batch job

```bash
curl -X POST https://api.padstats.io/v1/avm/batch/property \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notify_url": "https://yourserver.com/webhooks/avm",
    "properties": [
      {
        "property_id": "ref-001",
        "location": { "address": "123 Main St, Austin, TX 78701" },
        "search_params": { "radius_mi": 5.0, "num_comparables": 0 },
        "property_fields": {
          "total_bedrooms": 3,
          "total_bathrooms": 2,
          "living_area": 1800,
          "year_built": 1995,
          "property_type": "houses"
        }
      },
      {
        "property_id": "ref-002",
        "location": { "address": "456 Oak Ave, Tampa, FL 33602" },
        "search_params": { "radius_mi": 5.0, "num_comparables": 0 },
        "property_fields": {
          "total_bedrooms": 4,
          "total_bathrooms": 3,
          "living_area": 2400,
          "year_built": 2010,
          "property_type": "houses"
        }
      }
    ]
  }'
```

### Batch request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `properties` | array | Yes | Array of property objects (max 500) |
| `properties[].property_id` | string | No | Your reference ID — echoed back in results |
| `properties[].location` | object | Yes | `address` or `latitude` + `longitude` |
| `properties[].search_params` | object | No | `radius_mi`, `num_comparables`, `lookback_months`, `date` |
| `properties[].property_fields` | object | Yes | Same fields as the single-property AVM |
| `notify_url` | string | No | Webhook URL — called when the job completes |

### Response (HTTP 202 Accepted)

```json
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "avm_type": "property",
  "total": 2,
  "created_at": "2026-03-16T14:32:01.123Z",
  "status_url": "/v1/avm/batch/f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "notify_url": "https://yourserver.com/webhooks/avm"
}
```

Use `status_url` as the polling path — it's the same as `GET /v1/avm/batch/{job_id}` pre-formatted for convenience.

---

## Step 2 — Poll for completion

```bash
curl "https://api.padstats.io/v1/avm/batch/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "X-API-Key: YOUR_API_KEY"
```

### In-progress response

```json
{
  "job_id": "f47ac10b-...",
  "status": "running",
  "total": 500,
  "completed": 312,
  "failed": 0,
  "progress_pct": 62.4
}
```

### Completed response

```json
{
  "job_id": "f47ac10b-...",
  "status": "complete",
  "total": 500,
  "completed": 498,
  "failed": 2,
  "progress_pct": 100.0,
  "completed_at": "2026-03-16T14:35:44.789Z",
  "updated_at": "2026-03-16T14:35:44.789Z",
  "webhook_delivered": true,
  "results": [
    {
      "index": 0,
      "property_id": "ref-001",
      "status": "complete",
      "data": {
        "valuation": {
          "point_value": 487000,
          "confidence_interval_95": { "lower": 452000, "upper": 522000 }
        }
      }
    },
    {
      "index": 1,
      "property_id": "ref-002",
      "status": "error",
      "error": "Unable to geocode address"
    }
  ]
}
```

---

## Webhooks

If you supply a `notify_url`, PadStats will `POST` the completed job result to that URL when the job finishes. The webhook payload is identical to the polling response above.

Webhook delivery is retried up to **3 times** with exponential backoff (2s → 4s → 8s) on failure. Check `webhook_delivered: true/false` in the polling response to confirm delivery.

---

## Performance guidance

| Scenario | Recommended config |
|----------|--------------------|
| Need only valuations, no comparable listings | `num_comparables: 0` — 2–3s per 8 properties |
| Need comparable properties returned | `num_comparables: 5` — 5–7s per 8 properties |
| Maximum throughput | `num_comparables: 0`, `radius_mi: 3.0` |

Setting `num_comparables: 0` is the most impactful single optimization — it skips the comparables database query entirely.

---

## Polling pattern (Python)

```python
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.padstats.io"

def poll_batch(job_id, interval=10, timeout=600):
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/avm/batch/{job_id}",
            headers={"X-API-Key": API_KEY},
        )
        job = r.json()
        print(f"Status: {job['status']} — {job.get('progress_pct', 0):.1f}%")
        if job["status"] in ("complete", "failed"):
            return job
        time.sleep(interval)
    raise TimeoutError("Batch job did not complete within timeout")
```


========================================================================
# Environmental Risk
Source: https://docs.padstats.io/docs/guides/environmental-risk
========================================================================

# Environmental Risk

PadStats provides FEMA flood zone classifications, USDA wildfire risk scores, and NOAA storm surge zone data. All three endpoints accept the same location input (address or coordinates) and can be combined in a single [Comprehensive request](/docs/api/comprehensive-v-1-comprehensive-post).

## Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /v1/flood-zone` | FEMA flood zone classification |
| `POST /v1/flood-zone` | Same, via JSON body |
| `GET /v1/fire-risk` | USDA wildfire risk score and category |
| `POST /v1/fire-risk` | Same, via JSON body |
| `GET /v1/storm-surge` | Hurricane storm surge depths (categories 1–5) |
| `POST /v1/storm-surge` | Same, via JSON body |
| `GET /v1/natural-hazards` | Combined natural hazard indices by geography |

---

## Flood Zone

Returns the FEMA DFIRM flood zone classification for a location.

```bash
curl "https://api.padstats.io/v1/flood-zone?address=1234+Bayshore+Dr,+Miami+Beach,+FL+33139" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response

```json
{
  "location_info": { ... },
  "fema_flood_zone": {
    "fld_zone": "AE",
    "sfha": true,
    "sfha_tf": "T",
    "static_bfe": 8.0,
    "user_label": "High Risk",
    "annual_risk": "1 %",
    "version_id": "12086C0306L",
    "fld_ar_id": "FL12086C_305",
    "study_typ": "FE",
    "v_datum": "NAVD88",
    "len_unit": "Feet",
    "source_cit": "STUDY1"
  }
}
```

Additional response fields:

| Field | Description |
|-------|-------------|
| `study_typ` | FEMA flood study type (e.g., `FE` = full engineering study) |
| `v_datum` | Vertical datum used for BFE (typically `NAVD88` or `NGVD29`) |
| `len_unit` | Unit of length for elevation values (`Feet` or `Meters`) |
| `source_cit` | FEMA source citation identifier for the flood study |

### Flood zone codes

| Code | Description | Risk |
|------|-------------|------|
| `AE` | Special Flood Hazard Area with Base Flood Elevation data | High — 1% annual chance |
| `A` | Special Flood Hazard Area (no BFE data available) | High — 1% annual chance |
| `AH` | Shallow flooding area, 1–3 ft depth | High |
| `AO` | Sheet flow area, 0–3 ft depth | High |
| `VE` | Coastal high hazard with BFE (wave action, 3+ ft velocity) | Very High |
| `V` | Coastal high hazard (no BFE data) | Very High |
| `X` | Minimal flood hazard, outside 500-year floodplain | Low |
| `B` | Moderate flood hazard (between 100-year and 500-year) | Moderate |
| `C` | Minimal flood hazard | Low |

`sfha: true` means the property is in a Special Flood Hazard Area — FEMA-regulated flood insurance is typically required for federally-backed mortgages on these properties.

---

## Fire Risk

Returns the USDA Forest Service wildfire burn probability and risk category.

```bash
curl "https://api.padstats.io/v1/fire-risk?address=789+Hillside+Rd,+Boulder,+CO+80302" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response

```json
{
  "location_info": { ... },
  "fire_risk": {
    "has_fire_risk": true,
    "risk_value": 0.0032,
    "risk_level": 7,
    "risk_category": "high",
    "risk_category_display": "High",
    "description": "High wildfire risk area. Annual burn probability 1-in-312.",
    "annual_chance": "1-in-312",
    "return_period_years": 312,
    "data_source": "USDA Forest Service",
    "location": { "latitude": 40.015, "longitude": -105.27 }
  }
}
```

### Risk levels

| Level | Category | Annual Burn Probability |
|-------|----------|------------------------|
| 0 | No data | — |
| 1–3 | Low | < 1-in-10,000 |
| 4–6 | Moderate | 1-in-10,000 to 1-in-1,000 |
| 7–9 | High | 1-in-1,000 to 1-in-100 |
| 10–11 | Extreme | > 1-in-100 |

`risk_value` is the raw annual burn probability (0–1 scale). `risk_level` maps this to an 11-point categorical scale for easier comparison.

---

## Storm Surge

Returns NOAA storm surge depth estimates for hurricane categories 1–5.

```bash
curl "https://api.padstats.io/v1/storm-surge?address=901+Ocean+Dr,+Naples,+FL+34102" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response

```json
{
  "location_info": { ... },
  "storm_surge": {
    "in_surge_zone": true,
    "highest_risk_level": 3,
    "highest_risk_category": "6-9 ft",
    "max_surge_depth_ft": 9,
    "zones": [
      { "category": 1, "depth_ft": 3, "depth_category": "1-3 ft", "risk_level": 1 },
      { "category": 2, "depth_ft": 5, "depth_category": "3-6 ft", "risk_level": 2 },
      { "category": 3, "depth_ft": 9, "depth_category": "6-9 ft", "risk_level": 3 },
      { "category": 4, "depth_ft": 14, "depth_category": "9-18 ft", "risk_level": 4 },
      { "category": 5, "depth_ft": 20, "depth_category": "18+ ft", "risk_level": 4 }
    ]
  }
}
```

### Hurricane category reference

| Category | Wind Speed | Typical Surge |
|----------|-----------|---------------|
| 1 | 74–95 mph | 2–5 ft |
| 2 | 96–110 mph | 4–8 ft |
| 3 | 111–129 mph | 7–12 ft |
| 4 | 130–156 mph | 11–17 ft |
| 5 | 157+ mph | 17+ ft |

`in_surge_zone: false` means no storm surge data exists for this location — typically inland areas not at risk from coastal flooding.

---

## Natural Hazards (combined indices)

Returns pre-computed natural hazard risk indices aggregated at the county and census tract level. Useful for comparing risk profiles across geographies rather than point-in-time assessments.

```bash
curl "https://api.padstats.io/v1/natural-hazards?address=500+Congress+Ave,+Austin,+TX+78701" \
  -H "X-API-Key: YOUR_API_KEY"
```

The response includes indexed scores (0–100) for flood, fire, storm surge, wind, and seismic risk at both the county and tract geography levels. See the [Socioeconomic Data guide](./socioeconomic-data) for index interpretation.

---

## Getting all risk data in one call

Use the [Comprehensive endpoint](/docs/api/comprehensive-v-1-comprehensive-post) (`POST /v1/comprehensive`) to fetch flood zone, fire risk, and storm surge in a single request:

```json
{
  "requests": ["flood-zone", "fire-risk", "storm-surge"],
  "address": "901 Ocean Dr, Naples, FL 34102"
}
```


========================================================================
# Socioeconomic & Demographics
Source: https://docs.padstats.io/docs/guides/socioeconomic-data
========================================================================

# Socioeconomic & Demographics

PadStats provides ACS census demographics, FBI NIBRS crime statistics, and composite socioeconomic indices — all queryable by address, coordinates, or Census GEOID.

## Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /v1/census-data` | ACS census variables by address or coordinates |
| `POST /v1/census-data` | Same, via JSON body |
| `POST /v1/census-data/by-geoid` | Census data by Census GEOID |
| `GET /v1/crime-data` | Crime incidents within a radius |
| `POST /v1/crime-data` | Same, via JSON body |
| `GET /v1/socioeconomic-data` | Composite socioeconomic indices |
| `POST /v1/socioeconomic-data` | Same, via JSON body |
| `GET /v1/socioeconomic-data/by-geoid` | Socioeconomic data by Census GEOID |

---

## Census Data

Returns ACS (American Community Survey) variables at one or more geographic levels.

```bash
curl -X POST https://api.padstats.io/v1/census-data \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "500 Congress Ave, Austin, TX 78701",
    "years": [2023],
    "geographies": ["block_group", "tract"]
  }'
```

### Request fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `address` / `latitude` + `longitude` | — | — | Location |
| `years` | int[] | `[2023]` | ACS data years (2019–2023) |
| `geographies` | string[] | `["block_group"]` | `county`, `cousub`, `tract`, `block_group` |
| `census_keys` | string[] | predefined set | Specific ACS variable codes; omit for the default set |

### Response structure

```json
{
  "location_info": { ... },
  "census_geoids": {
    "state_fips": "48",
    "county_fips": "453",
    "cousub_fips": "24000",
    "tract_fips": "002100",
    "block_fips": "1",
    "geoid": "480450021001"
  },
  "acs_data": [
    {
      "year": 2023,
      "geography_level": "block_group",
      "name": "Block Group 1, Census Tract 21, Travis County, Texas",
      "variables": {
        "B01003_001E": {
          "category": "demographics",
          "subcategory": "population",
          "value_type": "total",
          "value": 1482
        },
        "B19013_001E": {
          "category": "economics",
          "subcategory": "income",
          "value_type": "currency",
          "value": 78500
        }
      }
    }
  ]
}
```

### Common ACS variable groups

| Table | Description |
|-------|-------------|
| `B01002` | Median age by sex |
| `B01003` | Total population |
| `B03002` | Hispanic or Latino origin by race |
| `B15003` | Educational attainment (25+) |
| `B19001` | Household income distribution |
| `B19013` | Median household income |
| `B19082` | Gini index of income inequality |
| `B25001` | Total housing units |
| `B25024` | Units in structure |
| `B25035` | Median year structure built |

### Querying by GEOID

If you already have a Census GEOID (e.g., from a previous response), use the direct lookup:

```json
{
  "geoid": "480453002100",
  "geography": "tract",
  "years": [2023]
}
```

---

## Crime Data

Returns crime incidents from FBI NIBRS reporting within a specified radius.

```bash
curl -X POST https://api.padstats.io/v1/crime-data \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "500 Congress Ave, Austin, TX 78701",
    "radius_mi": 1.0,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "include_crime_summary": true
  }'
```

### Request fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `radius_mi` | float | 1.0 | Search radius (max 6.0 miles) |
| `start_date` | string | — | Start date (`YYYY-MM-DD`) |
| `end_date` | string | — | End date (`YYYY-MM-DD`) |
| `include_crime_summary` | bool | `true` | Include aggregated summary statistics |
| `include_crime_details` | bool | `false` | Include extended fields: `agency`, `victim_sex`, `victim_race`, `victim_age_group`, `offender_sex`, `offender_race`, `offender_age_group`, `crime_against`, `reference_id` |
| `offense_categories` | string[] | all | Filter to specific NIBRS offense categories |
| `sort_by` | string | `recency` | `recency` or `distance` |
| `limit` | int | 100 | Max records returned (up to 1,000) |
| `cursor` | string | — | Pagination cursor from previous response |

### Response

```json
{
  "query": {
    "latitude": 30.2672, "longitude": -97.7431,
    "radius_mi": 1.0
  },
  "summary": {
    "total": 87,
    "by_category": {
      "Theft": 34,
      "Assault": 18,
      "Burglary": 12,
      "Vehicle Theft": 9
    },
    "by_severity": {
      "minor": 10, "low": 28, "moderate": 31, "high": 15, "severe": 3
    }
  },
  "crime_instances": [
    {
      "id": 10482910,
      "datetime": "2024-11-14T22:35:00",
      "lat": 30.2680,
      "lon": -97.7418,
      "address": "500 Block of Congress Ave",
      "distance_mi": 0.08,
      "offense_code": "23H",
      "offense_category": "Theft",
      "offense_description": "Theft from vehicle",
      "crime_type": "property",
      "severity": "Moderate"
    }
  ],
  "meta": {
    "count": 87,
    "truncated": false,
    "next_cursor": null,
    "compute_ms": 143
  }
}
```

### Severity levels

| Level | Description |
|-------|-------------|
| Minor | Non-contact, low-impact offenses |
| Low | Property crimes with limited direct harm |
| Moderate | Property crimes or non-severe person crimes |
| High | Violent crimes or significant property damage |
| Severe | Homicide, sexual assault, armed robbery |

---

## Socioeconomic Indices

Returns composite indices (0–100 scale) derived from ACS census data, compared against local, county, state, and national baselines.

```bash
curl -X POST https://api.padstats.io/v1/socioeconomic-data \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "500 Congress Ave, Austin, TX 78701",
    "year": 2023,
    "geographies": ["tract", "county"],
    "include_grades": true
  }'
```

### Request fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `year` | int | 2023 | ACS data year (2019–2023) |
| `geographies` | string[] | `["all"]` | `county`, `cousub`, `tract`, `block_group`, `all` |
| `include_grades` | bool | `false` | Return letter grades (A–F) alongside numeric indices |

### Socioeconomic indices returned

| Index | What it measures |
|-------|-----------------|
| Income & Employment | Median household income, employment rate |
| Education & Employment | Educational attainment, workforce participation |
| Diversity | Racial and ethnic diversity |
| Poverty | Poverty rate relative to comparison area |
| Age / Family | Age distribution, household composition |

### Natural hazard indices

The response also includes natural hazard indices at the same geographic levels:

| Index | What it measures |
|-------|-----------------|
| Flood Risk | Composite FEMA flood exposure |
| Storm Surge | Coastal storm surge exposure |
| Fire Risk | USDA wildfire burn probability |
| Wind / Hurricane | Wind hazard exposure |
| Seismic Risk | Earthquake risk |
| Severe Weather | Tornado, hail, and severe storm exposure |

### Reading the indices

All indices are on a **0–100 scale** relative to a comparison basis:

- `100` = best possible outcome for this index (e.g., lowest poverty, lowest flood risk)
- `0` = worst possible outcome
- The comparison basis is shown in each result: `cousub` (local), `county`, `state`, or `country`

When `include_grades: true`, letter grades (A through F) are attached to each index based on the same comparison.


========================================================================
# Coverage
Source: https://docs.padstats.io/docs/understanding-the-data/coverage
========================================================================

# Geographic Coverage

Coverage varies by data product. All endpoints accept addresses anywhere in the United States, but will return partial or empty data for locations outside the covered area.

## Coverage by endpoint

| Endpoint | Coverage |
|----------|---------|
| Property AVM | Contiguous United States (varies by local market data density) |
| Rental AVM | Contiguous United States (varies by local rental listing density) |
| Multifamily AVM | Major metro areas and markets with sufficient multifamily sale history |
| Flood Zone | Contiguous United States (FEMA DFIRM mapped areas) |
| Fire Risk | Contiguous United States |
| Storm Surge | Atlantic and Gulf Coast counties at hurricane risk |
| Census Data | Entire United States (all 50 states + D.C.) |
| Crime Data | Jurisdictions participating in FBI NIBRS reporting |
| Socioeconomic Indices | Entire United States (block group through county) |
| Natural Hazards | Entire United States (tract and county levels) |

## AVM coverage notes

AVM accuracy is a function of **local comparable sale density**. Urban and suburban markets with active MLS data produce tighter confidence intervals. Rural areas, very high-end properties, or markets with infrequent sales will have wider confidence intervals.

The `confidence_interval_95` in the AVM response reflects model uncertainty at the specific location and price point — a wide interval is a signal that the local market has limited comparable data.

## Flood zone coverage notes

FEMA DFIRM mapping covers areas where flood risk studies have been completed. Some rural areas may be mapped with older, less detailed methods (Zone A without Base Flood Elevation) or may not have been studied at all. FEMA's Flood Map Service Center is the authoritative source for the most current FIRM maps.

## Storm surge coverage notes

Storm surge data is available only in coastal areas modeled by NOAA's SLOSH system — primarily Atlantic and Gulf of Mexico coastal counties. Locations without storm surge risk (inland areas) return `in_surge_zone: false`.

## Crime data coverage notes

NIBRS participation is voluntary at the agency level. Major cities and suburban law enforcement agencies generally participate; some rural and tribal jurisdictions do not. The absence of crime records for a location should not be interpreted as "zero crime" — it may mean the reporting agency does not submit to NIBRS.


========================================================================
# Data Sources
Source: https://docs.padstats.io/docs/understanding-the-data/data-sources
========================================================================

# Data Sources

Every PadStats endpoint draws from authoritative, regularly-updated data sources. Understanding the provenance of each data type helps you evaluate accuracy, coverage, and appropriate use cases.

## Property Valuations (AVM)

| Component | Source |
|-----------|--------|
| Sale comparables | MLS and public record transaction data |
| Property attributes | County assessor and recorder records |
| ML model ensemble | XGBoost, LightGBM, CatBoost trained on local sale comparables |
| Walk Score | [Walk Score®](https://www.walkscore.com) (when provided in request) |

The AVM produces a point estimate from the ensemble median and a probabilistic distribution based on comparable sale variance in the subject property's local market. The 95% confidence interval reflects model uncertainty at the specific price point and location.

## Flood Zone

| Component | Source |
|-----------|--------|
| Flood zone boundaries | FEMA DFIRM (Digital Flood Insurance Rate Maps) |
| Base Flood Elevation | FEMA DFIRM BFE data |
| SFHA designation | FEMA National Flood Hazard Layer |

FEMA DFIRM data is the official source used by lenders, insurers, and municipalities for flood insurance requirements. `sfha: true` indicates a Special Flood Hazard Area — properties in these zones are subject to mandatory flood insurance requirements for federally-backed mortgages.

## Fire Risk

| Component | Source |
|-----------|--------|
| Burn probability | USDA Forest Service — [Wildfire Risk to Communities](https://wildfirerisk.org) |
| Risk classification | USDA National Risk Index methodology |

The USDA fire risk data represents the **annual probability of a wildfire burning through a given location**, derived from fire simulation modeling across fuel, weather, and topographic data. Values are available for the contiguous United States.

## Storm Surge

| Component | Source |
|-----------|--------|
| Storm surge zones | NOAA SLOSH (Sea, Lake, and Overland Surges from Hurricanes) model |
| Hurricane category bands | National Hurricane Center SLOSH Basin data |

NOAA's SLOSH model simulates storm surge flooding from hurricane category 1–5 scenarios. Coverage is limited to **coastal areas** at risk from Atlantic and Gulf of Mexico hurricanes. Areas without storm surge data return `in_surge_zone: false`.

## Census Data

| Component | Source |
|-----------|--------|
| Demographic variables | U.S. Census Bureau — American Community Survey (ACS) 5-Year Estimates |
| Available years | 2019, 2020, 2021, 2022, 2023 |
| Geographic levels | Block group, census tract, county subdivision, county |

ACS 5-year estimates aggregate survey responses over a 5-year period to produce statistically reliable estimates at small geographies (block group, tract). The trade-off is that the data represents a rolling 5-year average, not a single-point-in-time snapshot.

## Crime Data

| Component | Source |
|-----------|--------|
| Crime incidents | FBI NIBRS (National Incident-Based Reporting System) |
| Offense classification | NIBRS offense codes and categories |
| Severity classification | PadStats severity mapping over NIBRS offense types |

NIBRS is the FBI's primary crime data collection program. Not all law enforcement agencies participate in NIBRS — coverage varies by jurisdiction. Absence of crime data for a location may indicate limited agency reporting rather than absence of crime.

## Socioeconomic Indices

| Component | Source |
|-----------|--------|
| Underlying variables | ACS census data (same as Census Data endpoint) |
| Index construction | PadStats composite scoring methodology |
| Comparison baselines | Local (county subdivision), county, state, national |

Socioeconomic indices are composite scores computed from ACS variables using a weighted methodology that accounts for the relative importance and variance of each input variable. Scores are normalized (0–100) relative to the selected comparison basis.


========================================================================
# Update Frequency
Source: https://docs.padstats.io/docs/understanding-the-data/update-frequency
========================================================================

# Update Frequency

Data freshness varies by product. Real-time queries (AVM, flood zone, fire risk) reflect the most recently ingested dataset. Time-series products (census, crime) cover specific survey years.

## Update cadence by product

| Product | Update Frequency | Current Dataset |
|---------|-----------------|-----------------|
| Property AVM models | Quarterly retraining on new sale data | Q1 2026 |
| Rental AVM models | Quarterly retraining on new rental listings | Q1 2026 |
| Flood Zone (FEMA DFIRM) | As FEMA issues map amendments (LOMA/LOMR) | Updated continuously |
| Fire Risk (USDA) | Annual update cycle | 2023 release |
| Storm Surge (NOAA SLOSH) | Updated when NOAA revises basin models | 2023 models |
| Census Data (ACS) | Annual — new 5-year estimates released each December | 2019–2023 ACS |
| Crime Data (NIBRS) | Annual — FBI releases prior-year data each fall | 2019–2023 NIBRS |
| Socioeconomic Indices | Refreshed when new ACS data is available | 2023 ACS |

## AVM model currency

AVM models are retrained quarterly on rolling sale transaction data. Model version and training date are not currently exposed in the API response but are tracked internally by model region.

## ACS 5-year estimates

The ACS 5-year estimates represent data collected across a 5-year survey window. For example, the 2023 ACS covers respondents from January 2019 through December 2023. This means the `2023` dataset does not represent a single snapshot of 2023 — it is an aggregate over five years. The trade-off is greater statistical precision at small geographies (block group, census tract).

When `year: 2023` is the default across the API, it refers to the most recently available ACS 5-year dataset.

## Flood map amendments

FEMA issues map amendments (Letters of Map Amendment — LOMA, and Letters of Map Revision — LOMR) on a rolling basis. The flood zone data in PadStats reflects the official DFIRM maps as of the last ingestion date. Properties that have received recent LOMAs or LOMRs should be verified directly against FEMA's [Flood Map Service Center](https://msc.fema.gov).