GeoHealth Context API
Live API · Interactive Map · Docs Site · PyPI · Swagger UI
Census-tract-level geographic health intelligence API. Given a street address or lat/lng coordinates, returns demographics, CDC/ATSDR Social Vulnerability Index (SVI) themes, CDC PLACES health outcome measures, EPA EJScreen environmental indicators, multi-year trend data, and an optional AI-generated narrative for the surrounding census tract.
Coverage: All 50 US states + DC — ~84,000 census tracts.
Try It Without Installing
The API is live and hosted on Railway. The interactive map is hosted on Vercel.
# Anonymous health check (no key required)
curl https://geohealth-api-production.up.railway.app/health
# Hit a data endpoint — auth-protected endpoints require X-API-Key
curl -H "X-API-Key: $GEOHEALTH_API_KEY" \
"https://geohealth-api-production.up.railway.app/v1/context?address=1234+Main+St,+Minneapolis,+MN"
Features
- Address and coordinate geocoding (Census Bureau + Nominatim fallback)
- Census tract resolution via PostGIS spatial queries or FIPS-code lookup
- ACS demographics: population, income, poverty, insurance, unemployment, age
- CDC/ATSDR SVI theme percentile rankings (4 themes + composite)
- CDC PLACES health outcome measures (14 measures, crude prevalence)
- EPA EJScreen environmental indicators (PM2.5, ozone, diesel PM, lead paint, Superfund proximity, etc.)
- Multi-year ACS trend data (2018–2022) with absolute and percent change
- Demographic comparison with county/state/national percentile rankings
- Composite SDOH index
- AI-generated narrative summaries (Anthropic Claude)
- Batch address lookups, spatial radius search, tract comparison
- GeoJSON endpoints for map rendering (tracts and NPI providers)
- Webhook subscriptions with HMAC-signed delivery and exponential-backoff retry
- Per-key sliding-window rate limiting with standard headers
- SHA-256 API key hashing
Run Your Own Instance
If you'd rather run it yourself instead of using the hosted API:
1. Clone and start services
git clone https://github.com/RussellStover1983/geohealth-api.git
cd geohealth-api
docker compose up --build -d
This launches PostgreSQL/PostGIS and the API on http://localhost:8000.
2. Load census tract data
# Single state (fast, good for development)
pip install -e ".[etl]"
python -m geohealth.etl.load_all --state 27
# All states (resumable)
python -m geohealth.etl.load_all --state all --resume
3. Verify
curl http://localhost:8000/health
# {"status":"ok","database":"connected","detail":null}
Local Swagger UI / ReDoc / OpenAPI JSON live at /docs, /redoc, and /openapi.json on whatever host you're running. For the hosted equivalents, see the table at the top of this README.
Authentication
Most endpoints require an API key via the X-API-Key header.
# Against the hosted API
curl -H "X-API-Key: your-key-here" \
"https://geohealth-api-production.up.railway.app/v1/context?address=..."
# Against a local instance
curl -H "X-API-Key: your-key-here" "http://localhost:8000/v1/context?address=..."
Configuration:
| Variable | Description |
|---|
AUTH_ENABLED | Set to true to enforce key validation (default: false) |
API_KEYS | Comma-separated list of valid keys |
Keys can be provided as plaintext or as pre-hashed SHA-256 hex strings. The API always hashes keys with SHA-256 before comparison — plaintext keys are never stored or logged.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
