Postal Code
Look up city, state, and geographic coordinates for any postal code worldwide. Covers 100+ countries using the GeoNames postal code dataset.
Descripción general
Casos de uso
- 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
Funcionalidades
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
Puntos finales de la API
Lookup Postal Code
Returns city, state, country, and coordinates for the given postal code.
GET
https://requiems.xyz/v1/places/postal/{code}
Parámetros
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| code | string |
Obligatorio | The postal code to look up (e.g. 10001 for New York, SW1A 1AA for London) |
| country | string |
Opcional | ISO 3166-1 alpha-2 country code (default: US) |
Pruébalo
Demostración en vivoSolicitud
The postal code to look up (e.g. 10001 for New York, SW1A 1AA for London)
ISO 3166-1 alpha-2 country code (default: US)
Sending request...
Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
| 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 |
Ejemplos de código
# US zip code (default country)
curl "https://requiems.xyz/v1/places/postal/10001" \
-H "requiems-api-key: YOUR_API_KEY"
# UK postcode
curl "https://requiems.xyz/v1/places/postal/SW1A1AA?country=GB" \
-H "requiems-api-key: YOUR_API_KEY"import requests
url = "https://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 Cityconst response = await fetch(
'https://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 Cityrequire 'net/http'
require 'json'
uri = URI('https://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']Respuestas de error
not_found
The postal code was not found for the given country.
internal_error
Unexpected server error.
Batch Lookup Postal Codes
Look up city, state, and coordinates for up to 50 postal codes in a single request. Results are returned in input order.
POST
https://requiems.xyz/v1/places/postal/batch
Parámetros
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| items | array<object> |
Obligatorio | List of postal code lookups (1–50 items). |
| items[].code | string |
Obligatorio | The postal code to look up. |
| items[].country | string |
Opcional | ISO 3166-1 alpha-2 country code (default: US). |
Pruébalo
Demostración en vivoSolicitud
List of postal code lookups (1–50 items).
The postal code to look up.
ISO 3166-1 alpha-2 country code (default: US).
Sending request...
Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
| results | array<object> |
Per-item results in input order. |
| results[].code | string |
The postal code as provided in the request. |
| results[].country | string |
The country code used for the lookup (defaulted to US when omitted). |
| results[].found | boolean |
Whether the postal code was found in the dataset. |
| results[].result | object |
Postal code details (omitted when found is false). |
| total | integer |
Total number of items processed. |
Ejemplos de código
curl -X POST https://requiems.xyz/v1/places/postal/batch \
-H "requiems-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"items": [{"code": "10001", "country": "US"}, {"code": "SW1A1AA", "country": "GB"}]}'import requests
url = "https://requiems.xyz/v1/places/postal/batch"
headers = {
"requiems-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"items": [
{"code": "10001", "country": "US"},
{"code": "SW1A1AA", "country": "GB"}
]
}
response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
if item["found"]:
print(item["code"], item["result"]["city"])const response = await fetch('https://requiems.xyz/v1/places/postal/batch', {
method: 'POST',
headers: {
'requiems-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
items: [
{ code: '10001', country: 'US' },
{ code: 'SW1A1AA', country: 'GB' }
]
})
});
const { data } = await response.json();
data.results.forEach(item => {
if (item.found) console.log(item.code, item.result.city);
});require 'net/http'
require 'json'
uri = URI('https://requiems.xyz/v1/places/postal/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
items: [
{ code: '10001', country: 'US' },
{ code: 'SW1A1AA', country: 'GB' }
]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)['data']
data['results'].each do |item|
puts "#{item['code']}: #{item['result']['city']}" if item['found']
endRespuestas de error
validation_failed
The items array is missing, empty, or exceeds 50 items.
bad_request
The request body is missing or malformed.
Preguntas frecuentes
The API covers 100+ countries via the GeoNames postal code dataset, including US, CA, GB, DE, FR, AU, JP, BR, and many more.
Use the format native to the country. For the US that is the 5-digit ZIP code (10001). For the UK use the postcode without spaces (SW1A1AA). The API normalises case automatically.
Some postal codes span multiple places. The API returns the primary administrative entry from the GeoNames dataset, which is typically the most populous place.
Pass an ISO 3166-1 alpha-2 code as the country query parameter (e.g. country=DE for Germany). If omitted the default is US.