Postal Code

Look up city, state, and geographic coordinates for any postal code worldwide. Covers 100+ countries using the GeoNames postal code dataset.

Get API Key

Overview

Use Cases

Auto-fill city and state fields from a zip/postal code
Validate postal codes during checkout or registration
Geocode postal codes to display on a map
Calculate distances between postal code areas

Features

100+ countries supported (US, CA, GB, DE, AU, and more)

Returns city, state/province, country, latitude, and longitude

Default country: US (omit the country param for US lookups)

ISO 3166-1 alpha-2 country codes

API Endpoints

Lookup Postal Code

Returns city, state, country, and coordinates for the given postal code.

GET

https://api.requiems.xyz/v1/places/postal/{code}

Parameters

Name	Type	Required	Description
code	`string`	Required	The postal code to look up (e.g. 10001 for New York, SW1A 1AA for London)
country	`string`	Optional	ISO 3166-1 alpha-2 country code (default: US)

Try it out

Live Demo

Request

code * (string)

The postal code to look up (e.g. 10001 for New York, SW1A 1AA for London)

country (string)

ISO 3166-1 alpha-2 country code (default: US)

Response Fields

Field	Type	Description
postal_code	`string`	The postal code as stored in the dataset
city	`string`	Primary city or place name for the postal code
state	`string`	State, province, or administrative region name
country	`string`	ISO 3166-1 alpha-2 country code (uppercase)
lat	`number`	Latitude of the postal code centroid
lon	`number`	Longitude of the postal code centroid

Code Examples

# US zip code (default country)
curl "https://api.requiems.xyz/v1/places/postal/10001" \
  -H "requiems-api-key: YOUR_API_KEY"

# UK postcode
curl "https://api.requiems.xyz/v1/places/postal/SW1A1AA?country=GB" \
  -H "requiems-api-key: YOUR_API_KEY"

import requests

url = "https://api.requiems.xyz/v1/places/postal/10001"
headers = {"requiems-api-key": "YOUR_API_KEY"}

response = requests.get(url, params={"country": "US"}, headers=headers)
data = response.json()
print(data["data"]["city"])   # New York City

const response = await fetch(
  'https://api.requiems.xyz/v1/places/postal/10001?country=US',
  { headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.city);  // New York City

require 'net/http'
require 'json'

uri = URI('https://api.requiems.xyz/v1/places/postal/10001')
uri.query = URI.encode_www_form(country: 'US')

request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data['data']['city']

Error Responses

not_found

The postal code was not found for the given country.

internal_error

Unexpected server error.

No results found