# Zippopotam.us

> 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.

App · Travel & Places · 8 actions. Web page: https://docs.lodol.com/docs/integrations/zippopotam

## Actions

### 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**

- Country (`country`, text, required): 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 code (`postal_code`, text, required): 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_for` (object)
- `country` (text)
- `country_code` (text)
- `country_supported` (true/false)
- `exists` (true/false)
- `normalized` (true/false)
- `place_count` (number)
- `place_names` (list)
- `places` (list)
- `postal_code` (text)
- `postal_code_format` (text)
- `reason` (text)
- `summary` (text)
- `url` (text)

**Example output**

```json
{
  "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**

- Country (`country`, text, required): 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 code (`postal_code`, text, required): 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 place (`place_name`, text): 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 state (`state`, text): 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_places` (list)
- `actual_state_abbreviations` (list)
- `actual_states` (list)
- `asked_for` (object)
- `country` (text)
- `country_code` (text)
- `country_supported` (true/false)
- `exists` (true/false)
- `matches` (true/false)
- `place_matches` (true/false)
- `places` (list)
- `postal_code` (text)
- `reason` (text)
- `state_matches` (true/false)
- `summary` (text)
- `url` (text)

**Example output**

```json
{
  "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**

- Country (`country`, text, required): 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.
- State (`state`, text, required): 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.
- City (`city`, text, required): 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_for` (object)
- `city` (text)
- `country` (text)
- `country_code` (text)
- `found` (true/false)
- `latitude` (number)
- `longitude` (number)
- `map_url` (text)
- `place_count` (number)
- `places` (list)
- `places_with_coordinates` (number)
- `postal_code_count` (number)
- `postal_codes` (list)
- `state` (text)
- `state_abbreviation` (text)
- `summary` (text)
- `url` (text)

**Example output**

```json
{
  "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**

- Country (`country`, text, required): 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 code (`postal_code`, text, required): 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 against (`candidates`, list, required): 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 codes (`candidate_country`, text): 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 in (`unit`, text): 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 return (`limit`, number): 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_count` (number)
- `candidate_country` (text)
- `candidate_country_code` (text)
- `candidates_looked_up` (list)
- `count` (number)
- `found_count` (number)
- `from` (object)
- `nearest` (object)
- `not_found` (list)
- `requests_made` (number)
- `results` (list)
- `summary` (text)
- `truncated` (true/false)
- `unit` (text)
- `without_coordinates` (list)

**Example output**

```json
{
  "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**

- Country (`country`, text, required): 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 code (`postal_code`, text, required): 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 place (`place_name`, text): 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_for` (object)
- `country` (text)
- `country_code` (text)
- `exact` (true/false)
- `latitude` (number)
- `longitude` (number)
- `map_url` (text)
- `place_count` (number)
- `place_name` (text)
- `places` (list)
- `places_averaged` (number)
- `postal_code` (text)
- `summary` (text)
- `url` (text)

**Example output**

```json
{
  "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 to (`search`, text): 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 by (`sort_by`, text): 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**

- `count` (number)
- `countries` (list)
- `query` (object)
- `total` (number)
- `total_postal_codes` (number)
- `url` (text)

**Example output**

```json
{
  "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**

- Country (`country`, text, required): 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 code (`postal_code`, text, required): 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_for` (object)
- `country` (text)
- `country_code` (text)
- `found` (true/false)
- `latitude` (number)
- `longitude` (number)
- `map_url` (text)
- `normalized` (true/false)
- `place_count` (number)
- `place_names` (list)
- `places` (list)
- `places_with_coordinates` (number)
- `postal_code` (text)
- `state_abbreviations` (list)
- `states` (list)
- `summary` (text)
- `url` (text)

**Example output**

```json
{
  "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**

- Country (`country`, text, required): 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 code (`from_postal_code`, text, required): 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 code (`to_postal_code`, text, required): The postal code to measure to. In the same country unless a destination country is set below.
- Destination country (`to_country`, text): 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 in (`unit`, text): 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**

- `distance` (number)
- `from` (object)
- `kilometers` (number)
- `miles` (number)
- `requests_made` (number)
- `same_country` (true/false)
- `summary` (text)
- `to` (object)
- `unit` (text)

**Example output**

```json
{
  "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"
}
```