Skip to content
Thesma docs

Get a metro-area demographic profile

Get a complete demographic snapshot for a US Metropolitan Statistical Area (MSA). The example uses New York-Newark-Jersey City, NY-NJ-PA (CBSA 35620) — largest MSA in the US, dense coverage across all 26 metrics.

Problem

Section titled “Problem”

You want the full demographic picture for a metro — all 26 curated metrics in one call, grouped by category, with margin-of-error metadata where available.

curl — all metrics for a metro

Section titled “curl — all metrics for a metro”
Terminal window
curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/census/places/35620" \
  | jq '.data | {fips, name, level, population, area_sq_mi}'

For the full metric payload (all 26, grouped by category):

Terminal window
curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/census/places/35620/metrics" \
  | jq '.data.metrics | keys'

Python SDK

Section titled “Python SDK”
from thesma import ThesmaClient


client = ThesmaClient()


nyc = client.census.places("35620").metrics()


print(f"{nyc.data.name} — {nyc.data.vintage}")
print(f"  population:          {nyc.data.metrics.demographics.total_population.value:,}")
print(f"  median household:    ${nyc.data.metrics.income.median_household_income.value:,}")
print(f"  homeownership:       {nyc.data.metrics.housing.homeownership_rate.value:.1%}")
print(f"  bachelor's or more:  {nyc.data.metrics.education.pct_bachelors_or_higher.value:.1%}")

Expected response shape

Section titled “Expected response shape”
{
  "data": {
    "fips": "35620",
    "name": "New York-Newark-Jersey City, NY-NJ-PA",
    "level": "metro",
    "parent_fips": null,
    "parent_name": "United States",
    "vintage": "2024 (acs5)",
    "metrics": {
      "demographics": {
        "median_age": { "value": 39.4, "unit": "years", "moe": 0.1 },
        "total_population": { "value": 19567410, "unit": "persons", "moe": null },
        "population_density": { "value": 2826.4, "unit": "persons_per_sq_mi", "moe": null }
      },
      "income": {
        "median_household_income": { "value": 94500, "unit": "usd", "moe": 320 },
        "per_capita_income": { "value": 52100, "unit": "usd", "moe": 180 },
        "median_earnings": { "value": 62300, "unit": "usd", "moe": 240 },
        "poverty_rate": { "value": 0.122, "unit": "ratio", "moe": 0.003 },
        "gini_index": { "value": 0.51, "unit": "index", "moe": 0.004 }
      },
      "housing": {
        "median_home_value": { "value": 612000, "unit": "usd", "moe": 3200 },
        "median_rent": { "value": 1785, "unit": "usd", "moe": 18 },
        "homeownership_rate": { "value": 0.519, "unit": "ratio", "moe": 0.003 },
        "vacancy_rate": { "value": 0.075, "unit": "ratio", "moe": 0.002 },
        "housing_units": { "value": 7843210, "unit": "count", "moe": 5400 }
      },
      "education": {
        "pct_high_school_or_higher": { "value": 0.874, "unit": "ratio", "moe": 0.002 },
        "pct_bachelors_or_higher": { "value": 0.412, "unit": "ratio", "moe": 0.003 },
        "pct_graduate_degree": { "value": 0.175, "unit": "ratio", "moe": 0.002 }
      },
      "employment": {
        "labor_force_participation": { "value": 0.642, "unit": "ratio", "moe": 0.002 },
        "unemployment_rate": { "value": 0.044, "unit": "ratio", "moe": 0.001 }
      },
      "population": {
        "pct_under_18": { "value": 0.205, "unit": "ratio", "moe": 0.001 },
        "pct_over_65": { "value": 0.167, "unit": "ratio", "moe": 0.001 }
      },
      "race_ethnicity": {
        "pct_white": { "value": 0.463, "unit": "ratio", "moe": 0.002 },
        "pct_black": { "value": 0.164, "unit": "ratio", "moe": 0.001 },
        "pct_hispanic": { "value": 0.247, "unit": "ratio", "moe": 0.001 },
        "pct_asian": { "value": 0.126, "unit": "ratio", "moe": 0.001 }
      },
      "health_insurance": {
        "pct_uninsured": { "value": 0.056, "unit": "ratio", "moe": 0.002 },
        "pct_private_insurance": { "value": 0.642, "unit": "ratio", "moe": 0.003 }
      }
    }
  }
}

Values drift as ACS publishes new vintages. Field types, categories, and names are stable.

Single-metric time series

Section titled “Single-metric time series”

For a single metric across available vintages (a few years of history):

Terminal window
curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/census/places/35620/metrics/median_household_income" \
  | jq '.data[] | {vintage, value, moe}'

Stable MSA targets

Section titled “Stable MSA targets”
CBSA FIPSMetro
35620New York-Newark-Jersey City, NY-NJ-PA
31080Los Angeles-Long Beach-Anaheim, CA
16980Chicago-Naperville-Elgin, IL-IN-WI
19100Dallas-Fort Worth-Arlington, TX
26420Houston-The Woodlands-Sugar Land, TX
14460Boston-Cambridge-Newton, MA-NH

Top-tier US MSAs with comprehensive ACS coverage. Avoid micropolitan statistical areas — they’re excluded in v1 and return 404 (see Census → Known limitations).

Finding an MSA by name

Section titled “Finding an MSA by name”

Pagination on name-search for metros is alphabetical and can miss large MSAs if their name starts late in the alphabet. If you don’t have the FIPS, use this pattern:

Terminal window
# Recommended — pass the known FIPS directly
curl "https://api.thesma.dev/v1/us/census/places/35620"


# Not recommended for ad-hoc searches — may require paginating past many pages
curl "https://api.thesma.dev/v1/us/census/geographies/metro?query=New+York&per_page=100"

Large-MSA FIPS codes are well-known and stable; bookmark the ones you use.

Gotchas

Section titled “Gotchas”
  • MOE (margin of error) can be null. Not every metric has a published MOE for every geo × vintage. Don’t assume it’s always present.
  • ratio values are between 0 and 1, not percentages. homeownership_rate: 0.519 means 51.9%.
  • Vintage lag. ACS 5-year estimates arrive ~18 months after the survey window closes. 2024 (acs5) covers the 2020–2024 window. For analysis needing the most recent possible data at the expense of statistical stability, check whether ACS 1-year is available for the geography.

See also

Section titled “See also”