API — CodePostalPro

The API serves the same dataset as this site — 100,373 localities across the United States, France, Algeria, Tunisia and Morocco — as JSON, from https://api.codepostalpro.com. It is read-only, CORS-enabled and needs no key for up to 1,000 requests a day per IP. Every record carries its sources and a verification status, so a result can be cited, not just used.

Try it

curl https://api.codepostalpro.com/v1/postal/US/90210

{
  "country": "US", "postal_code": "90210", "count": 1,
  "results": [{
    "postal_code": "90210", "city": "Beverly Hills", "county": "Los Angeles",
    "region": { "slug": "california", "name": "California", "code": "CA", "type": "state" },
    "location": { "lat": 34.0901, "lon": -118.4065, "accuracy": 4 },
    "time_zone": "America/Los_Angeles",
    "area_codes": ["310", "424"], "area_codes_method": "rate-centre-match",
    "demographics": { "population": 19652, "median_household_income": 190382, "median_age": 51.2, "source": "census-acs5", "geography": "ZCTA" },
    "sources": ["geonames-us", "census-acs5"], "verification": "source-single",
    "url": "https://codepostalpro.com/united-states/california/beverly-hills/90210"
  }]
}

Endpoints

Endpoint	Returns
`GET /v1`	Index, data vintage and record counts
`GET /v1/countries`	Countries, postal-code formats, hierarchy labels, key facts
`GET /v1/postal/{country}/{code}`	Every locality carrying a postal code
`GET /v1/search?q=&country=&limit=`	Name or code-prefix search
`GET /v1/nearby?lat=&lon=&radius_km=&country=&limit=`	Localities around a point, with distance
`GET /v1/regions/{country}/{region}`	A state, région or wilaya with its cities / departments
`GET /v1/groups/{country}/{region}/{group}`	A city, département or delegation with its localities
`GET /v1/localities/{country}/{region}/{group}/{locality}`	One locality record

{country} accepts an ISO code (US, FR) or the site's slug (united-states). Slugs for regions, groups and localities are the ones in this site's URLs, so any page here maps to one API call.

Fields worth knowing

verification — cross-checked, source-single, conflict or unverified. On conflict, alternate_codes lists the other values with their source. We never pick one silently.
area_codes_method — rate-centre-match when the city's own NANPA rate centre was found; nearest-rate-centre when taken from the nearest matched city. A ZIP and an area code are different boundaries.
demographics.geography — always ZCTA: the Census approximation of a ZIP area, not the USPS route.
time_zone — IANA zone of the nearest populated place; per-country offsets are in /v1/countries.

Keys and limits

Plan	Per day	Per minute	How
Anonymous	1,000 per IP	60	No key
Free	5,000	300	One POST, below
Pro	100,000	3,000	Ask us — paid plans open soon

curl -X POST https://api.codepostalpro.com/v1/keys -H "Content-Type: application/json" -d '{"email":"you@example.com"}'

Send the key as X-Api-Key or Authorization: Bearer. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; GET /v1/keys/me shows your plan and today's usage. One key per email — posting again returns the same key.

For AI agents — MCP server

The same data is available as an MCP server at https://api.codepostalpro.com/mcp (Streamable HTTP, stateless, no session to manage). Add it to Claude, Cursor, or any MCP-capable client:

{ "mcpServers": { "codepostalpro": { "url": "https://api.codepostalpro.com/mcp" } } }

Tools: lookup_postal_code, search_places, nearby_places, get_region, get_group, list_countries. Tool descriptions explain the fields and their caveats — what a ZCTA is, what "nearest rate centre" means, what to do on a conflict — so an agent can relay provenance rather than a bare number. Pass an API key as X-Api-Key for the higher limits; the quotas above apply per tool call.

Terms

Data is redistributed under its source licences — chiefly GeoNames CC BY 4.0, U.S. Census public domain and NANPA public records — so attribution to those sources, and to CodePostalPro as compiler, is required in anything you publish from it. See data sources for each licence.