Retrofit Atlas developer documentation

One database, three doors: a REST API for code, an MCP server for agents, and bulk files for analysts. No key, no sign-up, CORS open, five-minute caches. Research use only until the licence is agreed with the authors; attribute Retrofit Atlas and cite the record URL.

Quickstart

# closed malls in CA, largest first
curl "https://retrofitatlas.org/api/v1/sites?state=CA&status=closed&sort=acres&limit=5"

# one record, everything with provenance
curl "https://retrofitatlas.org/api/v1/sites/m-31b5364d66"

# the location sheet for the same record, through MCP
curl -X POST https://retrofitatlas.org/api/mcp -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"location_sheet","arguments":{"id":"m-31b5364d66"}}}'

# Python (stdlib only)
import json, urllib.request
r = json.load(urllib.request.urlopen("https://retrofitatlas.org/api/v1/sites?strategy=regreen&limit=100"))
for s in r["results"]: print(s["name"], s["city"], s["state"], s["url"])

// JavaScript (browser or Node 18+)
const r = await fetch("https://retrofitatlas.org/api/v1/near?lat=34.187&lon=-118.397&km=40").then(x => x.json());
console.log(r.count, r.results.map(s => s.name));

How the API behaves

Topic	Behaviour
Base URL	`https://retrofitatlas.org/api/v1` (the gated mirror `retrofits.staffbox.ai` answers too)
Authentication	None. No key, no token, no sign-up. Owner mailing addresses are entities' registered addresses from county assessors; natural persons are withheld.
Format	JSON, UTF-8. `Content-Type: application/json; charset=utf-8`. Every list response has `total`, `limit`, `offset`, `results`.
Pagination	`limit` (1 to 500) and `offset`; stable ordering by `sort`, ties alphabetical.
Filtering	Query parameters combine with AND. Comma in `element` means every element must match. Unknown parameters are ignored; malformed values return 400.
Caching and CORS	`Cache-Control: public, max-age=300` (stats 600, docs 3600). `Access-Control-Allow-Origin: *`. Data refreshes on every publish; `/api/v1/changes` tells you what moved.
Errors	400 `{"error": "bad parameter: …"}`; 405 for writes; 500 `{"error": "internal error; reported"}`. A missing record or endpoint answers HTTP 200 with `{"error", "status": 404}` and the header `X-Atlas-Status: 404`, because the CDN rewrites origin 404s to the site's HTML page. Check the header or the `status` field.
Rate limits	Best effort, no SLA. Keep to a few requests per second and cache; for bulk work use the downloads (CSV per table, GeoJSON, KML, SQLite).
Identifiers	Record ids (`m-…` curated/imported, `n-…` model-extracted drafts) are stable across publishes; slugs can change when a name is corrected. Every object carries `url` (the page) and, for sites, `api` (the full record).
Tiers and provenance	`verified`: curated = from the authors' public map, not reviewed by them; draft = imported or model-extracted, unreviewed; contributed = submitted and reviewed. Full records carry a `provenance` map naming the import, model run or research set behind each field, and quotes on extracted values.
Licence	Undecided; research use only until terms are agreed with the authors. Wikipedia excerpts CC BY-SA 4.0; photos per their Commons credit; each context layer lists its own source licence on the data model page.
Versioning	Path-versioned (`/api/v1`). Fields are added, not removed, within v1; removals come with a new version and a changelog entry. The OpenAPI 3.1 document is regenerated on every publish.
Contact	desk@retrofitatlas.org; corrections through the form; answered within five working days.

Three doors

REST API10 endpoints with real request and response examples, parameter tables, error cases.MCP server9 tools for Claude, Cursor, ChatGPT and any Model Context Protocol client; location_sheet for underwriting.Data model22 tables, 246 fields, 36 context layers, every vocabulary with live counts.

Worked examples

Lead list for a developer: closed sites over 30 acres, then /api/v1/sites/{id} for owners, parcels and the context layers.
Precedents for a city: built regreening retrofits; elements such as policy tools, then /api/v1/elements/{slug}.
Monitoring: poll changes since the first of the month or subscribe to the RSS feed.
Underwriting: the MCP tool location_sheet, or the context object of a full record; see the investors guide.

Documentation built 2026-10-21 from the live database (1,904 records). Corrections: the form or desk@retrofitatlas.org.