get_estaite_affordability

Description

Returns the rent-to-income ratio, affordability index, and index-change windows for a submarket, plus a derived affordability_label (“Affordable”, “Cost Burdened”, etc). Defaults to apt, 2 BR.

The response shape depends on whether you pass property_type and bedrooms:

Slice mode (both set) → flat fields for the one segment, including all four window changes (3m/6m/9m/12m).
Summary mode (either omitted) → no top-level slice fields; instead a segments block with one entry per property_type/bedrooms cell. Each cell exposes only the 3m and 6m change windows.

Inputs

Name	Type	Required	Description
`id`	integer	yes	Submarket id from `search_estaite_submarkets`.
`property_type`	enum (`apt`, `sfr`, `ct`)	no	If omitted (or `bedrooms` is omitted), the tool returns summary mode.
`bedrooms`	integer 1–5	no	Same — omit either to get summary mode.

Response — Slice mode

{
  "attribution": "Data via Estaite Submarket Index",
  "powered_by": "Estaite.com",
  "api_version": "v1",
  "request_id": "f0a4e9c2-7f8e-4d11-9a7e-7a2f1b4c8e91",
  "id": 1,
  "submarket_name": "Carmel Valley",
  "city": "San Diego",
  "state": "CA",
  "as_of": 202603,
  "property_type": "apt",
  "bedrooms": 2,
  "affordability_label": "Affordable",
  "median_household_income": 145800,
  "median_rent": 3659.0,
  "rent_to_income_pct": 23.4,
  "affordability_index": 88.45,
  "index_change_3m": 0.62,
  "index_change_6m": 1.10,
  "index_change_9m": 1.85,
  "index_change_12m": 2.40
}

Response — Summary mode

{
  "attribution": "Data via Estaite Submarket Index",
  "powered_by": "Estaite.com",
  "api_version": "v1",
  "request_id": "f0a4e9c2-7f8e-4d11-9a7e-7a2f1b4c8e91",
  "id": 1,
  "submarket_name": "Carmel Valley",
  "city": "San Diego",
  "state": "CA",
  "as_of": 202603,
  "median_household_income": 145800,
  "segments": {
    "apartments": {
      "br1": { "median_rent": 2700, "rent_to_income_pct": 22.2, "affordability_index": 90.1, "index_change_3m": 0.5, "index_change_6m": 0.9, "affordability_label": "Affordable" },
      "br2": { "median_rent": 3659, "rent_to_income_pct": 23.4, "affordability_index": 88.45, "index_change_3m": 0.62, "index_change_6m": 1.10, "affordability_label": "Affordable" },
      "br3": { "median_rent": 4200, "rent_to_income_pct": 28.7, "affordability_index": 81.4, "index_change_3m": 0.4, "index_change_6m": 0.7, "affordability_label": "Moderately Affordable" },
      "br4": { "median_rent": 5100, "rent_to_income_pct": 34.9, "affordability_index": 71.6, "index_change_3m": 0.3, "index_change_6m": 0.5, "affordability_label": "Cost Burdened" }
    },
    "single_family":  { "br1": { "...": null }, "br2": {  }, "br3": {  }, "br4": {  } },
    "condo_townhome": { "br1": {  }, "br2": {  }, "br3": {  }, "br4": {  } }
  }
}

Fields

Slice mode

Field	Type	Description
`affordability_label`	string	Derived from `rent_to_income_pct`. See table below.
`median_household_income`	number	Median household income for the submarket, USD.
`median_rent`	number	Median monthly rent for the slice, USD.
`rent_to_income_pct`	number	Rent-to-income ratio in whole-percent (e.g. `23.4` means 23.4%).
`affordability_index`	number	Affordability index. Higher = more affordable. Roughly `100 - rti%` scaled with some smoothing.
`index_change_3m`, `_6m`, `_9m`, `_12m`	number	Signed change in the affordability index over the corresponding window.

Summary mode

Path	Type	Description
`median_household_income`	number	Same field appears at top level.
`segments[label][br_key]`	object	One per property_type × bedrooms cell.
`segments[label][br_key].median_rent`	number	Slice median, USD.
`segments[label][br_key].rent_to_income_pct`	number	Slice rent-to-income in whole-percent.
`segments[label][br_key].affordability_index`	number	Same as slice mode.
`segments[label][br_key].index_change_3m`, `_6m`	number	Only 3m and 6m windows are exposed in summary mode (not 9m or 12m).
`segments[label][br_key].affordability_label`	string	Derived per cell.

`affordability_label` derivation

Label	Rule (rent_to_income_pct in whole-percent)
`Affordable`	`< 25`
`Moderately Affordable`	`25` to `< 30`
`Cost Burdened`	`30` to `< 35`
`Severely Cost Burdened`	`>= 35`
`Unknown`	`rent_to_income_pct` is `null`

Errors

Code	HTTP	Meaning
`MISSING_OR_INVALID_SUBMARKET_ID`	400	`id` missing or non-numeric.
`INVALID_PROPERTY_TYPE`	400	`property_type` is not one of `apt`, `sfr`, `ct`.
`INVALID_BEDROOM_COUNT`	400	`bedrooms` outside 1–5.
`SUBMARKET_NOT_FOUND`	404	No data exists for the requested id.

Notes

The rent-to-income ratio is whole-percent. 23.4 means a tenant on the median household income is paying 23.4% of pre-tax income on rent — not 2,340%.
The label thresholds match the federal definition. “Cost Burdened” is HUD’s threshold at 30%+, “Severely Cost Burdened” at 50%+ — but Estaite uses 35% as the severe threshold for tighter alerting. Adjust the rules in affordability_label on your side if your product needs HUD-exact buckets.
Summary mode shows fewer change windows. If you need 9m or 12m index changes, call slice mode for the specific segment.