# ToolMint Census Geocode

> US address or lat/lon → Census FIPS geographies as clean JSON. No Census API key.

- Status: Coming soon
- Price: $0.005 / call (x402 exact, USDC on Base eip155:8453, payTo 0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5)
- Planned URL: https://toolmint-census-geocode.toolmint.workers.dev
- OpenAPI: https://toolmint.toolmint.workers.dev/tools/census-geocode-json/openapi.json

## Routes

- `GET /geocode` $0.005: US address → matched address, lat/lon, state/county FIPS, tract, block group, block, congressional + state legislative districts, place (US Census Geocoder). Example: address=505 Travis St, Shreveport, LA 71101
- `GET /reverse` $0.005: US lat/lon → state/county FIPS, tract, block group, block, congressional + state legislative districts, place (US Census Geocoder). Example: lat=32.5136&lon=-93.7506

## What question it answers

- "What county, tract and block group is this US street address in?" (`/geocode`)
- "What Census geographies contain this latitude and longitude?" (`/reverse`)

County FIPS is what HUD rent and income-limit lookups key on. Lat/lon is what flood-zone and weather-alert lookups key on.

## When to use it

- You have a one-line street address and need coordinates and FIPS codes.
- You have a point and need the county, tract, block group or district.

## When not to

- Not a delivery-grade or rooftop geocoder. It returns what the Census Geocoder matches against its address ranges. `zip` is the USPS ZIP from the matched range, not a ZCTA.
- Needs a house number and street. Place names, intersections and bare ZIP codes will not work.
- No demographics. This returns geography IDs only.
- Coverage is US states, DC, Puerto Rico and island areas. A point outside returns 404.

## Example

```bash
curl -i "https://toolmint-census-geocode.toolmint.workers.dev/geocode?address=505%20Travis%20St,%20Shreveport,%20LA%2071101"
```
Unpaid, this returns HTTP 402. Trimmed 200 response shape.
```json
{
  "tool": "census-geocode-json",
  "version": "0.1.0",
  "query": { "address": "505 Travis St, Shreveport, LA 71101" },
  "source": { "name": "US Census Bureau Geocoder", "benchmark": "Public_AR_Current",
              "vintage": "Current_Current", "url": "https://geocoding.geo.census.gov/geocoder/geographies/onelineaddress?..." },
  "fetchedAt": "2026-10-31T...Z",
  "cached": false,
  "notice": "This product uses the Census Bureau Geocoder and Data API but is not endorsed or certified by the Census Bureau.",
  "match": "single",
  "matchedAddress": "505 TRAVIS ST, SHREVEPORT, LA, 71101",
  "location": { "lat": 32.51, "lon": -93.75 },
  "zip": "71101",
  "zipNote": "USPS ZIP from the matched TIGER address range (not a ZCTA).",
  "geographies": {
    "state": { "fips": "22", "abbr": "LA", "name": "Louisiana" },
    "county": { "fips": "22017", "name": "Caddo Parish" },
    "tract": { "geoid": "22017025300", "code": "025300", "name": "Census Tract 253" },
    "blockGroup": { "geoid": "220170253003" },
    "congressionalDistrict": { "geoid": "2204", "name": "Congressional District 4", "layer": "..." }
  }
}
```
The full `geographies` object also has `countySubdivision`, `place`, `block`, `stateLegislativeUpper`, `stateLegislativeLower`, `urbanArea` and `combinedStatisticalArea` (each `null` when absent).

Reverse: `GET /reverse?lat=32.5136&lon=-93.7506` returns the same envelope with `match: "point"` and the same `geographies`.

## Data source and licence

US Census Bureau Geocoder (`geocoding.geo.census.gov`), benchmark `Public_AR_Current`, vintage `Current_Current`. US federal data is generally public domain; check the source's terms for your own use. No key is used.

## Freshness and limits

- Answers are cached 24 hours on a warm Worker instance per normalized address or 6-decimal point; `cached: true` marks a hit.
- Address 5 to 200 characters. Coordinates in valid ranges.
- 15 second upstream timeout, 2 MB cap.
- Geography layers use the Census "current" benchmark; district layers change with each redistricting, and the layer name used is returned in `congressionalDistrict.layer`.