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.

What	URL
Hosted API	https://geohealth-api-production.up.railway.app
Swagger UI	/docs
ReDoc	/redoc
OpenAPI JSON	/openapi.json
Health check	/health
Agent overview	/llms.txt
Interactive map	GeoHealth SDOH Explorer
Documentation	russellstover1983.github.io/geohealth-api

# 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.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗