CostAlmanac US

Public API

One endpoint. No key, no signup, no quota beyond a rate limit. It returns every metric we hold for a city, each row carrying its own margin of error, geography level, vintage and source.

The endpoint

GET /api/v1/cities/{place}
GET /api/v1/cities/new-york-ny

200  text/csv; charset=utf-8
404  application/json  {"ok":false,"error":"City not found"}

{place} is the slug from the city's own URL. Any city with a page has an endpoint:

Columns

metric
Stable key, e.g. rent_1br. Safe to join on.
label
Human-readable name, e.g. “Rent (1BR)”. May change wording; do not join on it.
value
The figure. Percentages are 0–100, not 0–1.
moe
Margin of error at 90% confidence, in the same unit. Empty where the agency publishes none — empty is not zero, and zero is a real value for a controlled estimate.
unit
usd_per_month, usd_per_year, percent, count, years, minutes, calendar_year, index_100.
asOf
The date the data refers to, not the date we fetched it. Sources sit on different vintages.
geo_level
The geography the agency published at: place, metro, state or national. A state-level figure applies to every city in that state — do not read one as a city figure.
source
Publishing dataset, e.g. Census ACS 5-Year.
source_url
Where to verify it.

Only metrics with status ok are returned. A quarantined or missing figure is omitted rather than shipped as a zero, so a city's row count varies by how much we actually hold for it.

Limits and caching

  • 30 requests per minute per IP, bursting to 60. Enforced at the edge, not in the app.
  • Responses carry max-age=86400. The underlying data moves on annual and monthly release schedules, so a day-old response is the same response.
  • Read-only. There is no write API and no authentication to get one.

Using it

The underlying data is public domain U.S. government work. Our compilation is CC BY 4.0— credit the originating agency alongside this site. Every row gives you the agency and a URL to verify against.

If you are building on this and need something it does not do, say so rather than scraping the pages: [email protected].

Full provenance and refresh cadence per source: sources. How each number is computed: methodology. Bulk download: the data page.