TerraCore
Location Intelligence API

Introduction

TerraCore resolves any supported US location — coordinate, address, ZIP code, or GEOID — to census block group resolution and returns structured, analysis-ready neighborhood intelligence.

Responses combine demographic context, economic indicators, composite percentile-ranked indices, and location intelligence metrics such as accessibility and amenity proximity — delivered in a consistent, flattened JSON format.

Applications can request only the field groups they need, enabling high-resolution neighborhood context for use cases including site selection, market analysis, logistics planning, risk modeling, real estate evaluation, and location-based segmentation.

All endpoints accept a fields parameter to control which field groups are returned. Field groups span core metrics (population, income, housing, employment, education), composite indices, and TerraCore Location Intelligence Metrics such as walkability, retail density, grocery access, transit access, recreation, and healthcare proximity.

Key Capabilities

Authentication

All requests require an API key passed in the X-API-Key header. API keys are available through your Airelit account dashboard or via RapidAPI.

X-API-Key: YOUR_API_KEY
Content-Type: application/json

Base URL & Format

All TerraCore endpoints use POST with a JSON request body.

https://api.airelit.com/v1/terracore

Code Examples

Ready-to-run TerraCore API examples are available on GitHub. The repository includes complete request examples for:

• Node.js
• Python
• curl

Each example demonstrates authenticated POST requests for all TerraCore endpoints, including address, coordinates, ZIP code, and GEOID lookups.

curl -X POST https://api.airelit.com/v1/terracore/address \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"10700 Escondido Canyon Rd, Agua Dulce, CA 91390", "fields": ["summary", "income"]}'

The GitHub repository includes runnable scripts for each endpoint and language.

Field Groups

The fields parameter accepts an array of field group names. Only the requested groups are returned, keeping responses efficient and predictable. If omitted, only the summary group is returned.

Field groups represent logical categories of related metrics. The exact fields returned may differ depending on the spatial level queried. Block Group endpoints return detailed census variables, while ZIP code endpoints return aggregated versions of those metrics along with additional ZIP-exclusive environment and amenity fields.

See the Field Reference section for the complete list of fields returned for each group and endpoint type.

Field groups are organized into four categories: Core Metrics, Composite Indices, Location Intelligence Metrics, and ZIP-Exclusive Fields.

{
  "lat": 32.7767,
  "lon": -96.7970,
  "fields": ["summary", "income", "indices", "walkability"]
}

Pass ["all"] to request every field group permitted by your subscription tier.

By Coordinates

Enriches a latitude/longitude by resolving the point to its containing census block group and returning structured demographic and Location Intelligence data.

{
  "lat": 32.7767,
  "lon": -96.7970,
  "fields": ["summary", "income"]
}

curl -X POST https://api.airelit.com/v1/terracore/coordinates \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat": 32.7767, "lon": -96.7970, "fields": ["summary", "income"]}'

{
  "meta": {
    "geoid":           "481130201001",
    "state_abbr":      "TX",
    "state_name":      "Texas",
    "county_name":     "Dallas County",
    "dataset_version": "2026.03",
    "fields_returned": ["summary", "income"],
    "query_type":      "coordinates"
  },
  "data": {
    "total_population":           3842,
    "population_density":         4210.55,
    "median_age":                  34.2,
    "land_area_sq_miles":          0.9124,
    "latitude":                    32.7769,
    "longitude":                   -96.7965,
    "median_household_income":     68400,
    "per_capita_income":           31200,
    "aggregate_household_income":  82540000,
    "pct_below_poverty":           9.4,
    "pct_income_under_25k":        18.2,
    "pct_income_25k_to_50k":       24.1,
    "pct_income_50k_to_100k":      31.8,
    "pct_income_over_100k":        25.9
    // ... additional income bracket fields
  }
}

By ZIP Code

Returns ZIP-level demographic and Location Intelligence metrics aggregated across intersecting census block groups using population-weighted aggregation. ZIP code responses also include ZIP-exclusive fields — environment scores, raw amenity counts, per-capita ratios, and composite indices — not available at the Block Group level.

{
  "zipcode": "75201",
  "fields": ["summary", "housing", "income"]
}

curl -X POST https://api.airelit.com/v1/terracore/zipcode \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zipcode": "75201", "fields": ["summary", "housing", "income"]}'

{
  "meta": {
    "geoid":                    null,
    "zipcode":                   "75201",
    "state_abbr":                "TX",
    "state_name":                "Texas",
    "county_name":               null,
    "dataset_version":           "2026.03",
    "fields_returned":           ["summary", "housing", "income"],
    "query_type":                "zipcode",
    "contributing_block_groups": 14
  },
  "data": {
    "total_population":    12540,
    "population_density":  8840.20,
    "median_age":          31.8,
    "median_home_value":   385000,
    "median_gross_rent":   1640,
    "affordability_index": 0.72,
    "pct_owner_occupied":  28.4,
    "pct_renter_occupied": 71.6,
    "vacancy_rate":        7.2,
    "median_household_income": 72800,
    "per_capita_income":   48100,
    "pct_below_poverty":   11.3
  }
}

By GEOID

Returns demographic and Location Intelligence metrics for a specific census block group using its 12-digit GEOID.

// 12-digit Census Block Group GEOID breakdown
"481130201001"
 ^^   State FIPS  (48 = Texas)
   ^^^  County FIPS (113 = Dallas County)
      ^^^^^^ Census Tract (020100)
            ^ Block Group (1)

{
  "geoid": "481130201001",
  "fields": ["summary", "race", "education"]
}

curl -X POST https://api.airelit.com/v1/terracore/geoid \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"geoid": "481130201001", "fields": ["summary", "race", "education"]}'

{
  "meta": {
    "geoid":           "481130201001",
    "state_abbr":      "TX",
    "state_name":      "Texas",
    "county_name":     "Dallas County",
    "dataset_version": "2026.03",
    "fields_returned": ["summary", "race", "education"],
    "query_type":      "geoid"
  },
  "data": {
    "total_population":         3842,
    "population_density":       4210.55,
    "median_age":               34.2,
    "land_area_sq_miles":       0.9124,
    "pct_white":                38.4,
    "pct_hispanic":             31.2,
    "pct_black":                18.9,
    "pct_asian":                7.8,
    "diversity_index":          0.7241,
    "pct_bachelors_or_higher":  52.3,
    "education_index":          68.4,
    "pct_high_school_or_higher": 84.6
  }
}

By Address

Accepts a free-form US address string, resolves it to coordinates, and returns block group–level demographic and Location Intelligence data.

{
  "address": "1600 Pennsylvania Avenue NW, Washington, DC",
  "fields": ["summary", "income", "housing"]
}

curl -X POST https://api.airelit.com/v1/terracore/address \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "1600 Pennsylvania Avenue NW, Washington, DC", "fields": ["summary", "income"]}'

{
  "meta": {
    "geoid":             "110010062001",
    "state_abbr":        "DC",
    "state_name":        "District of Columbia",
    "county_name":       "District of Columbia",
    "dataset_version":   "2026.03",
    "fields_returned":   ["summary", "income"],
    "query_type":        "address",
    "resolved_address":  "1600 Pennsylvania Avenue NW, Washington, DC",
    "resolved_latitude":  38.8977,
    "resolved_longitude": -77.0365
  },
  "data": {
    "total_population":        1284,
    "population_density":      9820.40,
    "median_age":              38.1,
    "median_household_income": 118400,
    "per_capita_income":       84600,
    "pct_below_poverty":       4.2
  }
}

Response Format

All successful responses use a consistent two-key envelope. The meta object contains resolution context and geographic identifiers. The data object contains the requested enrichment fields as a flat, analysis-ready structure.

Success Envelope

Error Envelope

All errors use a consistent format regardless of endpoint:

{
  "error": true,
  "code": "NOT_FOUND",
  "message": "No census block group found for these coordinates"
}

Field Reference

Complete listing of every field returned per group. All percentage fields are expressed as values from 0–100. Monetary values are in US dollars (not adjusted for inflation).

All fields listed below appear inside the data object of the response. Geographic identifiers such as geoid, state_fips, state_name, state_abbr, and county identifiers are returned in the meta object.

Core Metrics

summary Free

demographics Basic

race Basic

income Basic

education Basic

employment Basic

housing Basic

jurisdictions Basic

Political and civic jurisdiction identifiers derived from spatial overlay of census block group centroids against authoritative boundary datasets.

commute Pro

internet Pro

insurance Pro

raw_counts Pro Block-group lookups only

Raw integer counts for the expanded age buckets. Useful when you need the underlying population counts rather than the percentages returned in demographics. Not available for ZIP code queries.

Composite Indices

indices Pro

TerraCore Composite Indices translate multi-variable demographic and economic signals into percentile-ranked, decision-ready scores. Each index combines independently percentile-normalized components to preserve scale consistency across heterogeneous inputs (income, rates, densities, etc.).

Location Intelligence Metrics

Location Intelligence Metrics describe access to everyday amenities — groceries, transit, parks, healthcare, schools, walkable retail, and community resources. Composite scores are normalized within peer zone classes (urban / suburban / rural) so comparisons are meaningful across geography types. Zone class is determined algorithmically based on population density and built-environment structure — not ZIP code heuristics — ensuring like-for-like benchmarking across geographies.

The enrichment_meta group provides data quality indicators for any Location Intelligence Metrics response, including a data_confidence field (high, medium, or low). Low confidence suggests sparse coverage for the area; scores may be underestimated.

walkability Pro

Pedestrian-range access to daily-use amenities measured within 0.25–1 mile radial buffers.

grocery_access Pro

Proximity and availability of grocery stores and supermarkets.

healthcare_access Pro

Access to clinics, urgent care facilities, and hospitals.

transit_access Pro

Walkable bus stop access plus proximity to rail and tram stations.

retail Pro

Commercial retail density and walkable shop access.

school_access Pro

Proximity to K-12 schools and higher education institutions.

recreation Pro

Access to parks, nature areas, and nearby entertainment venues.

community_access Pro

Proximity and density of community gathering places and places of worship.

enrichment_meta Pro

Data quality and coverage indicators for Location Intelligence Metrics.

ZIP-Exclusive Fields

The following fields are only returned for ZIP code queries (/v1/terracore/zipcode). They do not exist at the Block Group level. Block Group documentation remains unchanged.

ZIP-Exclusive · Environment Scores

zip_environment_scores Pro

Population-weighted averages of Block Group-level environment scores, aggregated to the ZIP. Weight = estimated population from area intersection. BGs with NULL scores are excluded from both numerator and denominator.

ZIP-Exclusive · Nearest POI Distance Averages

zip_poi_distances Pro

Population-weighted averages of BG-level nearest-POI distances. NULLs excluded from both numerator and denominator. Units: miles (same as BG source fields).

ZIP-Exclusive · Raw Amenity Counts

zip_amenity_counts Pro

Sourced directly from env.zip_environment — OSM features aggregated within the ZIP boundary. Not rolled up from Block Groups. NULL when no environment data exists for a ZIP.

ZIP-Exclusive · Per-Capita Amenity Ratios

zip_amenity_ratios Pro

Derived from ZIP amenity counts divided by ZIP total population. NULL when population is 0 or env data is absent.

ZIP-Exclusive · Composite Indices

zip_indices Pro

Composite indices derived from ZIP-level metrics and normalized using national percentile ranking across all ~33,000 US ZIP codes. Scores range from 0–100 where higher values indicate stronger performance relative to other ZIP codes nationally.

Error Codes

All errors return a JSON object with error: true, a machine-readable code, and a human-readable message.

{
  "error":   true,
  "code":    "TIER_REQUIRED",
  "message": "Requested field group(s) require a higher tier: commute, internet"
}

Data Sources & Coverage

TerraCore is powered by the US Census Bureau American Community Survey (ACS) 5-Year Estimates, currently using the 2024 ACS 5-Year vintage (2020–2024 survey period). ACS 5-Year data provides the most statistically reliable demographic estimates available for small geographies such as census block groups.

TerraCore extends census demographic data with spatial enrichment layers including amenity density, accessibility metrics, and derived neighborhood intelligence indices. These enrichment datasets are processed through AireLit's spatial analysis pipeline prior to API delivery to ensure consistent response latency and reproducible scoring across the United States.

Primary Demographic Data

The American Community Survey (ACS) is an ongoing statistical survey conducted by the US Census Bureau. The 5-Year dataset pools survey responses collected over five years, enabling reliable demographic estimates for small geographic areas such as census block groups.

Census block groups typically contain between 600 and 3,000 residents and are designed to represent relatively homogeneous neighborhoods with respect to demographic, economic, and housing characteristics. TerraCore uses block groups as its foundational geographic unit for demographic enrichment.

Spatial & Infrastructure Data

TerraCore Location Intelligence Metrics are derived from normalized geospatial infrastructure datasets including amenity locations, transportation infrastructure, healthcare facilities, parks, schools, and retail features. These datasets are spatially indexed and aggregated using AireLit's enrichment engine to produce neighborhood-level accessibility metrics and percentile-ranked scores.