# GeoHealth Context API

> Census-tract-level geographic health intelligence API for the United States.
> Given a street address or lat/lng coordinates, returns demographics,
> CDC Social Vulnerability Index (SVI) themes, CDC PLACES health outcome
> measures, and an optional AI-generated clinical narrative for the
> surrounding census tract.

## Quick Start

- Base URL: `https://geohealth-api-production.up.railway.app`
- Auth: `X-API-Key` header required on `/v1/*` endpoints
- Rate limit: 60 requests/minute per key
- OpenAPI spec: [/openapi.json](/openapi.json)

## Endpoints

- [GET /v1/context](/docs#/context): Primary lookup — address or lat/lng to tract demographics, SVI, PLACES, and optional AI narrative
- [POST /v1/batch](/docs#/batch): Multi-address lookup (up to 50 concurrent)
- [GET /v1/nearby](/docs#/nearby): Find census tracts within N miles of a point
- [GET /v1/compare](/docs#/compare): Compare two tracts or tract vs county/state/national averages
- [GET /v1/trends](/docs#/trends): Historical trend data across ACS years with computed changes
- [GET /v1/demographics/compare](/docs#/demographics): Percentile rankings at county/state/national level
- [GET /v1/dictionary](/docs#/dictionary): Field definitions with clinical interpretation guidance
- [GET /v1/stats](/docs#/stats): Data coverage by state
- [POST /v1/webhooks](/docs#/webhooks): Subscribe to data update notifications

## Key Data Fields

- **Demographics (ACS)**: total_population, median_household_income, poverty_rate, uninsured_rate, unemployment_rate, median_age
- **Vulnerability (SVI)**: rpl_theme1 (socioeconomic), rpl_theme2 (household/disability), rpl_theme3 (minority/language), rpl_theme4 (housing/transportation), rpl_themes (overall) — all as 0-1 percentiles
- **Health Outcomes (PLACES)**: diabetes, obesity, mhlth (mental health), phlth (physical health), bphigh (high blood pressure), csmoking (smoking), casthma (asthma), chd (coronary heart disease), lpa (physical inactivity), binge (binge drinking), sleep (short sleep), checkup, dental, access2 (no insurance) — all as crude prevalence %
- **Environmental (EPA EJScreen)**: pm25, ozone, diesel_pm, air_toxics_cancer_risk, respiratory_hazard_index, traffic_proximity, lead_paint_pct, superfund_proximity, rmp_proximity, hazardous_waste_proximity, wastewater_discharge
- **Composite**: sdoh_index (0-1 scale, higher = more vulnerable)

## MCP Server (for AI Agents)

```bash
pip install geohealth-api[mcp]
GEOHEALTH_API_KEY=your-key python -m geohealth.mcp
```

## Python SDK

```python
from geohealth.sdk import AsyncGeoHealthClient

async with AsyncGeoHealthClient(base_url, api_key="your-key") as client:
    result = await client.context(address="1234 Main St, Minneapolis, MN 55401")
    print(result.tract.poverty_rate, result.tract.sdoh_index)
```

## More

- [Full documentation with clinical context](/llms-full.txt)
- [Interactive API docs (Swagger)](/docs)
- [OpenAPI JSON schema](/openapi.json)