# Markets

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

A market series is one number tracked over time for a place: how many people work there, how much is being built, how many homes were finished. Markets returns each series as a list of periods and values, so you can chart a trend or compare two places. Markets are free.

```endpoint
GET /v1/markets
```

## What you can ask for

Each metric has its own period, set by its source: some are counted every quarter, some every year, and some are a single latest snapshot.

| Group | Metric | What it is | Period |
|---|---|---|---|
| Sales | `deal-count` | Sales | Quarterly |
| | `sales-volume` | Sales volume | Quarterly |
| | `sales-volume-12mo` | Sales volume over the last 12 months | Quarterly |
| | `average-sale-price` | Average deal size | Quarterly |
| | `price-per-sf` | Sale price per square foot | Quarterly |
| | `recorded-transfers` | Recorded transfers | Quarterly |
| | `inventory` | Building inventory | Quarterly |
| Development | `development-pipeline` | Projects in the development pipeline | Snapshot |
| | `pipeline-housing-units` | Net housing units in the pipeline | Snapshot |
| | `pipeline-commercial-sf` | Net commercial space in the pipeline | Snapshot |
| | `housing-completions` | Net housing units completed | Yearly |
| Economy | `employment` | Private-sector employment | Yearly |
| | `establishments` | Private-sector establishments | Yearly |
| | `weekly-wage` | Average weekly private-sector wage | Yearly |
| | `cbp-employment`, `cbp-establishments` | Employment and establishments with paid employees (County Business Patterns) | Yearly |
| | `workplace-jobs` | Modeled jobs located in the area | Yearly |
| | `population` | Estimated resident population | Yearly |
| | `housing-stock` | Estimated total housing units | Yearly |
| Commercial space | `commercial-vacancy-filings` | Reported vacant commercial spaces | Yearly |
| | `commercial-space-filings` | Commercial-space filings | Yearly |
| Mobility | `bart-activity`, `bart-exits` | BART entries and exits at San Francisco stations | Monthly |

Series are published for California and San Francisco market areas today. For other places, use [find](https://westkite.com/docs/api/find.md) to work from property records instead.

## Parameters

| Name | Type | Description |
|---|---|---|
| `metric` | string | Required. One or more metrics, comma-separated, up to 12: `records-properties`, `records-sales`, `records-sale-price`, `records-market-value`, `records-building-size`, `records-year-built`, `recorded-transfers`, `deal-count`, `sales-volume`, `sales-volume-12mo`, `average-sale-price`, `price-per-sf`, `inventory`, `development-pipeline`, `pipeline-housing-units`, `pipeline-commercial-sf`, `housing-completions`, `employment`, `establishments`, `weekly-wage`, `population`, `housing-stock`, `jobs-construction`, `jobs-manufacturing`, `jobs-retail`, `jobs-logistics`, `jobs-information`, `jobs-professional`, `jobs-healthcare`, `jobs-hospitality`, `cbp-employment`, `cbp-establishments`, `workplace-jobs`, `bart-activity`, `bart-exits`, `commercial-vacancy-filings`, `commercial-space-filings`. The table above explains the most used. |
| `area` | string | The market area, such as `san-francisco`. Add up to two more, comma-separated, to compare them with the first. Default `san-francisco`. Markets take `area`, not `in`. |
| `property_type` | string | Narrows pipeline series: `all`, `office`, `retail`, `industrial`, `multifamily`, `hospitality`. Default `all`. |
| `range` | string | How far back the rows go: `1y`, `3y`, `5y` or `10y` up to the latest period, or `all` for everything published. It sets the length, not the period: a quarterly metric over `3y` returns about 12 rows. Default `5y`. |

## Request

```curl
curl --get "https://api.westkite.com/v1/markets" \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  --data-urlencode "metric=employment,establishments" \
  --data-urlencode "area=san-francisco" \
  --data-urlencode "range=5y"
```

```typescript
const params = new URLSearchParams({ metric: "employment,establishments", area: "san-francisco", range: "5y" });
const res = await fetch(`https://api.westkite.com/v1/markets?${params}`, {
  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/markets",
    params={"metric": "employment,establishments", "area": "san-francisco", "range": "5y"},
    headers={"Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}"},
)
body = res.json()
```

## Response

```json 200
{
  "data": {
    "area": "san-francisco",
    "series": [
      {
        "metric": "employment",
        "unit": "jobs",
        "points": [
          { "period": "2024", "value": 612400 },
          { "period": "2025", "value": null }
        ]
      }
    ]
  },
  "missing": [
    { "field": "series[0].points[1]", "reason": "not_published", "note": "The year's annual average isn't published yet." }
  ],
  "billing": { "operation_id": "op_93aa…", "operation": "markets", "charged_usd": 0, "balance_usd": 9.98 },
  "request_id": "req_93aa…"
}
```

Each point is a period and its value. A period that isn't published yet comes back as `null`, with the reason in `missing`, never as zero. The full schema is in the [OpenAPI description](https://api.westkite.com/v1/openapi.json).

## Errors

| Code | When |
|---|---|
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | No `metric`, an unknown metric (the message lists the valid ones), a `property_type` or `range` it doesn't take, more than 12 metrics, or `in` (use `area`). |
