API Documentation

Authentication

Every v3 request takes your API key in the x-key header. The keyless v2 endpoint is rate-limited and free.

curl -H "x-key: YOUR_KEY" https://zip.getziptastic.com/v3/US/48867

Forward geocoding

Turn a postal code into readable locale information.

GET /v3/<country_code>/<postal_code>

Response

200 OK

[
  {
    "country": "US",
    "postal_code": "48867",
    "city": "Owosso",
    "county": "Shiawassee",
    "state": "Michigan",
    "state_short": "MI",
    "latitude": 42.9934,
    "longitude": -84.1595,
    "timezone": "America/Detroit",
    "geohash": "dpshsfsytw8k"
  }
]

Response fields

A lookup returns a JSON array (a postal code can map to more than one locale). Coordinates and timezone are present for every result; administrative fields depend on what the source data provides for that country — treat them as optional and code defensively.

Field	Description	Availability
`country`	ISO 3166-1 alpha-2 code	Always
`postal_code`	The (normalized) code that matched	Always
`city`	City / place / locality name	Always
`latitude`, `longitude`	Representative point (WGS84)	Always
`timezone`	IANA timezone (e.g. `Europe/London`)	Always
`geohash`	Geohash of the point	Always
`state`	Region / province / state name	Most countries
`state_short`	Region abbreviation	~88% of codes — may be empty (e.g. Singapore)
`county`	County / district / second-level area	~65% of codes — often empty (e.g. UAE, Singapore)
`cbsa_code`, `cbsa_name`	US metro (Core-Based Statistical Area)	US only, where a CBSA applies

Country coverage & granularity

Ziptastic covers 120+ countries. The granularity of a postal code — how much of it you pass and how precise the answer is — varies by country's postal system. Pass the code at the level Ziptastic stores it:

Granularity	What you pass	Examples
Full postal code	The complete code	US `48867` (5-digit), most of Europe & Asia
District / prefix	The leading portion only	UK `SW1A` (outward code), Canada `M5V` (FSA), Netherlands `1011` (PC4)

Ziptastic normalizes input where it safely can — a US ZIP+4 like 48867-1234 is trimmed to 48867, and a full Canadian code M5V 2T6 to its M5V forward sortation area. For countries stored at district level (e.g. the UK), pass the outward code; a full postcode such as SW1A 1AA will not match.

Two helpers make coverage easy to work with:

GET /v3/<country>/list — every postal code Ziptastic holds for a country, so you can see its granularity and extent directly.
GET /v3/resolve?q=… — the forgiving resolver infers country and normalizes the code for you; ideal when input is loosely formatted or agent-supplied.

Reverse geocoding

Turn coordinates into the nearest locales, ranked by distance.

GET /v3/reverse/<latitude>/<longitude>/<radius_in_meters>

Batch lookups agent-friendly

Resolve up to 100 codes in a single round-trip, each with its own result or error.

curl -X POST -H "x-key: YOUR_KEY" -H "content-type: application/json" \
  -d '{"lookups":[{"country":"US","postal_code":"48867"},
                  {"country":"GB","postal_code":"SW1A"}]}' \
  https://zip.getziptastic.com/v3/batch

Note the UK code is the outward code (SW1A), not the full postcode — see coverage & granularity below.

Forgiving resolve agent-friendly

Pass a loose string and let Ziptastic infer the country and code.

GET /v3/resolve?q=48867

Machine-readable spec

Agents can discover every endpoint and its shape from the OpenAPI document.

GET /openapi.json

MCP server

Use Ziptastic natively from any MCP client (Claude, Cursor, …). Six tools, all authenticated with your key.

{
  "mcpServers": {
    "ziptastic": {
      "command": "python",
      "args": ["-m", "ziptastic_mcp.server"],
      "env": { "ZIPTASTIC_API_KEY": "YOUR_KEY" }
    }
  }
}

Official & community libraries

Find official libraries on GitHub (jQuery, PHP, Python, and more). See full code examples →

Node Ziptastic by Ben Drucker
Angular Ziptastic by Ben Drucker
Ziptastic Ruby Gem by Ezekiel Templin
.NET Ziptastic by Justin Porter