Skip to main content

API

API Documentation

Public fixture-backed JSON endpoints for Housing BuildDesignHub market profiles.

About these endpoints

These endpoints expose production-loaded static fixture profiles. They do not provide live data, investment advice, legal advice, financial advice, or property-level assessment. Consumers should treat fixture data as illustrative; see /data-status for per-source freshness on every deploy.

Available endpoints

All endpoints respond with application/json and are statically prerendered. URLs do not carry a .json extension — the response content-type is still JSON.

Index

Lists every supported market with html and json URLs.

GET /api/markets ↗

Response model

Per-market response fields. Undefined values are omitted from the rendered JSON; consumers should treat missing keys as semantically absent rather than as null.

FieldTypeNotes
schemaVersion"1"Stable contract version. Consumers should pin to "1"; future shape changes will bump this.
generatedAtstring (ISO date)When the profile snapshot was prepared. Mirrors profile.updatedDate from the ETL run.
methodologyVersionstringMethodology contract used for the computed signals. See /methodology.
productionMode"static-fixture"Current production mode. Will be reconsidered if/when live ingestion is promoted.
liveDatafalseGuarded constant. This endpoint does not provide live data in this version.
marketobjectGeographic identity: id, name, slug, city, state, stateCode, countryCode, countyName, cbsaName (undefined fields are omitted).
profileobjectETL output: updatedDate, scores (0–100 composite signals), metrics (keyed by id), freshness, coverage.
sourcesarraySource attributions sorted by sourceId: sourceId, sourceName, agency, datasetName, sourceUrl, confidence, updateFrequency, provenance, latestReleaseDate, latestRetrievedAt.
caveatsstring[]Project-doctrine caveats emitted verbatim. Consumers must surface them when rendering responses.
linksobjectCross-references to html, dataStatus, methodology, dataSources, dataCatalog, privacy, changelog.

Example response

Excerpt from /api/markets/us-tx-austin. The live response contains additional metrics and source attribution entries.

{
  "schemaVersion": "1",
  "generatedAt": "2026-05-19",
  "methodologyVersion": "v5.0",
  "productionMode": "static-fixture",
  "liveData": false,
  "market": {
    "id": "us-tx-austin",
    "name": "Austin",
    "slug": "austin",
    "state": "Texas",
    "stateCode": "TX",
    "countryCode": "US",
    "countyName": "Travis County",
    "cbsaName": "Austin-Round Rock-Georgetown, TX"
  },
  "profile": {
    "updatedDate": "2026-05-19",
    "scores": { "affordability": 73, "supply": 100, "overall": 58 },
    "metrics": { "medianGrossRent": { "id": "medianGrossRent", "label": "Median gross rent", "unit": "USD/mo", "value": 1567, "asOf": "2018-2022", "sourceId": "census-acs" } },
    "freshness": { "provenance": "fixture", "freshness": "fresh", "retrievedAt": "2026-05-19", "note": "Fixture-backed snapshot." },
    "coverage": { "totalRequired": 18, "totalProvided": 18, "percent": 100, "missing": [] }
  },
  "sources": [ { "sourceId": "census-acs", "sourceName": "American Community Survey", "agency": "U.S. Census Bureau", "datasetName": "ACS 5-Year Estimates", "sourceUrl": "https://www.census.gov/programs-surveys/acs", "confidence": "high", "updateFrequency": "annually", "provenance": "fixture" } ],
  "caveats": [
    "Production JSON uses source-attributed static fixtures.",
    "This endpoint does not provide live data.",
    "Not investment, legal, financial, or property-level advice.",
    "Upstream public datasets retain their own licenses and terms."
  ],
  "links": { "html": "https://housing.builddesignhub.com/markets/us/texas/austin", "dataStatus": "https://housing.builddesignhub.com/data-status", "methodology": "https://housing.builddesignhub.com/methodology", "dataSources": "https://housing.builddesignhub.com/data-sources", "dataCatalog": "https://housing.builddesignhub.com/data-catalog", "privacy": "https://housing.builddesignhub.com/privacy", "changelog": "https://housing.builddesignhub.com/changelog" }
}

CSV export

Each market also exposes a CSV with one row per metric. Useful for spreadsheet ingestion and notebook analysis; same fixture data as the JSON profile.

Endpoint pattern

GET /api/markets/<market-id>/csv

Content-Type: text/csv; charset=utf-8. Content-Disposition: attachment; filename="<market-id>-housing-builddesignhub.csv". RFC 4180 quoting; CRLF line endings.

/api/markets/us-tx-austin/csv ↓/api/markets/us-fl-miami/csv ↓/api/markets/us-az-phoenix/csv ↓/api/markets/us-wa-seattle/csv ↓/api/markets/us-co-denver/csv ↓/api/markets/us-tn-nashville/csv ↓/api/markets/us-tx-dallas/csv ↓/api/markets/us-fl-tampa/csv ↓/api/markets/us-ca-los-angeles/csv ↓/api/markets/us-ca-san-diego/csv ↓/api/markets/us-ca-san-francisco/csv ↓/api/markets/us-ny-new-york/csv ↓/api/markets/us-ma-boston/csv ↓/api/markets/us-il-chicago/csv ↓/api/markets/us-ga-atlanta/csv ↓/api/markets/us-dc-washington/csv ↓

Bulk CSV — all supported markets

GET /api/markets/csv

Single CSV file with one row per market metric across every supported market. Stable ordering: rows sorted by market_id then metric_id. Same column contract as the per-market CSV. Content-Disposition filename: housing-builddesignhub-markets.csv.

/api/markets/csv ↓

Columns

ColumnNotes
market_idGeography id, e.g. us-tx-austin. Same as the JSON market.id.
market_nameDisplay name, e.g. "Austin, TX".
metric_idStable metric key, e.g. medianGrossRent.
metric_labelHuman-readable label for the metric.
valueNumeric value, encoded as a JS Number.
unitUnit string, e.g. USD/mo, %, index.
source_idSource adapter id (e.g. census-acs).
updated_dateProfile updatedDate; same value for all rows in a single export.
methodology_versionMethodology contract version used (e.g. v5.0).
production_modeAlways static-fixture in this version.
live_dataAlways false in this version.

Example rows

market_id,market_name,metric_id,metric_label,value,unit,source_id,updated_date,methodology_version,production_mode,live_data
us-tx-austin,"Austin, TX",medianGrossRent,Median gross rent,1567,USD/mo,census-acs,2026-05-19,v5.0,static-fixture,false
us-tx-austin,"Austin, TX",homePriceIndex,"House Price Index (all-transactions-nsa, 1991-Q1 = 100)",488.2,index,fhfa-hpi,2026-05-19,v5.0,static-fixture,false
us-tx-austin,"Austin, TX",permits,Trailing-12 building permits,28200,units,census-bps,2026-05-19,v5.0,static-fixture,false

CSV exports carry the same fixture caveats as the JSON profile — see below. The live_data column is always false; the production_modecolumn is always static-fixture.

Caveats

  • Static fixture data. Endpoints serialize production-loaded fixture profiles — not live data, not real-time data, not investor-grade forecasts.
  • No SLA. Housing BuildDesignHub is an early-stage MVP. There are no published uptime guarantees, response-time targets, or paid support tiers.
  • No auth, no rate limiting today. Endpoints are statically prerendered. Behavior may change without notice if a future phase adds authentication or quotas.
  • Not advice. Nothing in these responses is investment, legal, financial, real-estate, or property-level advice.
  • Upstream licenses. Citation URLs point at the agency landing pages whose datasets feed the pipeline; each upstream dataset retains its own license, terms, and citation conventions.
  • Schema may evolve. Consumers should pin to schemaVersion 1. A shape change will bump the version and be reflected in /changelog.
  • Index endpoint behavior. /api/markets lists all currently-produced markets. New markets appear when their fixtures land — there is no add-a-market API.

API contract

Machine-readable contract descriptors for the JSON profile and the CSV exports. Same content surfaced as the response model table above — these endpoints are the source of truth for consumers that need a programmatic shape reference.

JSON Schema (draft-07)

GET /api/schema/market-profile

Describes PublicMarketProfileResponse. Use with any draft-07 validator (Ajv, jsonschema, etc.).

/api/schema/market-profile ↗

CSV column descriptor

GET /api/schema/market-csv

Lists the 11 CSV columns with type and constants. Same contract for both per-market and bulk CSV endpoints.

/api/schema/market-csv ↗

schemaVersion compatibility

  • Pin to schemaVersion 1. Both the JSON profile and the CSV descriptor currently report schemaVersion: "1".
  • Additive changes. New optional fields may be introduced inside the same schemaVersion. Consumers should ignore unknown fields. Current additive optional field: geographyScope, present when a market's source fixtures span multiple geographic boundaries (e.g. New York combines Census place, county-equivalent, and multi-state MSA inputs).
  • Breaking changes bump the version. Removing a field, renaming a field, or tightening a type constraint will increment schemaVersion and be documented in /changelog.
  • Do not infer live behavior. liveData: false is a guarded constant. Consumers must not interpret responses as a live feed regardless of schemaVersion.

curl examples

# index
curl https://housing.builddesignhub.com/api/markets

# single market (JSON)
curl https://housing.builddesignhub.com/api/markets/us-tx-austin

# single market (CSV)
curl https://housing.builddesignhub.com/api/markets/us-tx-austin/csv

# bulk CSV — all markets
curl https://housing.builddesignhub.com/api/markets/csv

# JSON schema (draft-07)
curl https://housing.builddesignhub.com/api/schema/market-profile

# CSV descriptor
curl https://housing.builddesignhub.com/api/schema/market-csv

All endpoints are static. There is no auth, no SLA, no rate limit today; consumers should treat responses as best-effort fixture data. See Caveats below.

Related resources

Last reviewed: 2026-05-20.

Related transparency