{"openapi":"3.1.0","info":{"title":"Rentometer API","termsOfService":"https://www.rentometer.com/terms-of-use#api-terms","description":"Rentometer's public REST API for rent analysis. The same API that powers the\n`rentometer.com` web app, mobile apps, and the published `/rentometer-*`\nClaude Code skills.\n\n## Authentication\n\nMost endpoints require a Rentometer API key. Generate one at\n[rentometer.com/rentometer-api/settings](https://www.rentometer.com/rentometer-api/settings).\nAPI access requires an active Pro subscription with API access enabled.\n\nPass the key either as:\n\n- `Authorization: Bearer \u003ckey\u003e` header (preferred)\n- `?api_key=\u003ckey\u003e` query parameter (legacy, still supported)\n\n## Credits\n\nEach authenticated request consumes credits from the caller's wallet:\n\n| Credit type | Endpoints that charge it |\n|---|---|\n| `quickview` | `/summary`, each property in `/batch_summary` |\n| `premium` | `/nearby_comps`, `/property_rents` |\n| `pro_report` | `/request_pro_report` |\n\n`credits_remaining` is returned in the body of every charging response.\nWallet balance and plan tier are managed at\n[rentometer.com/rentometer-api/settings](https://www.rentometer.com/rentometer-api/settings).\n\n## Rate limits\n\nPer-key rate limits depend on tier. Every response includes:\n\n- `X-RateLimit-Usage` — e.g. `minute=4/60;hour=87/1000;day=412/10000`\n- `X-RateLimit-Dimension` — `api_key` or `ip`\n- `X-RateLimit-Tier` — `pro`, `essential`, `free`, `anonymous`\n- `X-RateLimit-Policy` — the limit values for the current tier\n\nCall `/rate_limit` to read current usage without consuming credits.\n","version":"1.0.0","contact":{"name":"Rentometer Support","url":"https://www.rentometer.com/support"},"license":{"name":"Proprietary","url":"https://www.rentometer.com/terms"}},"servers":[{"url":"https://www.rentometer.com","description":"Current host"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]},{"oauth2":["rentometer.read"]}],"tags":[{"name":"Rent Analysis","description":"Get rent statistics and comparable listings for an address"},{"name":"Atlas","description":"Live, key-gated bounded-geography analysis. Resolves place names to\nAtlas `slug` values and returns the same rent + demographics +\nhousing-market data the public `/average-rent-in/...` Atlas pages\nsurface.\n"},{"name":"Pro Report","description":"Generate and download a Pro PDF report for an analyzed search"},{"name":"Account","description":"Wallet, rate-limit, and account introspection"}],"paths":{"/api/v1/summary":{"get":{"tags":["Rent Analysis"],"summary":"Get rent summary for an address, point, or Atlas area","description":"Returns aggregate rent statistics (mean, median, percentiles, sample\nsize) for a property described by address, lat/lng, or Atlas slug.\nCharges 1 quickview credit.\n\nSupply **exactly one of**:\n\n- `address` (geocoded), or\n- `latitude` + `longitude` (point search), or\n- `slug` (Atlas bounded geography — metro, city, ZIP, neighborhood,\n  school district, etc.). When `slug` is present, `address`,\n  `latitude`, and `longitude` are ignored. Use `/api/v1/atlas/search`\n  to resolve a place name to a slug.\n\n### Filters\n\nThe same filters the rentometer.com search form offers:\n`bedrooms`, `baths`, `building_type`, `look_back_days`,\n`min_price`/`max_price` (rent range), `min_sqft`/`max_sqft`\n(square footage), and — for address/point searches — `radius_miles`\n(a fixed radius instead of Smart Radius). Applied filters are echoed\nin the response.\n\nA fixed `radius_miles` that holds more comps than one analysis\nsamples falls back to Smart Radius, as on the website; `radius_miles`\nin the response is the radius actually used.\n\nFor a `slug` search with no `bedrooms` and no filters, the response\nis the unfiltered, all-bedrooms number for the whole area (the same\nnumbers the public `/average-rent-in/...` page shows). With\n`bedrooms` the analysis is narrowed to that bedroom count inside the\narea, and any other filter can be added; filters without `bedrooms`\nare rejected (`422`), as on the website. Filters are not supported for state- or\nmetro-wide slugs (`422`); use a smaller area or omit them.\n`radius_miles` is rejected with a slug (`422`).\n\n### Historical searches (limited availability)\n\nPass `end_date` (`YYYY-MM-DD`, up to 5 years back) to see rents as of\na past date: the analysis covers the `look_back_days` window ending\non `end_date`. It costs the same credit as a current search. With a\n`slug`, a historical summary is always computed live over the area\n(never from the weekly rollup), and isn't supported for state- or\nmetro-wide slugs (`422`). It's rolling out gradually: accounts without\naccess get `403`.\n","operationId":"getRentSummary","parameters":[{"$ref":"#/components/parameters/Address"},{"$ref":"#/components/parameters/Latitude"},{"$ref":"#/components/parameters/Longitude"},{"$ref":"#/components/parameters/AtlasSlug"},{"$ref":"#/components/parameters/Bedrooms"},{"$ref":"#/components/parameters/Baths"},{"$ref":"#/components/parameters/BuildingType"},{"$ref":"#/components/parameters/LookBackDays"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/MinPrice"},{"$ref":"#/components/parameters/MaxPrice"},{"$ref":"#/components/parameters/MinSqft"},{"$ref":"#/components/parameters/MaxSqft"},{"$ref":"#/components/parameters/RadiusMiles"},{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Rent summary computed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RentSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/HistoricalSearchNotAvailable"},"404":{"$ref":"#/components/responses/AddressNotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/atlas/search":{"get":{"tags":["Atlas"],"summary":"Fuzzy-search Atlas geographic slugs by name","description":"Resolves a place name (e.g. \"hyde park cincinnati\", \"45208\",\n\"Austin TX\") to one or more Atlas `slug` values usable with\n`/api/v1/summary?slug=…` and `/api/v1/atlas/facts?slug=…`.\n\nBacked by trigram similarity / ILIKE matching ordered by relevance,\nrecord density, and total listing count. Areas with no listings are\nexcluded. Charges no credits.\n\n**FIPS / GEOID lookup:** instead of `q`, pass `geoid` (with optional\n`area_type`) to resolve a Census FIPS / GEOID or ZCTA code directly\nto its slug(s) — handy for callers that already hold codes rather\nthan place names. The result rows have the same shape as the\nfree-text path; an unmatched code returns an empty array.\n\nRequires an API key (rate-limited per-key), but no Pro subscription\ngate — works for any valid key.\n","operationId":"searchAtlas","parameters":[{"in":"query","name":"q","required":false,"schema":{"type":"string","minLength":2},"description":"Free-text search query (min 2 chars). Required unless `geoid` is\ngiven. Queries shorter than 2 chars return an empty array.\n"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":50,"default":15}},{"$ref":"#/components/parameters/AtlasGeoid"},{"$ref":"#/components/parameters/AtlasAreaType"},{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Matching Atlas areas","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AtlasSearchResult"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/atlas/facts":{"get":{"tags":["Atlas"],"summary":"Get the full Atlas data bundle for a bounded area","description":"Returns everything Rentometer knows about an Atlas area: live\nrent breakdown (by bedrooms and by property type) plus\nthird-party data sources — ACS demographics, HUD Fair Market\nRents, HUD CHAS (housing affordability), BLS LAUS (local\nunemployment), BLS QCEW (industry / wages), Census BPS\n(building permits), and Census PEP (population, growth, and\nmigration).\n\nWhether each external source is included depends on the caller's\naccount access. **Sources the caller doesn't have access to are\nomitted entirely from the response** — there is no \"access denied\"\nmarker. Sources with no data for the area are also omitted. An\nabsent key means \"no data\" or \"no access\"; consumers should treat\nboth the same.\n\nShares a 12-hour server-side cache with the public\nAtlas web pages, so the numbers match\n`https://www.rentometer.com/average-rent-in/…`. Charges 1\nquickview credit.\n\nIdentify the area by **either** `slug` **or** `geoid` (a Census\nFIPS / GEOID or ZCTA code, optionally narrowed with `area_type`).\nWhen a `geoid` is ambiguous across area types and no `area_type` is\ngiven, the endpoint returns `422` with a `candidates` list and\n**charges no credit** — resubmit with `area_type` to pick one.\n","operationId":"getAtlasFacts","parameters":[{"$ref":"#/components/parameters/AtlasSlug"},{"$ref":"#/components/parameters/AtlasGeoid"},{"$ref":"#/components/parameters/AtlasAreaType"},{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Atlas bundle for the area","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasFacts"}}}},"400":{"description":"Neither `slug` nor `geoid` supplied, or an unknown `area_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No Atlas area matches the given `slug` / `geoid`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The `geoid` is ambiguous across area types. The body includes a\n`candidates` array of `{slug, area_type}`; resubmit with\n`area_type`. No credit is charged.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"candidates":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"area_type":{"type":"string"}}}}}}]}}}},"402":{"$ref":"#/components/responses/InsufficientCredits"}}}},"/api/v1/atlas/rankings":{"get":{"tags":["Atlas"],"summary":"Rank areas of a type by a metric, optionally within a parent area","description":"Returns a sorted list of areas ranked by a single metric — the\n\"collection query\" complement to `/api/v1/atlas/facts` (which\ndescribes one named area). Use it for leaderboards: \"top N\ncities / metros / counties / ZIPs / neighborhoods by X\".\n\n`metric` must be a key from `/api/v1/atlas/metrics` that the caller\nis entitled to (otherwise `403`) and that is published for the\nrequested `area_type` (otherwise `422`). Omit `within` for a\ncountry-wide ranking, or pass a parent Atlas slug to scope to\nchildren contained in it.\n\nMetrics cover government facts (ACS, HUD, BLS, Census), NCES\nschool-district facts (`nces_ccd.enrollment`,\n`nces_ccd_finance.per_pupil_spending`, … — published only at\n`area_type=school_district`), OpenStreetMap amenity / walkability\nmetrics (`osm.amenity_density`, `osm.transit_stop_count`, … —\ncomputed per polygon, published for `place` / `zcta` / `neighborhood`),\nplus first-party rent stats\n(`rent.median`, `rent.median_2br`, …), houses vs apartments over\nevery listing (`rent.median_house`, `rent.median_apartment`,\n`rent.median_3br_house`, `rent.yoy_pct_3br_house`, …) and the derived\nrent growth / investor ratios (`rent.yoy_pct`, `rent.gross_yield_pct`,\n`rent.rent_to_income_pct`, `rent.vs_acs_gross_rent_pct`) where the\naccount holds the rent-metrics entitlement.\nCharges 1 quickview credit, flat, regardless of `limit`.\n","operationId":"getAtlasRankings","parameters":[{"in":"query","name":"area_type","required":true,"schema":{"type":"string","enum":["state","metro","cbsa","county","place","city","zcta","zip","neighborhood","school_district"]},"description":"Kind of area to rank. `city` aliases `place`; `zip` aliases `zcta`; `cbsa` aliases `metro` — both cover the full CBSA universe, i.e. metropolitan **and** micropolitan statistical areas (government fact families are often thinner for micropolitan areas, which simply drop out of the ranking). Aliases are case-insensitive, and the response echoes the canonical token (`area_type=city` returns `\"area_type\": \"place\"`; `area_type=cbsa` returns `\"area_type\": \"metro\"`).\n"},{"in":"query","name":"metric","required":true,"schema":{"type":"string"},"description":"A metric key from `/api/v1/atlas/metrics`, e.g. `acs.median_household_income`."},{"in":"query","name":"within","schema":{"type":"string"},"description":"Optional parent Atlas slug to scope the ranking to. Omit for country-wide."},{"in":"query","name":"order","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction. Defaults to the metric's natural direction."},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"How many areas to return."},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"description":"Skip this many ranked areas, for paging."},{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Ranked areas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasRankings"}}}},"400":{"description":"Unknown `metric`, or missing / unknown `area_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"description":"Caller is not entitled to the requested metric","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown `within` slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Metric is not published for the requested `area_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/atlas/screener":{"get":{"tags":["Atlas"],"summary":"Find areas whose metrics all fall within target ranges","description":"Multi-constraint screener: returns areas of a type whose\ngovernment-fact metrics **all** fall within the requested ranges —\nthe \"find me places that match this whole profile\" query, vs\n`/api/v1/atlas/rankings` which sorts by a single metric.\n\nEvery filter (and the `sort`) metric must be a key from\n`/api/v1/atlas/metrics` the caller is entitled to (otherwise `403`)\nand published for the `area_type` (otherwise `422`). Charges 1\nquickview credit, flat. Each result reports the matched value of\nevery filter metric.\n","operationId":"getAtlasScreener","parameters":[{"in":"query","name":"area_type","required":true,"schema":{"type":"string","enum":["state","metro","cbsa","county","place","city","zcta","zip","neighborhood","school_district"]},"description":"Kind of area to screen. `city` aliases `place`; `zip` aliases `zcta`; `cbsa` aliases `metro` — both cover the full CBSA universe, i.e. metropolitan **and** micropolitan statistical areas (government fact families are often thinner for micropolitan areas, which simply drop out of the results). Aliases are case-insensitive, and the response echoes the canonical token (`area_type=city` returns `\"area_type\": \"place\"`; `area_type=cbsa` returns `\"area_type\": \"metro\"`).\n"},{"in":"query","name":"filters","required":true,"schema":{"type":"string"},"description":"JSON array of `{ \"metric\": \"\u003ckey\u003e\", \"min\": \u003cnumber?\u003e, \"max\": \u003cnumber?\u003e }` (1–6 entries, at least one of min/max each). E.g. `[{\"metric\":\"acs.median_household_income\",\"min\":75000,\"max\":125000},{\"metric\":\"acs.effective_property_tax_rate_pct\",\"max\":0.75}]`.\n"},{"in":"query","name":"within","schema":{"type":"string"},"description":"Optional parent Atlas slug to scope to (containment). Omit for country-wide."},{"in":"query","name":"sort","schema":{"type":"string"},"description":"Metric key to order results by. Defaults to the first filter's metric."},{"in":"query","name":"order","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction. Defaults to the sort metric's natural direction."},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0}},{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Matching areas, with the value each matched on","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad / empty `filters`, unknown `metric`, or missing / unknown `area_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"description":"Caller is not entitled to a filter or sort metric","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown `within` slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A metric is not published for the requested `area_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Atlas"],"summary":"Find areas whose metrics all fall within target ranges (filters in body)","description":"Identical to `GET /api/v1/atlas/screener`, but the parameters travel in\na JSON request body so the `filters` array isn't a JSON blob in the URL\n— a query-string JSON array is rejected by some proxies/WAFs and runs\ninto URL-length limits. Preferred for programmatic callers and the MCP\nconnector. Same validation, credit charge, and response as the GET form.\n","operationId":"postAtlasScreener","parameters":[{"$ref":"#/components/parameters/Tool"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["area_type","filters"],"properties":{"area_type":{"type":"string","enum":["state","metro","cbsa","county","place","city","zcta","zip","neighborhood","school_district"],"description":"Kind of area to screen. `city` aliases `place`; `zip` aliases `zcta`; `cbsa` aliases `metro` — both cover the full CBSA universe, i.e. metropolitan **and** micropolitan statistical areas (government fact families are often thinner for micropolitan areas, which simply drop out of the results). Aliases are case-insensitive, and the response echoes the canonical token (`area_type=city` returns `\"area_type\": \"place\"`; `area_type=cbsa` returns `\"area_type\": \"metro\"`).\n"},"filters":{"type":"array","minItems":1,"maxItems":6,"description":"Metric range constraints; an area must satisfy all of them.","items":{"type":"object","required":["metric"],"properties":{"metric":{"type":"string","description":"A metric key from `/api/v1/atlas/metrics`."},"min":{"type":"number"},"max":{"type":"number"}}}},"within":{"type":"string","description":"Optional parent Atlas slug to scope to (containment)."},"sort":{"type":"string","description":"Metric key to order results by. Defaults to the first filter's metric."},"order":{"type":"string","enum":["asc","desc"]},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"offset":{"type":"integer","minimum":0,"default":0}}}}}},"responses":{"200":{"description":"Matching areas, with the value each matched on","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad / empty `filters`, unknown `metric`, or missing / unknown `area_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"description":"Caller is not entitled to a filter or sort metric","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown `within` slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A metric is not published for the requested `area_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/atlas/metrics":{"get":{"tags":["Atlas"],"summary":"List the metric vocabulary for /api/v1/atlas/rankings","description":"Returns the metrics `/api/v1/atlas/rankings` can rank by, each with\nits unit, the area types it is published for, its natural sort\ndirection, and whether the calling account is entitled to it. Free —\nno credit charge. Call this before\n`/api/v1/atlas/rankings` to discover valid metric keys and self-gate\non `entitled`.\n","operationId":"getAtlasMetrics","parameters":[{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Metric catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AtlasMetricCatalog"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/nearby_comps":{"get":{"tags":["Rent Analysis"],"summary":"List comparable rental listings near an address","description":"Returns individual rental property listings from a rent analysis.\nCharges 1 premium credit.\n\nEither supply a `token` from a prior `/summary` call (reuses the\nexisting search, filters included; preferred) or describe a new\nsearch via the same address/point parameters and filters as\n`/summary`. A `token` can't be combined with other search parameters.\n\nSupported searches: address, latitude/longitude, and Atlas `slug`\nsearches for a **ZIP code (ZCTA) or neighborhood**. A token from a\nlarger Atlas area (city, county, school district, metro, state)\nreturns `422`, and no credit is charged.\n\nLists up to 25 comps drawn from the analysis sample (the sample\nitself holds up to 150). `count` is the size of the analysis sample,\nso it can exceed the number of comps listed. For ZIP and neighborhood\nsearches each comp's `distance` is `\"n/a\"`, since there is no single\nsearch point.\n","operationId":"getNearbyComps","parameters":[{"$ref":"#/components/parameters/Address"},{"$ref":"#/components/parameters/Latitude"},{"$ref":"#/components/parameters/Longitude"},{"$ref":"#/components/parameters/Bedrooms"},{"$ref":"#/components/parameters/Baths"},{"$ref":"#/components/parameters/BuildingType"},{"$ref":"#/components/parameters/LookBackDays"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/MinPrice"},{"$ref":"#/components/parameters/MaxPrice"},{"$ref":"#/components/parameters/MinSqft"},{"$ref":"#/components/parameters/MaxSqft"},{"$ref":"#/components/parameters/RadiusMiles"},{"in":"query","name":"token","schema":{"type":"string"},"description":"Token from a prior `/summary` response. Reuses the search. Must be an address, latitude/longitude, ZIP or neighborhood search."},{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Comparable listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NearbyComps"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/HistoricalSearchNotAvailable"},"404":{"$ref":"#/components/responses/AddressNotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/api/v1/batch_summary":{"post":{"tags":["Rent Analysis"],"summary":"Submit a batch of properties for rent analysis","description":"Asynchronously analyzes up to 1000 properties in a single request.\nReturns a `batch_id` immediately; poll `GET /api/v1/batch_summary/{batch_id}`\nfor status. Charges 1 quickview credit per property when complete.\n\nA pre-flight credit check rejects the request with `402` if the\nwallet can't cover the full batch.\n\nEvery property and the `defaults` object are validated before anything\nis queued; any error rejects the whole request with `422` and charges\nnothing. Numeric fields must be entirely numeric: `\"39.1031abc\"` or\n`\"abc\"` is an error, not a coerced value. Error messages are prefixed\n`Property N:` (zero-based row index) or `Defaults:`.\n\n`end_date` (per property or in `defaults`) makes a row a historical\nsearch, with the same rules and plan requirement as `/summary`; a\nbatch that uses it on a plan without historical searches is refused\nwith `403` before anything is queued.\n","operationId":"createBatchSummary","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSummaryRequest"}}}},"responses":{"202":{"description":"Batch accepted and queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSummaryAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/HistoricalSearchNotAvailable"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/api/v1/batch_summary/{batch_id}":{"get":{"tags":["Rent Analysis"],"summary":"Get the status and results of a batch summary","description":"Poll for batch progress. While `status` is `pending` or `processing`,\nonly `batch_id`, `status`, and `progress` are populated. Once\n`status` becomes `completed` or `failed`, the full `results` array\nis returned.\n\nPoll every 5–10 seconds. Typical batches complete within a few\nminutes.\n","operationId":"getBatchSummary","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"type":"string"},"description":"Token returned by `POST /batch_summary`"}],"responses":{"200":{"description":"Batch status (and results, if finished)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSummaryStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Batch not found or not owned by the authenticated key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/property_rents":{"get":{"tags":["Rent Analysis"],"summary":"Get historical rents recorded for a single address","description":"Returns rental listing records matching the exact address. Different\nfrom `/summary` (which returns aggregate area stats) and `/nearby_comps`\n(which returns nearby comparable properties).\n\nCharges 1 premium credit. Often returns zero matches — most properties\nare not individually tracked in the database. Fall back to `/summary`\nwhen no matches are found.\n","operationId":"getPropertyRents","parameters":[{"$ref":"#/components/parameters/Address"},{"in":"query","name":"max_age","schema":{"type":"integer","default":30,"minimum":1},"description":"Days of listing history to include. Default 30."},{"$ref":"#/components/parameters/Tool"}],"responses":{"200":{"description":"Historical rent records (may be empty)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyRents"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"404":{"$ref":"#/components/responses/AddressNotFound"}}}},"/api/v1/request_pro_report":{"get":{"tags":["Pro Report"],"summary":"Request a Pro PDF report for a previously analyzed search","description":"Enqueues PDF generation for the search identified by `token`. Charges\n1 pro_report credit immediately. The PDF is rendered asynchronously;\npoll `/pro_report_status` until ready.\n","operationId":"requestProReport","parameters":[{"$ref":"#/components/parameters/ProReportToken"},{"$ref":"#/components/parameters/Tool"}],"responses":{"202":{"description":"Pro report queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProReportQueued"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"404":{"description":"Search token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pro_report_status":{"get":{"tags":["Pro Report"],"summary":"Poll Pro report build status","description":"Returns `202` (with `Retry-After: 5`) while the PDF is still queued,\n`303` (with a `download` link) once it's ready, `400` if no Pro\nreport has been requested for this token yet.\n","operationId":"getProReportStatus","parameters":[{"$ref":"#/components/parameters/ProReportToken"}],"responses":{"202":{"description":"Still queued; retry after the seconds in `Retry-After`","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Suggested wait before next poll"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProReportStatus"}}}},"303":{"description":"Ready — `download` link is in the response body","headers":{"Location":{"schema":{"type":"string","format":"uri"},"description":"URL to download the PDF"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProReportReady"}}}},"400":{"description":"Pro report has not been requested for this token; call `/request_pro_report` first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProReportNotRequested"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/download_pro_report":{"get":{"tags":["Pro Report"],"summary":"Download the rendered Pro report PDF","description":"Returns the PDF binary when `?download=true` is passed, otherwise\nreturns JSON containing a signed `download` URL. The token must\nmatch a search whose Pro report has finished rendering.\n","operationId":"downloadProReport","parameters":[{"$ref":"#/components/parameters/ProReportToken"},{"in":"query","name":"download","schema":{"type":"boolean"},"description":"When true, returns the PDF binary. Otherwise returns JSON with a download URL."}],"responses":{"200":{"description":"PDF binary (when `download=true`) or JSON wrapper","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProReportReady"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Report not yet ready or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/rate_limit":{"get":{"tags":["Account"],"summary":"Get current rate-limit usage","description":"Inspect minute / hour / day rate-limit windows for the current API key.\nDoes not consume credits. Useful before launching large batches or\nwhen investigating `429` responses.\n","operationId":"getRateLimit","responses":{"200":{"description":"Current rate-limit usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/auth":{"get":{"tags":["Account"],"summary":"Verify API key and return account / plan / credit summary","description":"Lightweight \"who am I\" endpoint. Confirms the supplied API key is\nvalid and returns the associated account's plan, tier, and remaining\ncredit balances. Does not consume credits.\n\nUseful for client apps that need to know what plan the user is on\n(e.g. to gate features or label the UI) without making a charging\ncall first.\n","operationId":"getAuth","responses":{"200":{"description":"API key is valid; account summary returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/whats_new":{"get":{"tags":["Account"],"summary":"Product release notes (\"What's New\")","description":"Recent Rentometer product updates across Rentometer, the Atlas, the API,\nand tools — each with a title, plain-English blurb, category, publish\ndate, and link. Does not consume credits.\n\nFilter with `category` to answer product-specific questions (e.g. only\nAtlas updates). Returns an empty `release_notes` array while the feature\nis not yet enabled for the account.\n","operationId":"getWhatsNew","parameters":[{"name":"category","in":"query","required":false,"description":"Optional product filter.","schema":{"type":"string","enum":["atlas","api","rentometer","tools_company"]}},{"name":"limit","in":"query","required":false,"description":"Maximum notes to return (default 20, max 100).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Recent release notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhatsNew"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Pass a Rentometer API key as `Authorization: Bearer \u003ckey\u003e`. Generate\nkeys at https://www.rentometer.com/rentometer-api/settings.\n"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Legacy query-parameter authentication. Prefer `bearerAuth`."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization-code + PKCE, for AI connectors (Claude / ChatGPT)\nand custom GPT Actions. The user authorizes in their browser and the\nconnector receives an access token that maps to the user's Rentometer\naccount and credits — no API key copy-paste. Discovery documents live at\n`/.well-known/oauth-authorization-server` (RFC 8414) and\n`/.well-known/oauth-protected-resource` (RFC 9728); clients may\ndynamically register at `/oauth/register` (RFC 7591). See\nhttps://www.rentometer.com/connect.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.rentometer.com/oauth/authorize","tokenUrl":"https://www.rentometer.com/oauth/token","refreshUrl":"https://www.rentometer.com/oauth/token","scopes":{"rentometer.read":"Run rent analyses and Atlas lookups using your account's credits"}}}}},"parameters":{"Address":{"in":"query","name":"address","example":"15 Broad St, Boston, MA","schema":{"type":"string"},"description":"Full street address including city and state. Exclusive with `latitude`/`longitude`.","required":true},"Latitude":{"in":"query","name":"latitude","schema":{"type":"number","format":"float","minimum":-90,"maximum":90},"description":"Decimal latitude. Must be paired with `longitude` and not `address`."},"Longitude":{"in":"query","name":"longitude","schema":{"type":"number","format":"float","minimum":-180,"maximum":180},"description":"Decimal longitude. Must be paired with `latitude` and not `address`."},"Bedrooms":{"in":"query","name":"bedrooms","required":true,"example":2,"schema":{"type":"integer","minimum":0,"maximum":6},"description":"Bedroom count. 0 = studio. With `slug`, omit it (and all filters) for\nwhole-area, all-bedroom numbers; it's required once any filter is set.\n"},"Baths":{"in":"query","name":"baths","schema":{"type":"string","enum":["1","1.5","1.5+"]},"description":"Bathroom filter. Omit to include all bath counts.\n- `1` = 1 bath only\n- `1.5` / `1.5+` = 1.5 or more baths\n"},"BuildingType":{"in":"query","name":"building_type","example":"apartment","schema":{"type":"string","enum":["apartment","house"]},"description":"Filter by property type. Omit for both."},"LookBackDays":{"in":"query","name":"look_back_days","schema":{"type":"integer","minimum":90,"maximum":1460,"default":365},"description":"How many days of listing history to include (90–1460, default 365)."},"EndDate":{"in":"query","name":"end_date","example":"2024-06-30","schema":{"type":"string","format":"date"},"description":"Run a historical search: the analysis covers the `look_back_days` window ending on this date instead of today. A listing counts if it was active at any time in that window, at its latest price within it. `YYYY-MM-DD`, not in the future, and no more than 5 years ago (`422` otherwise). Accounts without access get `403`. Same credit cost as a current search. Echoed as `end_date` in the response (null when omitted)."},"MinPrice":{"in":"query","name":"min_price","schema":{"type":"integer","minimum":250,"maximum":100000},"description":"Only include comps renting for at least this many USD per month. Must not exceed `max_price`."},"MaxPrice":{"in":"query","name":"max_price","schema":{"type":"integer","minimum":500,"maximum":100000},"description":"Only include comps renting for at most this many USD per month."},"MinSqft":{"in":"query","name":"min_sqft","schema":{"type":"integer","minimum":250,"maximum":10000},"description":"Only include comps of at least this many square feet. Must not\nexceed `max_sqft`. Comps with no recorded square footage are\nexcluded when a square-footage filter is set.\n"},"MaxSqft":{"in":"query","name":"max_sqft","schema":{"type":"integer","minimum":500,"maximum":10000},"description":"Only include comps of at most this many square feet."},"RadiusMiles":{"in":"query","name":"radius_miles","schema":{"type":"number","minimum":0.1,"maximum":10},"description":"Fixed search radius in miles around the address or point. Omit to use\nSmart Radius, which widens until there are enough comps. Falls back to\nSmart Radius when the radius holds more comps than one analysis\nsamples. Not allowed with `slug`.\n"},"AtlasSlug":{"in":"query","name":"slug","schema":{"type":"string"},"description":"Atlas slug identifying a bounded geographic area (metro, city,\nneighborhood, ZIP, school district, county, state). When passed to\n`/api/v1/summary`, takes precedence over `address`/`latitude`/`longitude`.\nWithout filters it returns whole-area, all-bedroom numbers; with\n`bedrooms` (plus any filters), numbers for matching comps in the area.\nResolve a place name to a slug via `/api/v1/atlas/search`.\n"},"AtlasSlugRequired":{"in":"query","name":"slug","required":true,"schema":{"type":"string"},"description":"Atlas slug (from `/api/v1/atlas/search`) identifying the area."},"AtlasGeoid":{"in":"query","name":"geoid","schema":{"type":"string"},"description":"Census FIPS / GEOID (or 5-digit ZCTA code) identifying the area —\nan alternative to `slug` for callers that already hold a code:\n2-digit state, 5-digit county or CBSA/metro, 7-digit place, or\n5-digit ZCTA. Because a 5-digit code can match more than one area\ntype (a county FIPS, a CBSA code, and a ZCTA can all be 5 digits),\npair it with `area_type` to disambiguate.\n"},"AtlasAreaType":{"in":"query","name":"area_type","schema":{"type":"string","enum":["state","metro","cbsa","county","place","city","zcta","zip"]},"description":"Disambiguates a `geoid` lookup to a single area type. `city` is an\nalias for `place`, `zip` for `zcta`, and `cbsa` for `metro` (both\ncover metropolitan **and** micropolitan statistical areas). Omit to\nmatch every fact-bearing type the code resolves to.\n"},"Tool":{"in":"query","name":"tool","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.-]{0,63}$","maxLength":64},"description":"Optional client identifier for attribution / analytics. Recommended\nvalues: `claude-skills`, `claude-mcp`, `chatgpt-gpt`, `python-sdk`.\n\nStored alongside the search as its `tool`. Values are lower-cased and\ntrimmed; anything that is not a plain identifier (letters, digits,\n`_`, `.`, `-`, max 64 chars) is ignored rather than truncated. The\nvalue never changes how the request is billed or served, and it does\nnot alter the search's `source` (the server-assigned channel, e.g.\n`rent_summary_api`).\n\n`tools` and `source` are accepted as deprecated aliases for this\nparameter.\n"},"ProReportToken":{"in":"query","name":"token","required":true,"schema":{"type":"string"},"description":"Search token from a prior `/summary` response."}},"responses":{"Unauthorized":{"description":"API key missing, invalid, or no active Pro subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Usage":{"$ref":"#/components/headers/RateLimitUsage"},"X-RateLimit-Tier":{"$ref":"#/components/headers/RateLimitTier"}}},"HistoricalSearchNotAvailable":{"description":"`end_date` was passed but historical searches aren't enabled for the caller's account yet. `error_type` is `HISTORICAL_SEARCH_NOT_AVAILABLE`. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Wallet doesn't have enough credits to complete the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AddressNotFound":{"description":"Address could not be geocoded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request parameters failed validation, or insufficient comps to analyze","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests — see `Retry-After` and `X-RateLimit-*` headers","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"},"X-RateLimit-Usage":{"$ref":"#/components/headers/RateLimitUsage"}}}},"headers":{"RateLimitUsage":{"schema":{"type":"string"},"description":"Current per-window usage, e.g. `minute=4/60;hour=87/1000;day=412/10000`.\nPresent on every response from a `/api/*` endpoint.\n"},"RateLimitTier":{"schema":{"type":"string"},"description":"Rate-limit tier name driving the policy. One of `pro`, `essential`,\n`free`, `anonymous`.\n"}},"schemas":{"AtlasRankings":{"type":"object","description":"A ranked list of areas for a single metric","properties":{"metric":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"unit":{"type":"string","description":"Value unit, e.g. usd | percent | count | ratio | points (percentage-point change) | index (unitless score, e.g. HHI)."},"family":{"type":"string"}}},"area_type":{"type":"string"},"within":{"type":"object","nullable":true,"description":"The parent area, when `within` was supplied.","properties":{"slug":{"type":"string"},"display_name":{"type":"string"}}},"order":{"type":"string","enum":["asc","desc"]},"total_candidates":{"type":"integer","description":"Number of areas of this type that have the metric."},"rankings":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"slug":{"type":"string"},"display_name":{"type":"string"},"area_type":{"type":"string","description":"Geometry model name, e.g. MetroGeometry."},"type":{"type":"string","description":"Human label, e.g. Metro."},"value":{"type":"number","nullable":true,"description":"Interpret using `metric.unit`."},"context":{"type":"object","properties":{"record_density":{"type":"number","nullable":true,"description":"Listings per square mile, rounded to 2 significant figures."}}},"links":{"type":"array","items":{"type":"object","properties":{"rel":{"type":"string"},"href":{"type":"string"}}}}}}},"credits_remaining":{"type":"integer"},"generated_at":{"type":"string","format":"date-time"}}},"AtlasMetricCatalog":{"type":"object","description":"The metric vocabulary accepted by `/api/v1/atlas/rankings`.\n\nEach entry self-documents the metric: in addition to its key /\nunit / area types / entitlement, the response carries a\nshort human description, source attribution, a \"Learn more\"\nURL pointing to the source authority, an optional derivation\nnote for computed metrics, and the methodology URL for the\nunderlying data family. The same fields back the `ⓘ` popovers\non Atlas tiles, so a third-party agent (or an LLM skill / MCP\ntool) can show users the same context without a second lookup.\n","properties":{"metrics":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Public dotted key (e.g. `acs.median_household_income`)"},"label":{"type":"string","description":"Human-readable name for UI labels"},"unit":{"type":"string","description":"Unit of measure (`usd`, `percent`, `count`, `ratio`, `points` for a percentage-point change, `score` for a 0–100 percentile rank (used by `fema_nri`), or `index` for a unitless score such as an HHI)"},"family":{"type":"string","description":"Data family (`acs`, `hud_fmr`, `bls_laus`, `bls_qcew`, `census_bps`, `hud_chas`, `nces_ccd`, `pep`, `fhfa_hpi`, `fema_nri`, `irs_soi_migration`, …)"},"default_order":{"type":"string","enum":["asc","desc"],"description":"Natural sort direction for this metric (e.g. income → desc, poverty rate → asc)"},"area_types":{"type":"array","items":{"type":"string"},"description":"Area type tokens the metric is published for"},"requires_flag":{"type":"string","description":"Identifier of the access entitlement that gates this metric's family"},"entitled":{"type":"boolean","description":"Whether the calling account is entitled to this metric"},"description":{"type":"string","nullable":true,"description":"One-line plain-English explanation of what the metric measures"},"source":{"type":"string","nullable":true,"description":"Vintage-agnostic source attribution (e.g. \"U.S. Census Bureau, American Community Survey\"). The per-area vintage label lives on `/atlas/facts` and the ranking response, not here."},"source_url":{"type":"string","nullable":true,"description":"Authoritative reference URL for the metric (per-variable Census page where available; family-level methodology URL otherwise)"},"derivation":{"type":"string","nullable":true,"description":"How a computed metric is derived from its inputs (e.g. \"Aggregate real estate taxes paid (B25090) ÷ aggregate owner-occupied home value (B25082)\"). Null for direct lookups."},"methodology_url":{"type":"string","nullable":true,"description":"Family-level methodology URL (Census ACS methodology page, HUD FMR data dictionary, etc.). Useful when `source_url` is absent."}}}}}},"RentSummary":{"type":"object","description":"Aggregate rent statistics for an address-based or point search","properties":{"address":{"type":"string","nullable":true,"description":"Formatted address. Null for point searches."},"latitude":{"type":"string","example":"42.358655","description":"Decimal latitude of the search point, encoded as a string."},"longitude":{"type":"string","example":"-71.054643","description":"Decimal longitude of the search point, encoded as a string."},"bedrooms":{"type":"integer","nullable":true,"description":"Null for an unfiltered, all-bedrooms slug summary."},"baths":{"type":"string","description":"Human-readable baths label"},"building_type":{"type":"string"},"look_back_days":{"type":"integer"},"end_date":{"type":"string","format":"date","nullable":true,"description":"The historical search's end date, or null for a current search."},"min_price":{"type":"integer","nullable":true,"description":"The `min_price` filter applied, or null."},"max_price":{"type":"integer","nullable":true,"description":"The `max_price` filter applied, or null."},"min_sqft":{"type":"integer","nullable":true,"description":"The `min_sqft` filter applied, or null."},"max_sqft":{"type":"integer","nullable":true,"description":"The `max_sqft` filter applied, or null."},"mean":{"type":"number","description":"Mean rent in USD"},"median":{"type":"number","description":"Median rent in USD"},"min":{"type":"number"},"max":{"type":"number"},"percentile_5":{"type":"number"},"percentile_10":{"type":"number"},"percentile_20":{"type":"number"},"percentile_25":{"type":"number"},"percentile_50":{"type":"number"},"percentile_75":{"type":"number"},"percentile_80":{"type":"number"},"percentile_90":{"type":"number"},"percentile_95":{"type":"number"},"std_dev":{"type":"number","description":"Sample standard deviation"},"samples":{"type":"integer","description":"Number of comparable listings included"},"radius_miles":{"type":"number","nullable":true,"description":"Search radius in miles actually used — Smart Radius's choice, or\nthe caller's `radius_miles`. Null when the search was slug-bounded.\n"},"area":{"allOf":[{"$ref":"#/components/schemas/AtlasArea"}],"nullable":true,"description":"Present only when the search was slug-bounded (i.e. `slug` was passed).\nIdentifies the bounded geography whose numbers this response reflects.\n"},"atlas":{"type":"array","items":{"$ref":"#/components/schemas/AtlasArea"},"description":"Atlas geo-linkage: the nested fact-bearing Atlas areas (state →\nmetro → county → place → ZCTA) that contain the searched point,\nbroadest first. Pass any returned `slug` (or its `geoid`) to\n`/api/v1/atlas/facts` (or `/api/v1/atlas/rankings`) to pull\ndemographics, FMR, jobs, and permits for the property's location.\nPresent only on point/address searches when the\n`atlas_api_geo_linkage` feature is enabled for the caller; the key\nis omitted otherwise.\n"},"facts":{"type":"object","description":"Curated Atlas facts bundle for the searched point, included free\nwith the quickview credit. Each fact resolves\nmost-local-available: the narrowest containing area (ZCTA → city\n→ county → metro → state) with a published value wins, and the\nentry's `source_level`/`source_slug` identify where the number\ncame from. Possible keys: `effective_property_tax_rate_pct`,\n`median_real_estate_taxes`, `median_home_value`,\n`fair_market_rent` (adds `bedrooms` — the searched count, clamped\nto HUD's 0–4BR range), and `unemployment_rate_pct` (adds `as_of`,\n`YYYY-MM`). Facts with\nno value at any level are omitted (no nulls). Present only on\npoint/address searches; the full facts catalog remains at\n`/api/v1/atlas/facts`.\n","additionalProperties":{"$ref":"#/components/schemas/QuickviewFactEntry"}},"quickview_url":{"type":"string","format":"uri","description":"Link to the full Rentometer quickview report"},"credits_remaining":{"type":"integer","description":"Quickview credits left in the wallet after this call"},"token":{"type":"string","description":"Reusable search token for `/nearby_comps` and `/request_pro_report`"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"QuickviewFactEntry":{"type":"object","description":"One curated Atlas fact resolved for a searched point","required":["value","source_level","source_slug"],"properties":{"value":{"type":"number","description":"The fact's numeric value (units implied by the key)."},"source_level":{"type":"string","enum":["ZCTA","Place","County","Metro","State"],"description":"Geographic level the value came from — the narrowest containing\narea that publishes this fact.\n"},"source_slug":{"type":"string","description":"Atlas slug of the source area. Pass it to `/api/v1/atlas/facts`\nfor that area's full catalog.\n"},"bedrooms":{"type":"integer","description":"Only on `fair_market_rent` — the bedroom count the FMR value is\nfor (searched count clamped to HUD's 0–4BR range).\n"},"as_of":{"type":"string","description":"Only on time-series facts (`unemployment_rate_pct`) — the\n`YYYY-MM` month the value reflects.\n"}}},"AtlasArea":{"type":"object","description":"Identifies a bounded geographic area in the Atlas catalog","properties":{"slug":{"type":"string"},"name":{"type":"string","description":"Human-readable area name, e.g. \"Hyde Park, Cincinnati, OH\""},"type":{"type":"string","description":"UI-facing type label (e.g. \"neighborhood\", \"metro\", \"ZIP code\").\n"},"area_type":{"type":"string","description":"Machine area type identifier, e.g. `metro`, `city`, `zcta`,\n`neighborhood`, `school_district`, `state`, `county`.\n"},"geoid":{"type":"string","nullable":true,"description":"Census FIPS / GEOID (ZCTA code for ZIP areas) for this area, e.g.\n`39` (state), `17140` (CBSA), `39061` (county). Present on the\naddress-linkage `atlas` array; feed it back to\n`/api/v1/atlas/search?geoid=` or `/atlas/facts?geoid=`. Null for\narea types without a FIPS/GEOID code.\n"}}},"AtlasSearchResult":{"type":"object","description":"A matched Atlas geographic area","properties":{"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"area_type":{"type":"string"},"land_area_sq_mi":{"type":"number","nullable":true},"record_density":{"type":"number","nullable":true,"description":"Listings per square mile, rounded to 2 significant figures."}}},"AtlasFacts":{"type":"object","description":"Full Atlas bundle for an area. Rent data is always present;\nexternal sources (`acs`, `hud_fmr`, `hud_chas`, `bls_laus`,\n`bls_qcew`, `census_bps`, `pep`, `fhfa_hpi`, plus `nces_ccd` / `nces_ccd_finance` on\nschool districts) are gated by the caller's account access and\n**silently omitted** when not available. A parallel\n`sources` object documents the provenance of whatever is included\n(program, vintage, area GEOID + summary level, and per-metric\ncalculation notes and deep links into the source database).\n","properties":{"area":{"allOf":[{"$ref":"#/components/schemas/AtlasArea"}],"description":"Includes an extra `parent_slug` for navigation upward."},"rent_breakdown":{"$ref":"#/components/schemas/AtlasRentBreakdown"},"facts":{"$ref":"#/components/schemas/AtlasFactSources"},"sources":{"$ref":"#/components/schemas/AtlasSourceProvenance"},"calculated_at":{"type":"string","format":"date-time","description":"When the underlying analysis was computed. May be up to 12 hours\nold due to caching.\n"},"credits_remaining":{"type":"integer"},"token":{"type":"string","description":"Search token; reusable with `/nearby_comps`."}}},"AtlasRentBreakdown":{"type":"object","description":"Aggregate rent statistics for the bounded area, plus per-bedroom and\nper-property-type breakdowns.\n","properties":{"samples":{"type":"integer"},"mean":{"type":"number"},"median":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"},"percentile_25":{"type":"number"},"percentile_75":{"type":"number"},"bedroom_stats":{"type":"object","description":"Map keyed by bedroom count as a string (\"0\" = studio, \"1\", \"2\", …).\nEach value has `min`, `max`, `mean`, and `count`.\n","additionalProperties":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"mean":{"type":"number"},"count":{"type":"integer"}}}},"grouped_breakdown_stats":{"type":"object","description":"Two-level map: property type (`apartment`, `house`, etc.) → bedroom\ncount (string) → stats.\n","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"avg":{"type":"number"},"median":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"},"percentile_25":{"type":"number"},"percentile_75":{"type":"number"}}}}},"derived":{"type":"object","description":"Rent growth and investor ratios computed by the weekly first-party\nrent rollup (same numbers `rent.yoy_pct`, `rent.gross_yield_pct`,\n`rent.rent_to_income_pct` and `rent.vs_acs_gross_rent_pct` rank\nand screen on). **Silently omitted** when the account lacks the\nrent-metrics entitlement or no ratio is computable for the area\nyet. Individual keys are absent when their input is missing (no\nCensus figure, no year-ago rent point). The ACS-denominated\nratios use the ACS vintage current when the rollup ran\n(`acs_vintage`), not necessarily the vintage in `facts.acs`.\n","properties":{"yoy_pct":{"type":"number","description":"Percent change in the overall median rent vs. the same trailing-year window twelve months earlier."},"yoy_basis":{"type":"string","enum":["snapshot","live"],"description":"Year-ago point source: the area's own weekly rent snapshot 52 weeks back, or a year-ago analysis while the snapshot index is younger than a year."},"gross_yield_pct":{"type":"number","description":"Median rent × 12 ÷ ACS median home value × 100."},"rent_to_income_pct":{"type":"number","description":"Median rent × 12 ÷ ACS median household income × 100."},"vs_acs_gross_rent_pct":{"type":"number","description":"(Median rent − ACS median gross rent) ÷ ACS median gross rent × 100; positive = asking rents above the Census benchmark."},"acs_vintage":{"type":"string","description":"ACS 5-year vintage span (e.g. 2019-2023) behind the ACS-denominated ratios."},"computed_at":{"type":"string","format":"date-time","description":"When the weekly rollup computed these ratios."}}},"building_types":{"type":"object","description":"Houses vs apartments from the weekly first-party rent rollup,\nmedianed over **every** listing in the trailing year (not the\nanalysis sample behind `median`/`bedroom_stats`). Houses include\nduplexes; apartments include condos and townhouses. Same numbers\nthe `rent.median_house`, `rent.median_apartment`,\n`rent.median_3br_house` and `rent.yoy_pct_*` metrics rank and\nscreen on. Medians and YoY are\nnull below 10 listings (YoY needs 10 in the year-ago window too).\n**Silently omitted** without the rent-metrics entitlement or before\nthe area's first rollup with this section.\n","properties":{"house":{"$ref":"#/components/schemas/AtlasRentBuildingType"},"apartment":{"$ref":"#/components/schemas/AtlasRentBuildingType"},"yoy_basis":{"type":"string","nullable":true,"enum":["snapshot","live"],"description":"Year-ago point source, as for `derived.yoy_basis`."},"computed_at":{"type":"string","format":"date-time"}}}}},"AtlasRentBuildingType":{"type":"object","properties":{"median":{"type":"number","nullable":true,"description":"Median asking rent; null below 10 listings."},"yoy_pct":{"type":"number","nullable":true,"description":"Percent change in the median vs. the same window a year earlier."},"by_bedroom":{"type":"object","description":"Keyed by bedroom count 0–4 (4 = 4+), each with the same median / yoy_pct fields.","additionalProperties":{"type":"object","properties":{"median":{"type":"number","nullable":true},"yoy_pct":{"type":"number","nullable":true}}}}}},"AtlasFactSources":{"type":"object","description":"External data sources for the area. Keys are present only if the\ncaller's account has access to the source **and** the area\nhas data for that source. Treat absent keys as \"no data or no access\".\n","properties":{"acs":{"type":"object","description":"American Community Survey 5-year demographics and housing facts.\nKeys are omitted when the Census Bureau suppresses or does not\npublish the underlying estimate for the area, so the shape varies\nby area type and size. Neighborhoods inherit the containing FIPS\ngeography's values (see `sources.acs.inherited_from`).\n","additionalProperties":true,"properties":{"median_household_income":{"type":"number","description":"Median annual household income (USD)"},"median_age":{"type":"number"},"bachelors_or_higher_pct":{"type":"number"},"poverty_rate_pct":{"type":"number"},"race_white_pct":{"type":"number"},"race_black_pct":{"type":"number"},"race_asian_pct":{"type":"number"},"race_hispanic_pct":{"type":"number"},"median_home_value":{"type":"number","description":"Median owner-estimated home value (USD)"},"median_gross_rent":{"type":"number","description":"Median gross rent","contract rent plus utilities (USD/month)":null},"median_real_estate_taxes":{"type":"number","description":"Median annual property tax bill (USD)"},"effective_property_tax_rate_pct":{"type":"number","description":"Aggregate taxes paid ÷ aggregate owner-occupied value × 100"},"renter_share_pct":{"type":"number"},"vacancy_rate_pct":{"type":"number","description":"Gross vacancy — all vacant units ÷ all housing units × 100"},"cost_burdened_renter_pct":{"type":"number"},"mean_commute_minutes":{"type":"number"},"population":{"type":"integer","description":"Total population (B01003)"},"households":{"type":"integer","description":"Total households (B11001)"},"housing_units":{"type":"integer","description":"Total housing units","occupied and vacant (B25002)":null},"renter_households":{"type":"integer","description":"Renter-occupied housing units (B25003)"},"rental_vacancy_rate_pct":{"type":"number","description":"Census rental vacancy rate — vacant-for-rent ÷ (renter-occupied + vacant-for-rent) × 100 (B25004, B25003)"},"multifamily_5plus_share_pct":{"type":"number","description":"Share of housing units in structures of 5+ units (B25024)"},"median_year_built":{"type":"integer","description":"Median year structures were built; bottom-coded at 1939 (B25035)"},"gross_rent_yield_pct":{"type":"number","description":"Median gross rent × 12 ÷ median home value × 100 (2 decimals)"},"price_to_rent_ratio":{"type":"number","description":"Median home value ÷ (median gross rent × 12) (1 decimal)"},"rent_to_income_pct":{"type":"number","description":"Median gross rent × 12 ÷ median household income × 100 (1 decimal)"}}},"hud_fmr":{"type":"object","description":"HUD Fair Market Rents by bedroom count. HUD sets FMRs per HUD Metro\nFMR Area, and splits some metros into several; a metro's values are\nthose of the area containing its principal city (see fmr_area).\nA ZIP without a Small Area FMR inherits its county's FMR\n(`inherited_from`); in New England, where HUD sets FMRs by town, it\ninherits the town's, and `inherited_from` adds `town_geoid` and\n`town_name`.\n","properties":{"studio":{"type":"number"},"one_br":{"type":"number"},"two_br":{"type":"number"},"three_br":{"type":"number"},"four_br":{"type":"number"},"fmr_area":{"type":"string","description":"Metros only. The HUD Metro FMR Area the values belong to."},"fmr_area_count":{"type":"integer","description":"Metros only. How many FMR areas HUD prices the metro in. Omitted when unknown. An fmr_area ending in \"MSA\" covers the whole metro; a \"HUD Metro FMR Area\" is a subset or a different set of counties."}}},"hud_chas":{"type":"object","description":"HUD Comprehensive Housing Affordability Strategy renter cost burden.\nMetro values are synthesized by summing constituent counties; ZIP\nand neighborhood values are inherited from the containing county.\nNil fields are omitted.\n","properties":{"cost_burdened_renter_pct":{"type":"number","description":"Share of renter households paying \u003e30% of income on housing (percent)"},"severely_cost_burdened_renter_pct":{"type":"number","description":"Share of renter households paying \u003e50% of income on housing (percent)"},"low_income_cost_burdened_pct":{"type":"number","description":"Cost-burdened (\u003e30%) share of renter households at or below 50%\nof HUD Area Median Family Income — the ≤30% and 30–50% HAMFI\nbands combined by household count (percent). Absent until the\narea's CHAS row carries per-band household counts.\n"},"cost_burdened_renter_households":{"type":"integer"},"renter_households_total":{"type":"integer"},"by_income_band":{"type":"array","description":"Per-HAMFI-band burden shares, lowest band first","items":{"type":"object","properties":{"key":{"type":"string","example":"le_30_ami"},"label":{"type":"string","example":"≤30% AMI"},"burdened_pct":{"type":"number"},"severely_burdened_pct":{"type":"number"}}}},"vintage":{"type":"string","example":"2018-2022"},"synthesized":{"type":"boolean","description":"True for metro rows aggregated from counties"}}},"bls_laus":{"type":"object","description":"Local Area Unemployment Statistics (BLS LAUS). Nil fields are omitted.\n","properties":{"current_rate":{"type":"number","description":"Most recent unemployment rate (percent)"},"current_month":{"type":"string","pattern":"^\\d{4}-\\d{2}$","description":"Month the rate is for, ISO `YYYY-MM`"},"rate_12mo_ago":{"type":"number","description":"Unemployment rate in the same month one year earlier (percent)"},"rate_change_12mo_pts":{"type":"number","description":"`current_rate` − `rate_12mo_ago`, in percentage points (negative\n= unemployment fell). Absent while the stored series is\nshorter than 13 months.\n"}}},"bls_qcew":{"type":"object","description":"Quarterly Census of Employment and Wages (BLS QCEW), all industries\nand ownerships. Nil fields (e.g. prior-year values on a first\nquarter with no history) are omitted.\n","properties":{"current_quarter":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","example":"2025-Q4"},"current_avg_weekly_wage":{"type":"integer","description":"Average weekly wage, USD"},"current_avg_employment":{"type":"integer","description":"Average monthly covered employment in the quarter"},"prior_year_quarter":{"type":"string","example":"2024-Q4"},"prior_year_avg_weekly_wage":{"type":"integer"},"prior_year_avg_employment":{"type":"integer"},"wage_yoy_pct":{"type":"number","description":"Same-quarter year-over-year change in average weekly wage (percent)"},"employment_yoy_pct":{"type":"number","description":"Same-quarter year-over-year change in average employment (percent)"},"industry_mix_quarter":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"Quarter the industry-mix fields describe. Can trail\n`current_quarter` (BLS publishes metro industry detail about\ntwo quarters after the county figures).\n"},"industry_hhi":{"type":"integer","description":"Herfindahl-Hirschman index of private employment across the 11\nNAICS supersectors, 0–10,000 (lower = more diverse; an even\nsplit is ~909). Employment in BLS-suppressed cells is split\nevenly across them; omitted when suppressed cells hold more\nthan 10% of private jobs.\n"},"top_industry_share_pct":{"type":"number","description":"Largest supersector's share of private employment (percent). Omitted under the same suppression rule."},"top_industry_name":{"type":"string","example":"Education and health services"},"government_share_pct":{"type":"number","description":"(Total covered − private employment) ÷ total covered employment (percent) — federal, state, and local payrolls"},"industry_suppressed_share_pct":{"type":"number","description":"Share of private employment in BLS-suppressed supersector cells (percent)"},"industry_shares":{"type":"array","description":"Per-supersector breakdown, largest first; `share_pct` and `employment` are null for suppressed cells.","items":{"type":"object","properties":{"code":{"type":"string","example":"1025"},"name":{"type":"string"},"employment":{"type":"integer","nullable":true},"share_pct":{"type":"number","nullable":true}}}}}},"census_bps":{"type":"object","description":"Census Building Permits Survey, residential units authorized in the\nvintage year. Nil fields are omitted; `yoy_change_pct` is\nsuppressed when the prior-year base is under 500 units.\n","properties":{"vintage_year":{"type":"integer","example":2025},"total_units":{"type":"integer"},"single_family_units":{"type":"integer"},"multi_family_units":{"type":"integer","description":"Units in buildings with 2+ units"},"five_plus_units":{"type":"integer","description":"Units in buildings with 5+ units (closest proxy for rental supply)"},"multi_family_share_pct":{"type":"number","description":"multi_family_units ÷ total_units × 100"},"prior_year_total_units":{"type":"integer"},"yoy_change_pct":{"type":"number","description":"Year-over-year change in total units permitted (percent)"}}},"nces_ccd":{"type":"object","description":"NCES Common Core of Data school-district directory. Present only\non school-district areas. Includes `enrollment`, `student_teacher_ratio`,\n`number_of_schools`, `grade_span`, `locale`, `vintage`.\n","additionalProperties":true},"nces_ccd_finance":{"type":"object","description":"NCES F-33 per-pupil finance. Present only on school-district areas.\nIncludes `per_pupil_spending`, `total_current_expenditures`,\n`enrollment`, `vintage`.\n","additionalProperties":true},"pep":{"type":"object","description":"Census Population Estimates Program (vintage-versioned; the\nnewest vintage is served). Published for states, metros,\ncounties, and incorporated places; neighborhoods inherit their\ncontaining place/county (flagged via `inherited_from`).\nComponents of change (`births`, `deaths`, `natural_change`,\n`domestic_migration`, `international_migration`,\n`net_migration`, `net_migration_per_1k`) are present for\nstates, metros, and counties only — the sub-county file is\npopulation-only, so they are omitted for places.\n","properties":{"population":{"type":"integer","description":"Resident population as of July 1 of `estimate_year`"},"population_prior_year":{"type":"integer"},"population_base_2020":{"type":"integer","description":"April 1, 2020 Census estimates base"},"population_yoy_pct":{"type":"number","description":"(population − prior year) ÷ prior year × 100"},"population_since_2020_pct":{"type":"number","description":"(population − 2020 base) ÷ 2020 base × 100 — a 2020-to-date span, not a rolling five years"},"births":{"type":"integer"},"deaths":{"type":"integer"},"natural_change":{"type":"integer"},"domestic_migration":{"type":"integer","description":"Net domestic migration over the vintage year (negative = net out-migration)"},"international_migration":{"type":"integer"},"net_migration":{"type":"integer"},"net_migration_per_1k":{"type":"number","description":"net_migration ÷ population × 1,000"},"estimate_year":{"type":"integer","description":"July 1 reference year of the latest estimate (= vintage)"},"vintage":{"type":"string","description":"Human-readable vintage label, e.g. \"Census PEP Vintage 2025\""}}},"fhfa_hpi":{"type":"object","description":"FHFA House Price Index. Quarterly all-transactions index (NSA) for\nstates and metros, annual developmental index for counties and\nZIP codes (matched to the ZCTA of the same code — `keying`\n`zip5_as_zcta`); neighborhoods carry an inherited copy. The index\nlevel is only comparable within an area's own series (see\n`index_base`); compare areas on the appreciation percentages.\n","properties":{"index":{"type":"number","description":"Latest index level"},"period":{"type":"string","description":"Latest period, `YYYYQn` (quarterly) or `YYYY` (annual)"},"index_prior_year":{"type":"number","nullable":true},"index_5yr_ago":{"type":"number","nullable":true},"yoy_pct":{"type":"number","nullable":true,"description":"1-year appreciation (percent)"},"five_year_pct":{"type":"number","nullable":true,"description":"5-year appreciation (percent)"},"annual_change_pct":{"type":"number","nullable":true,"description":"FHFA's published annual change (county / ZIP only)"},"series":{"type":"string","enum":["all_transactions_nsa","developmental_annual"]},"index_base":{"type":"string","description":"What 100 means for this series, e.g. `1995Q1 = 100`"},"keying":{"type":"string","enum":["usps_state_abbreviation","cbsa","county_fips","zip5_as_zcta"]},"vintage":{"type":"string","description":"Human-readable vintage, e.g. `FHFA HPI 2026 Q2`"}}},"osm":{"type":"object","description":"OpenStreetMap amenity / walkability counts, computed per boundary\npolygon. Present only on city (`place`), ZIP (`zcta`), and\nneighborhood areas. Includes `amenity_count`, `amenity_density`\n(everyday amenities per km²), `transit_stop_count`, `park_count`,\n`area_sqkm`, and `vintage`. Coverage is volunteer-contributed and\nuneven — sparse in rural areas.\n","additionalProperties":true},"fema_nri":{"type":"object","description":"FEMA National Risk Index, county table. Present on counties and,\ninherited from the containing county, on neighborhoods (see\n`inherited_from`). Every `*_score` is a 0–100 national percentile\nrank among US counties (higher = more risk, except\n`community_resilience_score`, where higher is better). `*_rating`\nstrings are FEMA's categorical labels (\"Very Low\" … \"Very High\",\n\"Not Applicable\", \"Insufficient Data\"). A hazard score is absent\nwhere FEMA rates the hazard Not Applicable (e.g. coastal flooding\ninland). Area-wide figures, not a flood-zone determination for any\nproperty.\n","properties":{"risk_score":{"type":"number","description":"Composite risk score across 18 natural hazards"},"risk_rating":{"type":"string"},"eal_score":{"type":"number","description":"Expected annual loss score"},"eal_rating":{"type":"string"},"eal_total_usd":{"type":"integer","description":"Expected annual loss in dollars (buildings, agriculture, and population at FEMA's value of a statistical life)"},"eal_building_usd":{"type":"integer","description":"Expected annual building loss in dollars"},"eal_rate_building_pct":{"type":"number","description":"Expected annual building loss as a percent of total building value"},"social_vulnerability_score":{"type":"number"},"social_vulnerability_rating":{"type":"string"},"community_resilience_score":{"type":"number","description":"Higher is better"},"community_resilience_rating":{"type":"string"},"inland_flooding_risk_score":{"type":"number","description":"Riverine flooding before NRI v1.20"},"inland_flooding_risk_rating":{"type":"string"},"coastal_flooding_risk_score":{"type":"number"},"coastal_flooding_risk_rating":{"type":"string"},"hurricane_risk_score":{"type":"number"},"hurricane_risk_rating":{"type":"string"},"wildfire_risk_score":{"type":"number"},"wildfire_risk_rating":{"type":"string"},"population":{"type":"integer","description":"County population used by NRI (2020 Census)"},"building_value_usd":{"type":"integer","description":"Total building value NRI uses as exposure"},"vintage":{"type":"string","description":"NRI release, e.g. \"December 2025\" (v1.20)"}}},"irs_soi_migration":{"type":"object","description":"IRS Statistics of Income county/state migration, from year-to-year\naddress changes on tax returns. Households = tax returns; AGI in\ndollars from the year-2 return. Published for states and counties;\nneighborhoods carry their county's figures (`inherited_from`).\nIncludes `inflow_households`, `outflow_households`,\n`net_households`, `net_households_per_1k`, `inflow_agi`,\n`outflow_agi`, `net_agi`, `avg_agi_in_movers`,\n`avg_agi_out_movers`, `avg_agi_nonmigrants`, the same-state /\nother-state / abroad breakdowns, and `vintage`. Suppressed cells\n(under 20 returns) are omitted.\n","additionalProperties":true}}},"AtlasSourceProvenance":{"type":"object","description":"Provenance sidecar to `facts`, with one entry per source actually\nincluded above (same key set, same access/data gating). Each entry\ntraces the figures back to their government source so an agent can\ncite them or dig deeper into the raw tables.\n\nCrucially, `geoid` + `summary_level` make explicit that every figure\nis computed at THIS area's own geographic level: a city's effective\nproperty-tax rate is its place-level figure and its county's is the\ncounty-level figure — the same survey at two different geographies,\nnot one number shown twice.\n","additionalProperties":{"type":"object","description":"One source's provenance (e.g. the `acs` entry).","properties":{"name":{"type":"string","description":"Vintage-agnostic source attribution, e.g. \"U.S. Census Bureau, American Community Survey\"."},"vintage":{"type":"string","nullable":true,"description":"Human-readable vintage label for this area, e.g. \"ACS 2019–2023 5-year estimates\"."},"geoid":{"type":"string","nullable":true,"description":"Census FIPS / GEOID (or ZCTA) of the area these figures describe."},"summary_level":{"type":"string","nullable":true,"description":"Census summary level of the area — `state`, `metro`, `county`, `place`, or `zcta`."},"methodology_url":{"type":"string","nullable":true,"description":"Link to the source program's methodology page."},"metrics":{"type":"array","description":"Per-metric documentation for this source.","items":{"type":"object","properties":{"key":{"type":"string","description":"Metric key (matches the field name in `facts.\u003csource\u003e` for ACS), e.g. `effective_property_tax_rate_pct`."},"label":{"type":"string"},"description":{"type":"string"},"derivation":{"type":"string","description":"How the figure is calculated, when it isn't a raw published value. Omitted for direct values."},"tables":{"type":"array","description":"Underlying source table code(s) the metric draws from, e.g. `[\"B25090\",\"B25082\"]`. ACS only.","items":{"type":"string"}},"deep_link":{"type":"string","description":"Link to the underlying source data. For ACS at the\nstate/county/place/ZCTA level this is a geography-specific\ndata.census.gov table URL that opens THIS area's exact\nfigure; otherwise it is the table-level landing page.\n"}}}}}}},"NearbyComps":{"type":"object","properties":{"search_address":{"type":"string","nullable":true},"search_latitude":{"type":"string","example":"42.358655","description":"Decimal latitude of the search point, encoded as a string."},"search_longitude":{"type":"string","example":"-71.054643","description":"Decimal longitude of the search point, encoded as a string."},"count":{"type":"integer","description":"Comps in the analysis sample. At most 25 of them are listed in `nearby_properties`, so this can be larger."},"nearby_properties":{"type":"array","items":{"$ref":"#/components/schemas/CompProperty"}},"credits_remaining":{"type":"integer","description":"Premium credits left in the wallet"},"end_date":{"type":"string","format":"date","nullable":true,"description":"The search's end date (a token search keeps its own), or null for current comps."}}},"CompProperty":{"type":"object","description":"A single comparable rental listing","properties":{"address":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"distance":{"oneOf":[{"type":"number","description":"Distance from search anchor in miles"},{"type":"string","enum":["n/a"],"description":"Returned for ZIP and neighborhood searches, which have no single search point."}]},"price":{"type":"number","description":"Listed rent in USD"},"sqft":{"type":"integer","nullable":true},"dollar_sqft":{"type":"number","nullable":true},"bedrooms":{"type":"string","description":"Decoded bedroom string (`studio`, `1`, `2`, …)"},"baths":{"type":"string","nullable":true},"property_type":{"type":"string","nullable":true},"last_seen":{"type":"string","format":"date","description":"Date the listing was last observed"},"outlier":{"type":"boolean","description":"Whether this comp was flagged as a statistical outlier (Grubbs' test) and therefore excluded from the rent statistics. Returned for every comp so consumers can see which listings the analysis dropped."}}},"BatchSummaryRequest":{"type":"object","required":["properties"],"properties":{"properties":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/BatchProperty"}},"defaults":{"$ref":"#/components/schemas/BatchDefaults"}}},"BatchProperty":{"type":"object","required":["bedrooms"],"properties":{"address":{"type":"string","description":"Required if latitude/longitude are not provided"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"bedrooms":{"type":"integer","minimum":0,"maximum":6},"baths":{"type":"string","enum":["1","1.5","1.5+"]},"building_type":{"type":"string","enum":["apartment","house"]},"look_back_days":{"type":"integer","minimum":90,"maximum":1460},"end_date":{"type":"string","format":"date","description":"Historical search end date (limited availability). Same rules as `/summary`'s `end_date`."},"min_price":{"type":"integer","minimum":250,"maximum":100000},"max_price":{"type":"integer","minimum":500,"maximum":100000},"min_sqft":{"type":"integer","minimum":250,"maximum":10000},"max_sqft":{"type":"integer","minimum":500,"maximum":10000},"radius_miles":{"type":"number","minimum":0.1,"maximum":10,"description":"Fixed radius; omit for Smart Radius. Same rules as `/summary`."}}},"BatchDefaults":{"type":"object","description":"Default values applied to every property in the batch unless overridden.\nA property value of null or \"\" does not override a default. Defaults are\nvalidated with the same rules as the property fields; an invalid default\nis a 422 with a `Defaults:` error even if every property overrides it.\nEach property's filters are also checked with its defaults applied, so a\ndefault contradicting a property's own value is a `Property N:` error.\n","properties":{"look_back_days":{"type":"integer","minimum":90,"maximum":1460},"end_date":{"type":"string","format":"date","description":"Historical search end date (limited availability) for every property that doesn't set its own."},"baths":{"type":"string","enum":["1","1.5","1.5+"]},"building_type":{"type":"string","enum":["apartment","house"]},"min_price":{"type":"integer","minimum":250,"maximum":100000},"max_price":{"type":"integer","minimum":500,"maximum":100000},"min_sqft":{"type":"integer","minimum":250,"maximum":10000},"max_sqft":{"type":"integer","minimum":500,"maximum":10000},"radius_miles":{"type":"number","minimum":0.1,"maximum":10,"description":"Fixed radius; omit for Smart Radius. Same rules as `/summary`."}}},"BatchSummaryAccepted":{"type":"object","properties":{"batch_id":{"type":"string","description":"Poll this via `GET /api/v1/batch_summary/{batch_id}`"},"status":{"type":"string","enum":["pending"]},"properties_count":{"type":"integer"},"poll_url":{"type":"string","format":"uri"}}},"BatchSummaryStatus":{"type":"object","description":"Batch progress and (once complete) per-property results. While in\n`pending` or `processing` state, only progress metadata is populated.\n","properties":{"batch_id":{"type":"string"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"progress":{"type":"object","description":"Present while `status == processing`","properties":{"completed":{"type":"integer"},"total":{"type":"integer"},"percent":{"type":"number"}}},"total_requested":{"type":"integer"},"total_successful":{"type":"integer"},"total_failed":{"type":"integer"},"credits_charged":{"type":"integer"},"credits_remaining":{"type":"integer"},"processing_time_ms":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchResultItem"}}}},"BatchResultItem":{"type":"object","description":"One row of batch results. `status` indicates whether this property was analyzed successfully.","properties":{"input":{"$ref":"#/components/schemas/BatchProperty"},"status":{"type":"string","enum":["ok","insufficient_data","error"]},"summary":{"$ref":"#/components/schemas/RentSummary","nullable":true},"error":{"type":"string","nullable":true}}},"PropertyRents":{"type":"object","properties":{"formatted_address":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"count":{"type":"integer"},"average_update_days":{"type":"number","description":"Mean staleness (days) of the matched listings"},"property_listings":{"type":"array","items":{"$ref":"#/components/schemas/PropertyListing"}},"premium_credits_remaining":{"type":"integer"}}},"PropertyListing":{"type":"object","properties":{"id":{"type":"integer"},"bedrooms":{"type":"string"},"baths":{"type":"string","nullable":true},"price":{"type":"number"},"sqft":{"type":"integer","nullable":true},"price_per_sqft":{"type":"number","nullable":true},"last_seen":{"type":"string","format":"date"}}},"ProReportQueued":{"type":"object","properties":{"status":{"type":"string","enum":["added to queue"]},"token":{"type":"string"},"pro_report_credits_remaining":{"type":"integer"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"ProReportStatus":{"type":"object","properties":{"status":{"type":"string","enum":["in queue, retry later"]},"retry_after":{"type":"integer"},"token":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"ProReportReady":{"type":"object","properties":{"status":{"type":"string","enum":["ready","Pro Report Ready"]},"token":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"ProReportNotRequested":{"type":"object","properties":{"status":{"type":"string"},"token":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"WhatsNew":{"type":"object","properties":{"categories":{"type":"object","description":"Map of category key to human label.","additionalProperties":{"type":"string"},"example":{"atlas":"Atlas","api":"API","rentometer":"Rentometer","tools_company":"Tools \u0026 Company"}},"release_notes":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseNote"}}}},"ReleaseNote":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"category":{"type":"string","enum":["atlas","api","rentometer","tools_company"]},"category_label":{"type":"string"},"blurb":{"type":"string","description":"Short plain-English summary of the update."},"featured":{"type":"boolean"},"published_at":{"type":"string","format":"date-time","nullable":true},"url":{"type":"string","format":"uri","description":"Canonical link to the note's page on the site."}}},"RateLimit":{"type":"object","properties":{"dimension":{"type":"string","enum":["api_key","ip"]},"key_prefix":{"type":"string","nullable":true,"description":"First 6 characters of the API key, or null for IP-dimension responses"},"tier":{"type":"string","enum":["pro","essential","free","anonymous"]},"windows":{"type":"object","properties":{"minute":{"$ref":"#/components/schemas/RateLimitWindow"},"hour":{"$ref":"#/components/schemas/RateLimitWindow"},"day":{"$ref":"#/components/schemas/RateLimitWindow"}}}}},"RateLimitWindow":{"type":"object","properties":{"limit":{"type":"integer","nullable":true},"used":{"type":"integer"},"remaining":{"type":"integer"},"reset_at":{"type":"string","format":"date-time"}}},"AuthSummary":{"type":"object","description":"Account, plan, and credit summary returned by `/api/v1/auth`","properties":{"authorized":{"type":"boolean","description":"Always `true` on a 200 response"},"account_email":{"type":"string","format":"email"},"user_id":{"type":"integer","description":"Stable identifier for the authenticated user"},"user_tier":{"type":"string","enum":["admin","teams","mobile","essential","pro","pro-lite","trial","expired","unconfirmed","free"],"description":"Coarse account tier. Use this for feature gating. Exactly one\nvalue is returned per response.\n\n| Value | Meaning |\n|---|---|\n| `pro` | Active Pro subscription (any current Pro plan). |\n| `essential` | Active Pro Essential subscription. |\n| `pro-lite` | Legacy Pro Lite subscription. |\n| `teams` | Member of an active Teams account. |\n| `mobile` | Subscribed via the iOS or Android app. |\n| `trial` | On an active free Pro trial. |\n| `expired` | Previously subscribed; the most recent subscription has lapsed. |\n| `unconfirmed` | Account email has not yet been confirmed. |\n| `free` | Free account with no current subscription. |\n| `admin` | Internal Rentometer staff account. |\n\nTeam members always return `teams` even when the underlying\nteam subscription is a Pro plan; accept both `teams` and `pro`\nif you want to treat them equivalently for a feature check.\n`plan_name` is `\"Team Plan\"` for `teams` users regardless of\nthe underlying team subscription's plan.\n"},"plan_id":{"type":"string","nullable":true,"description":"Machine-readable plan slug (e.g. `\"pro-standard-2022\"`,\n`\"pro-monthly-2020\"`). For active team members, this is the\nunderlying team subscription's plan slug — not a `\"teams\"`\nsentinel. Use `user_tier` for tier-based feature gating, and\n`plan_id` for surfacing the exact subscription product.\n`null` when the user has no current subscription.\n"},"plan_name":{"type":"string","nullable":true,"description":"Human-readable plan name (e.g. `\"Pro Standard\"`, `\"Pro Monthly\"`).\nReturns `\"Team Plan\"` for active team members. `null` when the\nuser has no current subscription.\n"},"subscription_expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the current subscription expires (ISO 8601). For active\nteam members, this is the team subscription's expiry.\n`null` when the user has no current subscription, or when the\nsubscription is billed through Stripe or Apple — those renew\nuntil cancelled, so there is no fixed local expiry.\n"},"credits_remaining":{"type":"integer","description":"Alias of `quickview_credits_remaining`, kept for backward compatibility"},"quickview_credits_remaining":{"type":"integer"},"premium_credits_remaining":{"type":"integer"},"pro_report_credits_remaining":{"type":"integer"}}},"Link":{"type":"object","description":"HATEOAS-style related-action link","properties":{"rel":{"type":"string","description":"Relationship label, e.g. `download`, `check status`, `request pro report`, `nearby comps`"},"href":{"type":"string","format":"uri","description":"Fully-formed next-step URL. Report-flow links (request pro report, check status, download, nearby comps) carry a signed `auth_key` query parameter scoped to this search, so the link can be followed directly without re-sending your API key. Passing your own API key (api_key query parameter or Authorization header) also works and takes precedence."}}},"Error":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}},"error_type":{"type":"string","nullable":true},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}}}}}