# Demographics

> Documentation index: [llms.txt](https://westkite.com/docs/llms.txt). Every page is also at its URL plus `.md`.

Returns population, households, income, jobs, housing and home lending for a named area or a ring around a property or point. $0.05 per report.

```endpoint
GET /v1/demographics
GET /v1/demographics/areas
```

## Parameters

Send `area`, or `property_id` or `lat` and `lng` for a ring.

| Name | Type | Description |
|---|---|---|
| `area` | string | `state-06`, `metro-12420`, `county-48453`, `place-0644000` or `zip-94105`. [Find an area](#find-an-area) by name. |
| `property_id` | string | A property ID, for a ring around it. |
| `lat`, `lng` | number | A point in the United States, for a ring around it. |
| `radius_m` | number | The ring's radius, 100 to 16,093 m (10 miles). Default 1,609 (one mile). |
| `max_cost_usd` | number | Refuse the call if it costs more. |

## Request

```curl
curl --get "https://api.westkite.com/v1/demographics" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "property_id=property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0" \
  --data-urlencode "radius_m=1609"
```

```typescript
const res = await fetch("https://api.westkite.com/v1/demographics?property_id=property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0&radius_m=1609", {
  headers: { Authorization: `Bearer ${process.env.WESTKITE_API_KEY}` },
});
const { data, missing } = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.westkite.com/v1/demographics",
    params={"property_id": "property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0", "radius_m": 1609},
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
body = res.json()
```

## Response

```json 200
{
  "data": {
    "area": { "id": "custom", "kind": "custom", "label": "Within 1 mile of 1840 Industrial Way", "blockGroups": 21 },
    "acs": {
      "scope": { "kind": "area", "label": "Within 1 mile of 1840 Industrial Way" },
      "latest": { "year": 2024, "population": 48210, "households": 18930, "medianHouseholdIncome": 86400, "medianGrossRent": 1640 }
    },
    "radius_m": 1609,
    "sources": [{ "id": "census-acs5", "label": "American Community Survey 5-year estimates", "publisher": "U.S. Census Bureau" }],
    "note": "Census ACS 5-year estimates, BLS jobs and wages, LODES workplace jobs and HMDA home-purchase loans, each with its own scope (the area, or the counties that stand in for it) and year. A missing section is unknown, not zero."
  },
  "missing": [],
  "billing": { "operation_id": "op_c3e0…", "operation": "demographics_report", "charged_usd": 0.05, "balance_usd": 9.82 },
  "request_id": "req_c3e0…"
}
```

The figures above are an example, trimmed to a few fields. Each section names its `scope` and year. County-only sources describe a city, ZIP code or ring through the counties that stand in for it. A section that couldn't be filled is in `missing`, and an answer with no sections at all costs nothing.

| Section | Source |
|---|---|
| `acs` | American Community Survey 5-year estimates: population, households, income, age, rent, home values, tenure and commuting, with a ten-year trend |
| `jobs`, `labor` | BLS jobs, industries and wages (QCEW), and unemployment (LAUS) |
| `workplace` | Jobs at workplaces in the area (LEHD LODES) |
| `homeBuying` | Home-purchase mortgages by year (HMDA) |
| `rents` | HUD Fair Market Rents by bedroom count, studio to four bedrooms. A ZIP code takes its Small Area FMR; a ring around a property or point takes the Small Area FMR of the ZIP code at its centre, the site's own; other areas take their county's, labelled as county context |
| `permits`, `homePrices`, `population`, `mortgage` | Census building permits, the FHFA house price index, population change and the 30-year mortgage rate |

## Find an area

```curl
curl --get "https://api.westkite.com/v1/demographics/areas" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "q=Austin"
```

Returns `areas`, each with the `id` that `area` takes, its `kind`, `label` and `population`. Free.

## Errors

| Code | When |
|---|---|
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | An `area` id in the wrong form, both an area and a point, or a `radius_m` out of range. |
| [`not_found`](https://westkite.com/docs/api/errors.md#not_found) | No published property with a location has that ID. |
| [`service_unavailable`](https://westkite.com/docs/api/errors.md#service_unavailable) | Demographics can't be read right now. Retry shortly. |
