Lookup · Nearby · Distance
Postal Code API
Fill city and state.
Find places nearby.
Get city, state, timezone and coordinates where available. Compare two postal locations in miles or kilometers.
Look up a postal code
Lookup, nearby and distance
Postal data.
Ready for your app.
Look up a code, find nearby codes, or compare two locations. Complete JSON for every request.
curl "https://api.parseapi.com/postal/10001?country=US&deep=true" \
-H "X-API-Key: YOUR_API_KEY"Add form.js to your fields
A ZIP code. Less typing after it.
Use form.js to fill city and state from a US ZIP code. Keep those fields editable so the person can finish their address.
When a postal code has several localities, the person chooses the right one. Missing values leave room for manual entry.
Try postal code autofillInclude the script once with your website's domain-restricted public key. Use these bindings in your existing form.
ZIP code
10001
City
New York
State
NY
City and state from the 10001 example. Keep customer input editable.
Add form.js to these fields
<script src="https://cdn.parseapi.com/v1/form.js"
data-key="parse_public_YOUR_KEY" defer></script>
<label for="form-postal">ZIP code</label>
<input id="form-postal" name="postal" autocomplete="postal-code"
data-parse="postal" data-parse-country="US">
<label for="form-city">City</label>
<input id="form-city" name="city" autocomplete="address-level2"
data-parse-from="form-postal" data-parse-fill="city">
<label for="form-state">State</label>
<input id="form-state" name="state" autocomplete="address-level1"
data-parse-from="form-postal" data-parse-fill="state">Locations around a place
Find places.
Know the distance.
Build a store locator, group a service area, or compare two postal locations. Choose a radius or get the distance in miles and kilometers.
Distances are straight-line measurements between postal reference points, where available.
Build a store locatorExample response
Charlotte
28202
New York
10001
533.19 miles
858.08 kilometers · Straight-line distance
Complete JSON response
/postal/28202/distance/10001?country=US
Optional place detail
Simple first.
More when you need it.
Add deep=true for population, area and regional detail in the same request.
Deep is available on paid plans.
- Population and area
- Population, land and water area, and elevation.
- US regional detail
- Metropolitan associations and ZIP tax references where known. Exact-address tax can differ.
This product uses the HUD User Data API but is not endorsed or certified by HUD User.
Postal → District · Time · Weather
Carry the postcode’s place forward.
Postal already returns the available city, state and county names. Reuse its codes for county details and local time, or its coordinates for weather near the postal location.
Find the postal location
/postal/10001?country=US
Fields from the response
{
"district": "36061",
"country": "US",
"latitude": 40.750649,
"longitude": -73.997298,
"timezone": "America/New_York"
}This New York ZIP returns district 36061 and timezone America/New_York, alongside the address labels.
Use
district+countryAdd county detail when needed
/district/36061?country=US
Use Postal’s district code with its country. District supplies the county profile; paid Deep adds available population and area.
Use
timezoneShow a clock for that location
/time/America/New_York
Pass Postal’s timezone to Time for a local clock response. Reuse that same timezone for conversions.
Use
latitude+longitudeGet weather near the postal location
/weather?lat=40.750649&lon=-73.997298
Use the postal reference coordinates for the nearest supported station's observation. Its reading time and distance travel with the answer.
Use this in your app
// Run on your server with PARSEAPI_KEY in the environment.
const key = process.env.PARSEAPI_KEY;
if (!key) throw new Error('Set PARSEAPI_KEY on your server.');
const segment = value => encodeURIComponent(value);
const timezonePath = zone => zone.split('/').map(segment).join('/');
async function lookup(path, query = {}) {
const url = new URL(path, 'https://api.parseapi.com');
url.search = new URLSearchParams(query).toString();
const response = await fetch(url, {
headers: { 'X-API-Key': key, 'Parse-Version': '2.0.0' },
signal: AbortSignal.timeout(10000),
});
if (!response.ok) {
const error = await response.json().catch(() => null);
throw new Error(error?.message ?? 'ParseAPI returned HTTP ' + response.status);
}
return response.json();
}
const postal = await lookup('/postal/10001', { country: 'US' });
// Independent follow-ups reuse fields from the same Postal response.
const [district, time, weather] = await Promise.all([
postal.district && postal.country
? lookup('/district/' + segment(postal.district), { country: postal.country })
: null,
postal.timezone ? lookup('/time/' + timezonePath(postal.timezone)) : null,
Number.isFinite(postal.latitude) && Number.isFinite(postal.longitude)
? lookup('/weather', { lat: String(postal.latitude), lon: String(postal.longitude) })
: null,
]);
console.log({ postal, district, time, weather });Coverage and confidence
The places we cover.
55 countries and territories. Available fields and completeness vary by country.
- United States
- Mexico
- United Kingdom
- France
- Switzerland
- Liechtenstein
- Denmark
- Japan
- Australia
- Austria
- Norway
- Finland
- Luxembourg
- Czechia
- Belgium
- Netherlands
- Slovenia
- Latvia
- Hungary
- Iceland
- Estonia
- Lithuania
- Malaysia
- Cyprus
- Mauritius
- Slovakia
- South Korea
- Colombia
- Uruguay
- Spain
- Italy
- Portugal
- Croatia
- Bulgaria
- Costa Rica
- Sri Lanka
- Nepal
- Brazil
- Faroe Islands
- Monaco
- Morocco
- Peru
- North Macedonia
- Moldova
- Albania
- Guernsey
- Jersey
- Isle of Man
- Åland
- Svalbard and Jan Mayen
- Puerto Rico
- US Virgin Islands
- Guam
- Northern Mariana Islands
- American Samoa
Missing values return null. Enter postal codes for nearby and distance. We use their stored location data where available.
Country details
- Australia
- Suburb choices for 2,634 geographic postcodes from August 2026. 694 have an unambiguous city for autofill; other codes keep city null. Each choice includes its state. Coordinates remain approximate postal-area locations.
- Albania
- 532 published codes. Postal destination names where unambiguous. Approximate postal-area coordinates for 383 codes.
- Brazil
- Codes recorded in the 2022 census, with approximate coordinates from address locations.
- Colombia
- Coordinates describe postal areas published in 2013.
- Croatia and Bulgaria
- Selected geographic postal codes with coordinates. Locality names return null.
- Faroe Islands
- Approximate village centres for mapped postal codes.
- Guernsey, Jersey, and Isle of Man
- 11,106 active codes from August 2026, with country, timezone, and currency. Names are unavailable. Jersey has approximate coordinates for 42 codes, from facility locations recorded in 2018; other codes have no coordinates.
- Italy
- Geographic postal points without locality names. Special and newly issued codes may be missing.
- Lithuania
- Eight counties, excluding Vilnius and Utena in the current edition.
- Malaysia, South Korea, Costa Rica, Sri Lanka, and Slovenia
- Names without coordinates.
- Mauritius
- Main island only. Names without coordinates.
- Mexico
- Available coordinates describe matched business locations.
- Moldova
- 1,063 ordinary office codes. Locality and region names where the served areas agree. No coordinates.
- Monaco
- The ordinary code 98000. Names without coordinates.
- Morocco
- 1,666 locality codes from September 2018, with city and province names. Neighborhood codes and southern postal regions are excluded. No coordinates.
- Nepal
- Current five-digit municipality and seven-digit ward codes. Names without coordinates.
- Netherlands
- Full six-character codes from geographic and address references. Locality names where unambiguous. Some address-reference codes have no coordinates.
- North Macedonia
- 202 corroborated codes. Postal destination names where the published names agree. No coordinates.
- Peru
- 2,669 published codes from March 2018. Locality, province, and department names where unambiguous. Approximate locality-based coordinates for 2,129 codes; several urban codes may share a point.
- Portugal
- Locality names where the published postal name agrees. Geographic coordinates. Special and newly issued codes may be missing.
- Spain
- Locality and administrative names where unambiguous.
- United Kingdom
- England, Scotland, and Wales, plus Northern Ireland postcodes with observed premises locations.
- United States and US territories
- Select US, PR, VI, GU, MP, or AS explicitly. Postal identities and geographic coverage differ; some valid ZIPs have no coordinates, city, or district. A lookup does not verify address delivery.
- Uruguay
- 121 postal areas with coordinates. Locality and department names where the address records agree.
From the first request to your app
One integration.
Room to do more.
Start with a postal lookup. Use the same key for nearby codes and distances, alongside the other ParseAPI products your app needs.
HTTP, SDKs and MCP
Copy a request above, then follow the reference for parameters, complete responses and errors. Use the existing Postal methods in your language or connect through MCP.
Before you build.
What can I build with the Postal API?
Fill city and state from a postal code, put a location on a map, schedule in its timezone, or find nearby postal codes for a store locator. Fields vary by country.
Should I send a country?
Send the two-letter country code when you know it. A code shared by several covered countries requires a country. For example, use country=JP for 100-0001. A unique code can resolve on its own.
Can I choose an Australian suburb?
Yes. localities lists suburb and state choices. Keep those choices editable and let the customer choose. city is returned only when the geographic reference has one unambiguous city.
Does a ZIP lookup verify an address?
A ZIP lookup provides postal geography. Street address, apartment and deliverability verification are separate tasks.
What do the distances measure?
Straight-line distances between postal reference points, in kilometers and miles. Nearby returns postal codes inside your radius. Road distance and travel time require a routing service.
What does Deep add?
On a paid plan, deep=true adds population, area, elevation, tax references, neighbors and metropolitan associations where available. Deep uses your API request allowance.
What does ZIP type mean?
US and qualified territory ZIPs may include type: standard, po_box, unique, military, or null when unknown. It is a recorded ZIP classification, not proof that a street address is deliverable. A military ZIP identifies USPS routing; it does not identify the recipient’s location.
How do I keep leading zeros?
Send and store postal codes as strings. A ZIP such as 00501 retains its leading zeros. Postal codes can also contain letters and spaces.
What happens when a value is unavailable?
Unavailable fields return null. A missing code returns 404. A country is required when the same code resolves in more than one covered country.
Postal API pricing
Start building.
Your API request allowance is shared across ParseAPI products.
Free
Start free
Try Postal with a free API key.
Room to grow
See plans
Choose the volume your app needs.