Docs
Open Lodol
DocumentationIntegrationsAPI

Zippopotam.us

App · Travel & Places · 8 actions

Look up postal codes and zip codes from a workflow, in the 70 countries Zippopotam.us covers. Turn a postal code into the places it covers, with the state and coordinates, or a city into every code it holds. Check whether a code someone typed into a form is real, and whether it matches the city and state they typed with it, both answering yes or no rather than failing the step. Get one point for a code as numbers a mapping or weather step can use, measure how far apart two codes are in kilometres and miles, or rank a list of codes to find the branch, depot or territory nearest an address. Every action reads: nothing here changes anything, at this service or anywhere else. No account or API key required.

Actions

ActionWhat it does
Check a postal codeCheck whether a postal code really exists in a country, and get back a yes or a no rather than a failed step.
Check a postal code matches a placeCheck that a postal code and the city or state someone typed alongside it actually go together, which is the question an address form has to answer once it knows the code is real.
Find postal codes for a cityFind every postal code a city holds, which is the lookup the other way round: give a country, a state and a city and get the codes back.
Find the nearest postal codeGiven one postal code and a list of others, find which of them is closest, with all of them ranked by distance.
Get coordinates for a postal codeGet one latitude and longitude for a postal code, as numbers a mapping, weather or routing step can use directly.
List supported countriesList the 70 countries Zippopotam.us covers, with each one's two-letter code, the other names it answers to, an example postal code, the range it holds, how many codes that is, and the form it stores them in.
Look up a postal codeLook up a postal code and get every place it covers: the place name, the state and its abbreviation, and the coordinates, as numbers rather than as the strings the service sends.
Measure the distance between two postal codesMeasure how far apart two postal codes are, in kilometres and in miles, so a workflow can decide whether an address is inside a delivery radius, which depot serves it, or what to charge for shipping.

Check a postal code

Check whether a postal code really exists in a country, and get back a yes or a no rather than a failed step. This is the action for validating what a person typed into a form: a code that does not exist is an answer, not an error, and so is a country the service does not cover, so a workflow can branch on the result and tell the person what to fix. It reports the form that country stores its codes in, so the message can say what a valid one looks like. No API key required.

Inputs

CountrycountrytextRequired
Which country the postal code is in. A two-letter code or a name, matched without regard to case, spacing or accents, so 'US', 'us', 'USA' and 'United States' all work, as do 'Netherlands' and 'Holland', the name this service's own table uses. Run 'List supported countries' to see the 70 it covers.
Postal codepostal_codetextRequired
The postal code to look up. Written the way people write it: a code read out of a spreadsheet as the number 2108 is padded back to 02108, a ZIP+4 keeps its first five digits, a full British postcode is trimmed to its outward half, a Canadian one to its first three characters, and the punctuation Poland, Japan, Brazil, Portugal, the Czech Republic and Slovakia store is put back. The answer always says what was actually looked up.

Outputs

asked_forobject
countrytext
country_codetext
country_supportedtrue/false
existstrue/false
normalizedtrue/false
place_countnumber
place_nameslist
placeslist
postal_codetext
postal_code_formattext
reasontext
summarytext
urltext
Example output
{
  "asked_for": {
    "country": "US",
    "postal_code": "90210"
  },
  "country": "United States",
  "country_code": "US",
  "country_supported": true,
  "exists": true,
  "normalized": false,
  "place_count": 1,
  "place_names": [
    "Beverly Hills"
  ],
  "places": [
    {
      "country": "United States",
      "country_code": "US",
      "label": "Beverly Hills, CA 90210, United States",
      "latitude": 34.0901,
      "longitude": -118.4065,
      "place_name": "Beverly Hills",
      "post_code": "90210",
      "state": "California",
      "state_abbreviation": "CA"
    }
  ],
  "postal_code": "90210",
  "postal_code_format": "5 digits, such as 00210",
  "reason": "",
  "summary": "Beverly Hills, CA 90210, United States",
  "url": "https://api.zippopotam.us/us/90210"
}

Check a postal code matches a place

Check that a postal code and the city or state someone typed alongside it actually go together, which is the question an address form has to answer once it knows the code is real. Give a place name, a state, or both. The state is matched against its name and its abbreviation, so 'California' and 'CA' are the same answer, and names are compared without regard to case, punctuation or accents. Answers rather than failing, and says what disagreed. No API key required.

Inputs

CountrycountrytextRequired
Which country the postal code is in. A two-letter code or a name, matched without regard to case, spacing or accents, so 'US', 'us', 'USA' and 'United States' all work, as do 'Netherlands' and 'Holland', the name this service's own table uses. Run 'List supported countries' to see the 70 it covers.
Postal codepostal_codetextRequired
The postal code to look up. Written the way people write it: a code read out of a spreadsheet as the number 2108 is padded back to 02108, a ZIP+4 keeps its first five digits, a full British postcode is trimmed to its outward half, a Canadian one to its first three characters, and the punctuation Poland, Japan, Brazil, Portugal, the Czech Republic and Slovakia store is put back. The answer always says what was actually looked up.
Expected city or placeplace_nametext
The city the postal code is supposed to be in. Leave empty to check only the state. A name that contains the other counts as agreement, so 'New York City' against 'New York' is a match rather than a mismatch.
Expected statestatetext
The state, province or region the postal code is supposed to be in, by name or by abbreviation. Leave empty to check only the city. Give at least one of the two.

Outputs

actual_placeslist
actual_state_abbreviationslist
actual_stateslist
asked_forobject
countrytext
country_codetext
country_supportedtrue/false
existstrue/false
matchestrue/false
place_matchestrue/false
placeslist
postal_codetext
reasontext
state_matchestrue/false
summarytext
urltext
Example output
{
  "actual_places": [
    "Beverly Hills"
  ],
  "actual_state_abbreviations": [
    "CA"
  ],
  "actual_states": [
    "California"
  ],
  "asked_for": {
    "country": "US",
    "place_name": "Beverly Hills",
    "postal_code": "90210",
    "state": "CA"
  },
  "country": "United States",
  "country_code": "US",
  "country_supported": true,
  "exists": true,
  "matches": true,
  "place_matches": true,
  "places": [
    {
      "country": "United States",
      "country_code": "US",
      "label": "Beverly Hills, CA 90210, United States",
      "latitude": 34.0901,
      "longitude": -118.4065,
      "place_name": "Beverly Hills",
      "post_code": "90210",
      "state": "California",
      "state_abbreviation": "CA"
    }
  ],
  "postal_code": "90210",
  "reason": "",
  "state_matches": true,
  "summary": "Beverly Hills, CA 90210, United States",
  "url": "https://api.zippopotam.us/us/90210"
}

Find postal codes for a city

Find every postal code a city holds, which is the lookup the other way round: give a country, a state and a city and get the codes back. The service wants the state's abbreviation rather than its name, so a US state or a Canadian province written out in full is translated here and every other country is passed through as given. It matches a city's name exactly rather than searching, so 'New York' finds it and 'NYC' does not. No API key required.

Inputs

CountrycountrytextRequired
Which country the postal code is in. A two-letter code or a name, matched without regard to case, spacing or accents, so 'US', 'us', 'USA' and 'United States' all work, as do 'Netherlands' and 'Holland', the name this service's own table uses. Run 'List supported countries' to see the 70 it covers.
StatestatetextRequired
The state, province or region the city is in. The service wants the abbreviation, so Massachusetts is 'MA'; a US state or a Canadian province written out in full is translated. Elsewhere, use whatever the postal code lookup reports as the state abbreviation for that country.
CitycitytextRequired
The city, matched exactly rather than searched, so an abbreviation or a nickname will not find it. Case, spacing and accents do not matter.

Outputs

asked_forobject
citytext
countrytext
country_codetext
foundtrue/false
latitudenumber
longitudenumber
map_urltext
place_countnumber
placeslist
places_with_coordinatesnumber
postal_code_countnumber
postal_codeslist
statetext
state_abbreviationtext
summarytext
urltext
Example output
{
  "asked_for": {
    "city": "Belmont",
    "country": "US",
    "state": "Massachusetts"
  },
  "city": "Belmont",
  "country": "United States",
  "country_code": "US",
  "found": true,
  "latitude": 42.3959,
  "longitude": -71.1787,
  "map_url": "https://www.openstreetmap.org/?mlat=42.3959&mlon=-71.1787#map=12/42.3959/-71.1787",
  "place_count": 1,
  "places": [
    {
      "country": "United States",
      "country_code": "US",
      "label": "Belmont, MA 02478, United States",
      "latitude": 42.3959,
      "longitude": -71.1787,
      "place_name": "Belmont",
      "post_code": "02478",
      "state": "Massachusetts",
      "state_abbreviation": "MA"
    }
  ],
  "places_with_coordinates": 1,
  "postal_code_count": 1,
  "postal_codes": [
    "02478"
  ],
  "state": "Massachusetts",
  "state_abbreviation": "MA",
  "summary": "Belmont, MA 02478, United States",
  "url": "https://api.zippopotam.us/us/ma/belmont"
}

Find the nearest postal code

Given one postal code and a list of others, find which of them is closest, with all of them ranked by distance. This is the step that routes a lead to its nearest branch, picks the warehouse that should ship an order, or assigns a customer to a territory. A code in the list that does not exist is reported alongside the ranking rather than failing the step, so one bad row does not lose the answer. Each code is a request, so the list is capped at 25. No API key required.

Inputs

CountrycountrytextRequired
Which country the postal code is in. A two-letter code or a name, matched without regard to case, spacing or accents, so 'US', 'us', 'USA' and 'United States' all work, as do 'Netherlands' and 'Holland', the name this service's own table uses. Run 'List supported countries' to see the 70 it covers.
Postal codepostal_codetextRequired
The postal code to look up. Written the way people write it: a code read out of a spreadsheet as the number 2108 is padded back to 02108, a ZIP+4 keeps its first five digits, a full British postcode is trimmed to its outward half, a Canadian one to its first three characters, and the punctuation Poland, Japan, Brazil, Portugal, the Czech Republic and Slovakia store is put back. The answer always says what was actually looked up.
Postal codes to compare againstcandidateslistRequired
The postal codes to rank by distance from the one above. A list from an earlier step, or several typed in separated by commas. At most 25, because each one is a separate request to a free service. Duplicates are dropped.
Country of those codescandidate_countrytext
Leave this empty unless the codes being compared really are in another country: they are then all read in the country above, which is what almost every search wants. Setting it changes how every one of them is read, so a two-letter value here is a country and never a state. 'CA' is Canada, where a code is stored as its first three characters, so US ZIP codes sent there become 904, 911, 921 and match nothing.
Report the distance inunittext
Which unit the headline distance and the ordering use. Both kilometres and miles come back either way, so this only picks which one a message reads and which one a condition compares.One of: kilometers (Kilometres), miles. Default: kilometers.
How many to returnlimitnumber
How many of the ranked codes to return, nearest first. Leave empty for all of them. Every code given is looked up either way, so this only trims the answer.From 1 to 25.

Outputs

candidate_countnumber
candidate_countrytext
candidate_country_codetext
candidates_looked_uplist
countnumber
found_countnumber
fromobject
nearestobject
not_foundlist
requests_madenumber
resultslist
summarytext
truncatedtrue/false
unittext
without_coordinateslist
Example output
{
  "candidate_count": 2,
  "candidate_country": "United States",
  "candidate_country_code": "US",
  "candidates_looked_up": [
    {
      "given": "90401",
      "looked_up": "90401"
    },
    {
      "given": "99999",
      "looked_up": "99999"
    }
  ],
  "count": 1,
  "found_count": 1,
  "from": {
    "country": "United States",
    "country_code": "US",
    "latitude": 34.0901,
    "longitude": -118.4065,
    "map_url": "https://www.openstreetmap.org/?mlat=34.0901&mlon=-118.4065#map=12/34.0901/-118.4065",
    "place_count": 1,
    "place_names": [
      "Beverly Hills"
    ],
    "places_with_coordinates": 1,
    "postal_code": "90210",
    "summary": "Beverly Hills, CA 90210, United States",
    "url": "https://api.zippopotam.us/us/90210"
  },
  "nearest": {
    "country_code": "US",
    "distance": 11.397,
    "kilometers": 11.397,
    "latitude": 34.0154,
    "longitude": -118.4912,
    "map_url": "https://www.openstreetmap.org/?mlat=34.0154&mlon=-118.4912#map=12/34.0154/-118.4912",
    "miles": 7.082,
    "place_names": [
      "Santa Monica"
    ],
    "postal_code": "90401",
    "summary": "Santa Monica, CA 90401, United States"
  },
  "not_found": [
    "99999"
  ],
  "requests_made": 3,
  "results": [
    {
      "country_code": "US",
      "distance": 11.397,
      "kilometers": 11.397,
      "latitude": 34.0154,
      "longitude": -118.4912,
      "map_url": "https://www.openstreetmap.org/?mlat=34.0154&mlon=-118.4912#map=12/34.0154/-118.4912",
      "miles": 7.082,
      "place_names": [
        "Santa Monica"
      ],
      "postal_code": "90401",
      "summary": "Santa Monica, CA 90401, United States"
    }
  ],
  "summary": "90401 is the nearest of 2",
  "truncated": false,
  "unit": "kilometers",
  "without_coordinates": []
}

Get coordinates for a postal code

Get one latitude and longitude for a postal code, as numbers a mapping, weather or routing step can use directly. A postal code often covers several places, each with its own point, so this returns the middle of them and says how many it averaged, rather than presenting one place's coordinates as the code's own. Name a place to get that one place's point exactly instead. No API key required.

Inputs

CountrycountrytextRequired
Which country the postal code is in. A two-letter code or a name, matched without regard to case, spacing or accents, so 'US', 'us', 'USA' and 'United States' all work, as do 'Netherlands' and 'Holland', the name this service's own table uses. Run 'List supported countries' to see the 70 it covers.
Postal codepostal_codetextRequired
The postal code to look up. Written the way people write it: a code read out of a spreadsheet as the number 2108 is padded back to 02108, a ZIP+4 keeps its first five digits, a full British postcode is trimmed to its outward half, a Canadian one to its first three characters, and the punctuation Poland, Japan, Brazil, Portugal, the Czech Republic and Slovakia store is put back. The answer always says what was actually looked up.
Narrow to one placeplace_nametext
Which of the places the code covers to take the point from. Leave empty to get the middle of all of them. Naming a place the code does not cover fails the step and says what it does cover.

Outputs

asked_forobject
countrytext
country_codetext
exacttrue/false
latitudenumber
longitudenumber
map_urltext
place_countnumber
place_nametext
placeslist
places_averagednumber
postal_codetext
summarytext
urltext
Example output
{
  "asked_for": {
    "country": "US",
    "place_name": "",
    "postal_code": "90210"
  },
  "country": "United States",
  "country_code": "US",
  "exact": true,
  "latitude": 34.0901,
  "longitude": -118.4065,
  "map_url": "https://www.openstreetmap.org/?mlat=34.0901&mlon=-118.4065#map=12/34.0901/-118.4065",
  "place_count": 1,
  "place_name": "Beverly Hills",
  "places": [
    {
      "country": "United States",
      "country_code": "US",
      "label": "Beverly Hills, CA 90210, United States",
      "latitude": 34.0901,
      "longitude": -118.4065,
      "place_name": "Beverly Hills",
      "post_code": "90210",
      "state": "California",
      "state_abbreviation": "CA"
    }
  ],
  "places_averaged": 1,
  "postal_code": "90210",
  "summary": "Beverly Hills, CA 90210, United States",
  "url": "https://api.zippopotam.us/us/90210"
}

List supported countries

List the 70 countries Zippopotam.us covers, with each one's two-letter code, the other names it answers to, an example postal code, the range it holds, how many codes that is, and the form it stores them in. Use it to find out whether a country can be validated at all before a workflow tries, or to tell someone what a valid code looks like where they are. All 70 are shown, not a first few. This action makes no request: the list is the service's own published table. No API key required.

Inputs

Narrow tosearchtext
Only countries whose code, name or other names match this text. Leave empty for all 70. Matched without regard to case, punctuation or accents.
Sort bysort_bytext
What order the countries come back in. By name by default, which is how the service's own table reads.One of: name (Country name), code (Two-letter code), postal_code_count (Most postal codes first). Default: name.

Outputs

countnumber
countrieslist
queryobject
totalnumber
total_postal_codesnumber
urltext
Example output
{
  "count": 70,
  "countries": [
    {
      "also_known_as": [
        "PRT"
      ],
      "code": "PT",
      "example": "1000-001",
      "example_url": "https://api.zippopotam.us/pt/1000-001",
      "name": "Portugal",
      "postal_code_count": 204006,
      "postal_code_format": "7 digits, a '-' after 4, such as 1000-001",
      "range_from": "1000-001",
      "range_to": "9980-999"
    },
    {
      "also_known_as": [
        "USA",
        "United States of America",
        "America",
        "U.S.",
        "U.S.A."
      ],
      "code": "US",
      "example": "00210",
      "example_url": "https://api.zippopotam.us/us/00210",
      "name": "United States",
      "postal_code_count": 43624,
      "postal_code_format": "5 digits, such as 00210",
      "range_from": "00210",
      "range_to": "99950"
    }
  ],
  "query": {
    "search": "",
    "sort_by": "postal_code_count"
  },
  "total": 70,
  "total_postal_codes": 895395,
  "url": "https://www.zippopotam.us/"
}

Look up a postal code

Look up a postal code and get every place it covers: the place name, the state and its abbreviation, and the coordinates, as numbers rather than as the strings the service sends. A code often covers more than one place, so all of them come back rather than a first one picked as the answer. Works for the 70 countries Zippopotam.us covers, and the code is put into the form that country stores before it is looked up, so a ZIP read out of a spreadsheet as 2108 still finds Boston. The step fails if there is no such code; use 'Check a postal code' to ask instead. No API key required.

Inputs

CountrycountrytextRequired
Which country the postal code is in. A two-letter code or a name, matched without regard to case, spacing or accents, so 'US', 'us', 'USA' and 'United States' all work, as do 'Netherlands' and 'Holland', the name this service's own table uses. Run 'List supported countries' to see the 70 it covers.
Postal codepostal_codetextRequired
The postal code to look up. Written the way people write it: a code read out of a spreadsheet as the number 2108 is padded back to 02108, a ZIP+4 keeps its first five digits, a full British postcode is trimmed to its outward half, a Canadian one to its first three characters, and the punctuation Poland, Japan, Brazil, Portugal, the Czech Republic and Slovakia store is put back. The answer always says what was actually looked up.

Outputs

asked_forobject
countrytext
country_codetext
foundtrue/false
latitudenumber
longitudenumber
map_urltext
normalizedtrue/false
place_countnumber
place_nameslist
placeslist
places_with_coordinatesnumber
postal_codetext
state_abbreviationslist
stateslist
summarytext
urltext
Example output
{
  "asked_for": {
    "country": "US",
    "postal_code": "90210"
  },
  "country": "United States",
  "country_code": "US",
  "found": true,
  "latitude": 34.0901,
  "longitude": -118.4065,
  "map_url": "https://www.openstreetmap.org/?mlat=34.0901&mlon=-118.4065#map=12/34.0901/-118.4065",
  "normalized": false,
  "place_count": 1,
  "place_names": [
    "Beverly Hills"
  ],
  "places": [
    {
      "country": "United States",
      "country_code": "US",
      "label": "Beverly Hills, CA 90210, United States",
      "latitude": 34.0901,
      "longitude": -118.4065,
      "place_name": "Beverly Hills",
      "post_code": "90210",
      "state": "California",
      "state_abbreviation": "CA"
    }
  ],
  "places_with_coordinates": 1,
  "postal_code": "90210",
  "state_abbreviations": [
    "CA"
  ],
  "states": [
    "California"
  ],
  "summary": "Beverly Hills, CA 90210, United States",
  "url": "https://api.zippopotam.us/us/90210"
}

Measure the distance between two postal codes

Measure how far apart two postal codes are, in kilometres and in miles, so a workflow can decide whether an address is inside a delivery radius, which depot serves it, or what to charge for shipping. The two codes can be in different countries. Both distances always come back; the unit only picks the headline. The measurement is a great-circle distance between the two codes' points, so it is how far apart they are, not how far it is to drive. No API key required.

Inputs

CountrycountrytextRequired
Which country the postal code is in. A two-letter code or a name, matched without regard to case, spacing or accents, so 'US', 'us', 'USA' and 'United States' all work, as do 'Netherlands' and 'Holland', the name this service's own table uses. Run 'List supported countries' to see the 70 it covers.
Starting postal codefrom_postal_codetextRequired
The postal code to measure from, in the country above. Written however people write it; it is put into the form that country stores before it is looked up.
Destination postal codeto_postal_codetextRequired
The postal code to measure to. In the same country unless a destination country is set below.
Destination countryto_countrytext
Leave this empty unless the destination really is in another country: both codes are then read in the country above, which is what almost every measurement wants. Setting it changes how the destination code is read, not just where it is looked up, so a two-letter value here is a country and never a state. 'CA' is Canada.
Report the distance inunittext
Which unit the headline distance and the ordering use. Both kilometres and miles come back either way, so this only picks which one a message reads and which one a condition compares.One of: kilometers (Kilometres), miles. Default: kilometers.

Outputs

distancenumber
fromobject
kilometersnumber
milesnumber
requests_madenumber
same_countrytrue/false
summarytext
toobject
unittext
Example output
{
  "distance": 11.397,
  "from": {
    "country": "United States",
    "country_code": "US",
    "latitude": 34.0901,
    "longitude": -118.4065,
    "map_url": "https://www.openstreetmap.org/?mlat=34.0901&mlon=-118.4065#map=12/34.0901/-118.4065",
    "place_count": 1,
    "place_names": [
      "Beverly Hills"
    ],
    "places_with_coordinates": 1,
    "postal_code": "90210",
    "summary": "Beverly Hills, CA 90210, United States",
    "url": "https://api.zippopotam.us/us/90210"
  },
  "kilometers": 11.397,
  "miles": 7.082,
  "requests_made": 2,
  "same_country": true,
  "summary": "Beverly Hills, CA 90210, United States to Santa Monica, CA 90401, United States is 11.4 km",
  "to": {
    "country": "United States",
    "country_code": "US",
    "latitude": 34.0154,
    "longitude": -118.4912,
    "map_url": "https://www.openstreetmap.org/?mlat=34.0154&mlon=-118.4912#map=12/34.0154/-118.4912",
    "place_count": 1,
    "place_names": [
      "Santa Monica"
    ],
    "places_with_coordinates": 1,
    "postal_code": "90401",
    "summary": "Santa Monica, CA 90401, United States",
    "url": "https://api.zippopotam.us/us/90401"
  },
  "unit": "kilometers"
}

ZeroBounce

Previous Page

Ziptastic

Next Page

On this page

ActionsCheck a postal codeCheck a postal code matches a placeFind postal codes for a cityFind the nearest postal codeGet coordinates for a postal codeList supported countriesLook up a postal codeMeasure the distance between two postal codes