get_estaite_cbsa_trends

Description

Returns up to 12 months of CBSA-level rent and vacancy trends — per-month averages across every submarket in the metro, plus a trend_summary showing the dollar change in average rent from the earliest to latest month in the window. Use this for time-series chart data and “how is this metro trending over the past year” questions.

Inputs

Name	Type	Required	Description
`cbsa`	string	yes	CBSA code (e.g. `"19100"`) or partial name (e.g. `"Dallas"`).
`history_months`	integer 1–12	no	Number of months of history to return. Default `12`, hard cap `12`.

Response

{
  "attribution": "Data via Estaite Submarket Index",
  "powered_by": "Estaite.com",
  "source_domains": [],
  "cbsa": "Dallas-Fort Worth-Arlington, TX",
  "state": "TX",
  "history_months": 12,
  "period": "202504 → 202603",
  "trend_summary": {
    "latest_avg_vacancy": 7.85,
    "latest_avg_saturation": 1.92,
    "rent_change_over_period": {
      "apartments":     { "br1": 32.4, "br2": 48.1, "br3": 61.75, "br4": 78.2 },
      "single_family":  { "br1": 24.1, "br2": 39.55, "br3": 52.8, "br4": 64.9 },
      "condo_townhome": { "br1": 18.3, "br2": 28.45, "br3": 35.6, "br4": 42.2 }
    }
  },
  "history": [
    {
      "yearmonth": 202603,
      "submarket_count": 47,
      "avg_vacancy_rate": 7.85,
      "avg_saturation": 1.92,
      "segments": {
        "apartments": {
          "br1": { "avg_rent": 1280, "avg_yoy": 3.4 },
          "br2": { "avg_rent": 1610, "avg_yoy": 3.85, "avg_mom": 0.3 },
          "br3": { "avg_rent": 2050, "avg_yoy": 3.6 },
          "br4": { "avg_rent": 2580, "avg_yoy": 2.8 }
        },
        "single_family": {
          "br1": { "avg_rent": null, "avg_yoy": null },
          "br2": { "avg_rent": 1820, "avg_yoy": 4.5 },
          "br3": { "avg_rent": 2380, "avg_yoy": 4.1 },
          "br4": { "avg_rent": 2950, "avg_yoy": 3.4 }
        },
        "condo_townhome": {
          "br1": { "avg_rent": 1450, "avg_yoy": 3.9 },
          "br2": { "avg_rent": 1740, "avg_yoy": 3.5 },
          "br3": { "avg_rent": null, "avg_yoy": null },
          "br4": { "avg_rent": null, "avg_yoy": null }
        }
      }
    }
  ]
}

Fields

Top level

Field	Type	Description
`attribution`	string	Required attribution. Echo verbatim.
`powered_by`	string	Always `"Estaite.com"`.
`source_domains`	string[]	Contributing data-provider domains for submarkets in this metro.
`cbsa`	string	Full CBSA name.
`state`	string	Primary state code for the CBSA.
`history_months`	number	Actual number of monthly buckets returned. May be lower than requested if the metro has thinner history.
`period`	string	`"<earliest_yearmonth> → <latest_yearmonth>"`.

`trend_summary`

Path	Type	Description
`latest_avg_vacancy`	number	Mean vacancy in the most recent month, in whole-percent.
`latest_avg_saturation`	number	Mean saturation in the most recent month, in whole-percent.
`rent_change_over_period[label][br_key]`	number	Dollar delta in average rent from earliest → latest month for each segment cell. Not a percent. Negative when rent dropped over the period.

`history[]`

One entry per month, oldest first (so the last entry corresponds to trend_summary.latest_*).

Path	Type	Description
`yearmonth`	number	Format `YYYYMM`.
`submarket_count`	number	Number of submarkets contributing data for that month.
`avg_vacancy_rate`	number	Mean vacancy in whole-percent.
`avg_saturation`	number	Mean saturation in whole-percent.
`segments[label][br_key].avg_rent`	number	Mean median rent for the cell, USD. `null` when no submarkets in the metro have data for that cell that month.
`segments[label][br_key].avg_yoy`	number	Mean YoY change in whole-percent.
`segments.apartments.br2.avg_mom`	number	Mean MoM change in whole-percent. Only emitted on the `apt br2` cell — every other cell lacks this field. (Quirk of the underlying query — apt 2 BR is treated as the reference segment.)

Errors

Code	HTTP	Meaning
`MISSING_CBSA`	400	`cbsa` was not provided.
`CBSA_NOT_FOUND`	404	No CBSA matched the input, or no months satisfy the filter (need at least one row with `apt_2bd_median_price IS NOT NULL`).

Notes

avg_mom only appears on apt br2. The implementation only computes month-over-month for the reference segment. If you need MoM for other cells, use get_estaite_rent_trends per-submarket and aggregate.
History is oldest first. Reverse it if you want a “most recent on top” table.
rent_change_over_period is in USD, not percent. Don’t format it as "+3.2%" — format as "+$48".
Mixed scales in one response. avg_vacancy_rate and avg_yoy are whole-percent. rent_change_over_period.*.br* is USD. avg_rent and avg_saturation are also raw numbers (USD and percent respectively). Don’t apply a single formatter to everything.
Null cells are common. Smaller metros have many empty (null) cells. Skip them or show ”—” rather than crashing on missing data.