<!-- Agent Datasets docs · Real Estate REST endpoints · canonical: https://www.agentdatasets.com/docs/rest/real-estate · rendered from https://www.agentdatasets.com -->

# Real Estate REST endpoints

US housing and real-estate indicators — FHFA house price indices and related series.

4 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md documents the same operations for MCP clients.

## GET /v1/re/geographies/search

Geographies Search

Resolve a place to geography keys, parents, and outgoing crosswalks.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| query | query | `string` | yes | — | — | U.S. place, postal abbreviation, or Census/OMB code |
| limit | query | `integer` | no | 10 | min 1, max 50 | Maximum ranked matches to return |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/re/geographies/search?query=QUERY"
```

### Response

`200` Successful Response — `REGeographySearchResult`.

- `data` `REGeographySearchData` (required)
  - `query` `string` (required)
  - `matches` `array<REGeographyMatch>` (required)
    - `geo_key` `string` (required)
    - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
    - `code` `string` (required)
    - `name` `string` (required)
    - `state_code` `string | null` (required)
    - `score` `number` (required)
    - `match_reason` `"code_exact" | "postal_exact" | "name_exact" | "alias_exact" | "name_fuzzy" | "alias_fuzzy"` (required)
    - `parents` `array<REParentGeography>` (required)
      - `geo_key` `string` (required)
      - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
      - `code` `string` (required)
      - `name` `string` (required)
    - `crosswalks` `array<REGeographyCrosswalk>` (required)
      - `geo_key` `string` (required)
      - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
      - `code` `string` (required)
      - `name` `string` (required)
      - `relation` `"zcta_county" | "county_cbsa"` (required)
      - `weight` `string | null` (required)
      - `source` `string` (required)
      - `vintage` `string` (required)
- `meta` `REGeographySearchMeta` (required) — Base meta plus the constant Census non-endorsement notice carried by every geography-search payload — the matches, parents, and crosswalks are Census Bureau / OMB derived.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
  - `notice` `string`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/re/hazard-profile

Hazard Profile

Return one county's newest FEMA National Risk Index profile.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| fips_or_geo_key | query | `string` | yes | — | — | 5-digit county FIPS or county geo_key |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/re/hazard-profile?fips_or_geo_key=FIPS_OR_GEO_KEY"
```

### Response

`200` Successful Response — `REHazardProfileResult`.

- `data` `REHazardProfileData` (required) — One county's newest FEMA NRI release and its persisted hazard slices.
  - `fips` `string` (required)
  - `county_name` `string | null` (required)
  - `state_name` `string | null` (required)
  - `state_abbrev` `string | null` (required)
  - `geo_key` `string | null` (required)
  - `release_version` `string` (required)
  - `release_date` `string (date)` (required)
  - `risk_score` `string | null` (required)
  - `risk_rating` `string | null` (required)
  - `risk_value` `string | null` (required)
  - `risk_percentile` `string | null` (required)
  - `eal_total` `string | null` (required)
  - `eal_score` `string | null` (required)
  - `eal_rating` `string | null` (required)
  - `eal_percentile` `string | null` (required)
  - `sovi_score` `string | null` (required)
  - `sovi_rating` `string | null` (required)
  - `resl_score` `string | null` (required)
  - `resl_rating` `string | null` (required)
  - `population` `integer | null` (required)
  - `building_value` `string | null` (required)
  - `agriculture_value` `string | null` (required)
  - `hazards` `array<REHazardProfileHazard>` (required)
    - `hazard_code` `string` (required)
    - `hazard_name` `string` (required)
    - `risk_score` `string | null` (required)
    - `risk_rating` `string | null` (required)
    - `risk_value` `string | null` (required)
    - `eal_total` `string | null` (required)
    - `eal_score` `string | null` (required)
    - `eal_rating` `string | null` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/re/series

Series

Return one real-estate series' bounded, newest-first observations.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| series_key | query | `string` | yes | — | — | Exact series_key returned by real-estate series search |
| start | query | `string (date) \| null` | no | — | — | Inclusive observation-period start (YYYY-MM-DD) |
| end | query | `string (date) \| null` | no | — | — | Inclusive observation-period end (YYYY-MM-DD) |
| limit | query | `integer` | no | 100 | min 1, max 500 | Observations to return, newest first |
| cursor | query | `string \| null` | no | — | — | Opaque cursor from pagination.next_cursor |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/re/series?series_key=SERIES_KEY"
```

### Response

`200` Successful Response — `RESeriesResult`.

- `data` `RESeriesData` (required)
  - `series_key` `string` (required)
  - `dataset_key` `string` (required)
  - `source` `"fhfa" | "hud" | "census" | "noaa" | "fdic_sod" | "abs" | "nyc_acris"` (required)
  - `source_series_id` `string` (required)
  - `title` `string` (required)
  - `attribution` `string | null` (required)
  - `units` `string` (required)
  - `base_period` `string | null` (required)
  - `currency` `string | null` (required)
  - `frequency` `"daily" | "weekly" | "monthly" | "quarterly" | "annual"` (required)
  - `seasonal_adjustment` `"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"` (required)
  - `license_tag` `string` (required)
  - `geography` `agent_datasets__realestate__service__GeographyRef` (required)
    - `geo_key` `string` (required)
    - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
    - `code` `string` (required)
    - `name` `string` (required)
    - `state_code` `string | null` (required)
  - `start` `string (date) | null` (required)
  - `end` `string (date) | null` (required)
  - `observations` `array<RESeriesObservation>` (required)
    - `period` `string (date)` (required)
    - `period_type` `"date" | "month" | "quarter" | "year"` (required)
    - `value` `string` (required)
    - `as_of` `string (date-time)` (required)
    - `source_vintage` `string | null` (required)
    - `effective_date` `string (date) | null` (required)
    - `meta` `object | null` (required)
- `meta` `RESeriesMeta` (required) — Series provenance with a courtesy notice for Census-owned data.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
  - `notice` `string | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/re/series/search

Series Search

Search real-estate series by topic and/or exact geography.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| query | query | `string \| null` | no | — | — | Optional title or dataset-key token query |
| geo_key | query | `string \| null` | no | — | — | Optional exact geo_key returned by geography search |
| limit | query | `integer` | no | 10 | min 1, max 50 | Series matches to return |
| cursor | query | `string \| null` | no | — | — | Opaque cursor from pagination.next_cursor |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/re/series/search"
```

### Response

`200` Successful Response — `RESeriesSearchResult`.

- `data` `RESeriesSearchData` (required)
  - `query` `string | null` (required)
  - `geo_key` `string | null` (required)
  - `matches` `array<RESeriesMatch>` (required)
    - `series_key` `string` (required)
    - `dataset_key` `string` (required)
    - `source` `"fhfa" | "hud" | "census" | "noaa" | "fdic_sod" | "abs" | "nyc_acris"` (required)
    - `title` `string` (required)
    - `units` `string` (required)
    - `base_period` `string | null` (required)
    - `currency` `string | null` (required)
    - `frequency` `"daily" | "weekly" | "monthly" | "quarterly" | "annual"` (required)
    - `seasonal_adjustment` `"seasonally_adjusted" | "not_seasonally_adjusted" | "not_applicable"` (required)
    - `license_tag` `string` (required)
    - `geography` `agent_datasets__realestate__service__GeographyRef` (required)
      - `geo_key` `string` (required)
      - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
      - `code` `string` (required)
      - `name` `string` (required)
      - `state_code` `string | null` (required)
    - `coverage_start` `string (date) | null` (required)
    - `coverage_end` `string (date) | null` (required)
- `meta` `RESeriesSearchMeta` (required) — Catalog provenance plus a notice when the current page contains Census data.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
  - `notice` `string | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json