compare_estaite_submarkets

Description

Compares 2–10 submarkets side-by-side in a single call. Accepts names (partial match) or numeric ids — no separate search step required. Returns partial results with a warnings array if any name failed to match.

Two response shapes:

• Slice mode — pass property_type AND bedrooms to get a flat metrics block per submarket for that one segment.
• Summary mode (default — omit one or both) — returns a multi-segment segments block per submarket (3 property types × 4 bedrooms).

Inputs

Name	Type	Required	Description
submarkets	array of string | number, length 2–10	yes	Submarket names (partial match supported) or numeric ids.
property_type	enum (apt, sfr, ct)	no	Set together with bedrooms to get slice mode.
bedrooms	integer 1–5	no	Same — set both to get slice mode.
include	object	no	Flags controlling which metric families to return. See below.

include flags

Valid keys and defaults:

Key	Default	Effect
price	true	Median price and YoY/listing block. Currently always present in the metrics output regardless.
listings	true	Listing counts.
trend	true	Adds mom_change to the metrics.
affordability	false	Adds rent_to_income and affordability_index.
dom	false	Adds avg_dom.
market	true	Always emits market_health block.

Note

The MCP server’s input-schema description for include currently lists { trend, dom, affordability, rent_to_income }. That description is misleading — rent_to_income is not a top-level include key; it’s emitted as part of affordability. The keys above are the ones the implementation actually checks.

Response — Slice mode

{
  "attribution": "Data via Estaite Submarket Index",
  "powered_by": "Estaite.com",
  "api_version": "v1",
  "request_id": "f0a4e9c2-7f8e-4d11-9a7e-7a2f1b4c8e91",
  "warnings": ["No match found for: notarealmarket"],
  "as_of": "2026-05-11T19:42:08.115Z",
  "mode": "slice",
  "count": 2,
  "data": [
    {
      "submarket_name": "Buckhead",
      "city": "Atlanta",
      "state": "GA",
      "mode": "slice",
      "parameters": { "property_type": "apt", "bedrooms": 2 },
      "metrics": {
        "median_price": 2348,
        "yoy_change": 5.0,
        "listings": 276,
        "mom_change": 0.4
      },
      "market_health": { "vacancy": 5.5, "saturation": 17.6 }
    },
    {
      "submarket_name": "Roswell / Sandy Springs",
      "city": "Atlanta",
      "state": "GA",
      "mode": "slice",
      "parameters": { "property_type": "apt", "bedrooms": 2 },
      "metrics": {
        "median_price": 1675,
        "yoy_change": -4.3,
        "listings": 686,
        "mom_change": -0.2
      },
      "market_health": { "vacancy": 5.5, "saturation": 10.0 }
    }
  ]
}

Response — Summary mode

{
  "attribution": "Data via Estaite Submarket Index",
  "powered_by": "Estaite.com",
  "api_version": "v1",
  "request_id": "f0a4e9c2-7f8e-4d11-9a7e-7a2f1b4c8e91",
  "as_of": "2026-05-11T19:42:08.115Z",
  "mode": "summary",
  "count": 2,
  "data": [
    {
      "submarket_name": "Buckhead",
      "city": "Atlanta",
      "state": "GA",
      "mode": "summary",
      "segments": {
        "apartments": {
          "br1": { "median_price": 1800, "yoy_change": 4.1, "listings": 130 },
          "br2": { "median_price": 2348, "yoy_change": 5.0, "listings": 276 },
          "br3": { "median_price": 3100, "yoy_change": 3.6, "listings": 80 },
          "br4": { "median_price": 4200, "yoy_change": 2.4, "listings": 24 }
        },
        "single_family":  { "br1": {  }, "br2": {  }, "br3": {  }, "br4": {  } },
        "condo_townhome": { "br1": {  }, "br2": {  }, "br3": {  }, "br4": {  } }
      },
      "market_health": { "vacancy": 5.5, "saturation": 17.6 }
    }
  ]
}

Fields

Top level

Field	Type	Description
attribution	string	Required attribution. Echo verbatim.
powered_by	string	Always "Estaite.com".
api_version	string	Always "v1".
request_id	string	Per-request UUID.
warnings	string[]	Present only when one or more submarket names failed to match. Each entry is a human-readable note.
as_of	string	ISO timestamp of when the response was generated.
mode	string	"slice" or "summary".
count	number	Number of matched submarkets returned (≤ length of submarkets input).
data[]	array	Per-submarket records.

data[] — Slice mode

Path	Type	Description
submarket_name, city, state	string	Submarket identity.
mode	string	Always "slice".
parameters	object	Echoes the property_type and bedrooms used.
metrics.median_price	number	Median monthly rent for the slice, USD.
metrics.yoy_change	number	Year-over-year change in whole-percent.
metrics.listings	number	Listing count.
metrics.mom_change	number	Month-over-month change. Present when include.trend is true (default).
metrics.rent_to_income	number	Rent-to-income in whole-percent. Present when include.affordability is true.
metrics.affordability_index	number	Affordability index. Present when include.affordability is true.
metrics.avg_dom	number	Average days on market. Present when include.dom is true.
market_health.vacancy	number	Vacancy in whole-percent.
market_health.saturation	number	Saturation in whole-percent.

data[] — Summary mode

Path	Type	Description
submarket_name, city, state	string	Submarket identity.
mode	string	Always "summary".
segments[label][br_key].median_price	number	Median monthly rent, USD.
segments[label][br_key].yoy_change	number	Year-over-year change in whole-percent.
segments[label][br_key].listings	number	Listing count.
market_health	object	Same as slice mode.

Errors

Code	HTTP	Meaning
MINIMUM_TWO_SUBMARKETS_REQUIRED	400	Fewer than 2 entries supplied.
TOO_MANY_SUBMARKETS	400	More than 10 entries supplied.
INVALID_PROPERTY_TYPE	400	Slice property_type invalid.
INVALID_BEDROOM_COUNT	400	Slice bedrooms outside 1–5. The error response includes valid_values: [1,2,3,4,5].
INSUFFICIENT_MATCHES	404	No supplied submarket matched. The error response includes a warnings array describing which names failed.

Notes

• Partial matches resolve to the most specific submarket. Passing "Sandy Springs" may return "Roswell / Sandy Springs" if that’s the canonical record. Pass numeric ids when precision matters.
• warnings is at the top level, not on the individual record. Failed matches don’t appear in data[] at all — only as a warning string.
• All percent values are whole-percent. A yoy_change of 5.0 means +5.0%, not 500%.
• Slice mode is denser; summary mode is wider. Pick slice when you know which segment matters; summary when you want the whole 12-cell grid (apt/sfr/ct × 1–4 BR) at once.