Zippopotam.us API: Get postal code
Looks up the places, regions and coordinates for a postal code in a supported country on Zippopotam.us.
Unofficial. Not affiliated with or endorsed by Zippopotam.us.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Country optional
country Country name or two-letter country code, such as Germany or DE. Defaults to United States.
United States (default)
- Postal Code, required
postal_code Postal code to look up, such as 90210 or 10115.
90210
Input as JSON
{ "postal_code": "90210"}Output
{ "places": [ { "state": "California", "latitude": 34.0901, "page_url": "https://api.zippopotam.us/us/90210" , "longitude": -118.4065, "place_name": "Beverly Hills", "state_abbreviation": "CA" } ], "country": "United States", "postal_code": "90210"}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"zippopotam.us/get_postal_code","input":{"postal_code":"90210"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "zippopotam.us/get_postal_code" , "input": { "postal_code": "90210" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "zippopotam.us/get_postal_code" , "input": { "postal_code": "90210" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run zippopotam.us/get_postal_code# with {"postal_code":"90210"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "postal_code" ], "properties": { "country": { "type": "string", "default": "United States", "description": "Country name or two-letter country code, such as Germany or DE. Defaults to United States." }, "postal_code": { "type": "string", "description": "Postal code to look up, such as 90210 or 10115." } }, "additionalProperties": false}Output schema
{ "type": "object", "required": [ "country", "postal_code", "places" ], "properties": { "places": { "type": "array", "items": { "type": "object", "required": [ "place_name", "state", "state_abbreviation", "latitude", "longitude", "page_url" ], "properties": { "state": { "type": [ "string", "null" ], "description": "State or region name." }, "latitude": { "type": [ "number", "null" ], "description": "Latitude in decimal degrees." }, "page_url": { "type": "string", "description": "Link to this postal code on Zippopotam.us." }, "longitude": { "type": [ "number", "null" ], "description": "Longitude in decimal degrees." }, "place_name": { "type": [ "string", "null" ], "description": "Place name." }, "state_abbreviation": { "type": [ "string", "null" ], "description": "State or region abbreviation." } }, "additionalProperties": false }, "description": "Places using this postal code." }, "country": { "type": "string", "description": "Country name." }, "postal_code": { "type": "string", "description": "Postal code looked up." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
zippopotam.us/get_postal_code- Returns
- country, postal code, places with state and coordinates
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method zippopotam.us/get_postal_code with the inputs above.
Ask your agent
- What city and state does ZIP code 73301 belong to, and what are its coordinates?
- Find the places and latitude/longitude for German postal code 10115.
- Look up postal code 90210 in the US and tell me the state and coordinates of each place.
- I need the town and region for the Canadian postal code M5V, along with its coordinates.
- Using zippopotam.us, what locations are tied to postal code 02101 in the United States?
See more
All Zippopotam.us methodsFinds postal codes, place names and coordinates for a town and state or region in a country covered by Zippopotam.us.
zippopotam.us/search_postal_codesLooks up a UK postcode on Postcodes.io, including its location, administrative areas and whether it is still in use. Retired postcodes return location and retirement year only.
postcodes.io/get_postcodeLooks up an Indian six-digit PIN code and lists its post offices with branch type, delivery status and postal area.
postalpincode.in/get_pin_codeFinds map coordinates and address details for an address or place on OpenStreetMap, optionally restricted to a country.
openstreetmap.org/get_coordinatesFinds Indian post offices matching a place name, with PIN codes, branch types, delivery statuses, districts and states. Optionally narrows by state or district.
postalpincode.in/search_pin_codesMatches a US street address and returns its city or place, county, state, ZIP code, census tract, congressional and state legislative districts, coordinates and FIPS codes. Districts follow the Census Geocoder's current geography vintage and may differ from sitting representation.
census.gov/get_address_detailsEstimates domestic USPS Post Office retail postage between two ZIP Codes for a letter, large envelope, package or flat-rate packaging, by weight and mailing date. Media Mail is left out; a zero-weight letter counts as one ounce. Prices are retail, cheapest first, with each service's estimated delivery.
usps.com/estimate_postageFinds the public location and network operator of an IPv4 or IPv6 address. Private and reserved addresses have no public location.
ipinfo.io/get_ip_location