# Zippopotam.us API: Search postal codes

> Finds postal codes, place names and coordinates for a town and state or region in a country covered by Zippopotam.us.

Unofficial. Not affiliated with or endorsed by Zippopotam.us.

- Page: https://fous.com/methods/zippopotam.us/search-postal-codes
- Method: `zippopotam.us/search_postal_codes`, version 1
- Website: zippopotam.us
- Returns: postal codes, place names, coordinates, detail links
- Effect: read (it gets data and changes nothing)
- Sign-in: none needed
- Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free
- Verified: Nov 2, 2026

## Inputs

| Field | Type | Required | In the run below | Description |
|---|---|---|---|---|
| `town` | string | yes | `"Beverly Hills"` | Town to search, for example Beverly Hills. |
| `state` | string | yes | `"California"` | State or region name or abbreviation, for example California or CA. |
| `country` | string | no |  | Country name or two-letter country code, for example United States or US. Defaults to United States. Default "United States". |

## Output

From a run on Oct 23, 2026, shortened. Its input:

```json
{
  "town": "Beverly Hills",
  "state": "California"
}
```

Its output:

```json
{
  "postal_codes": [
    {
      "town": "Beverly Hills",
      "state": "California",
      "country": "United States",
      "latitude": 33.7866,
      "longitude": -118.2987,
      "page_link": "https://zippopotam.us/us/90209",
      "place_name": "Beverly Hills",
      "postal_code": "90209"
    },
    {
      "town": "Beverly Hills",
      "state": "California",
      "country": "United States",
      "latitude": 34.0901,
      "longitude": -118.4065,
      "page_link": "https://zippopotam.us/us/90210",
      "place_name": "Beverly Hills",
      "postal_code": "90210"
    },
    {
      "town": "Beverly Hills",
      "state": "California",
      "country": "United States",
      "latitude": 34.0652,
      "longitude": -118.383,
      "page_link": "https://zippopotam.us/us/90211",
      "place_name": "Beverly Hills",
      "postal_code": "90211"
    }
  ]
}
```

## Run it

From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output:

```bash
curl https://api.fous.com/v1/runs \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"zippopotam.us/search_postal_codes","input":{"town":"Beverly Hills","state":"California"}}'
```

From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`.

## Ask your agent

- What postal codes are used in Austin, Texas?
- Find the zip codes and coordinates for Boulder in CO.
- I need the postal codes for Kingston in Ontario, Canada.
- Look up place names and lat/long for Springfield, Illinois, US.
- Which zip codes cover Santa Fe, New Mexico?

## Input schema

```json
{
  "type": "object",
  "required": [
    "town",
    "state"
  ],
  "properties": {
    "town": {
      "type": "string",
      "description": "Town to search, for example Beverly Hills."
    },
    "state": {
      "type": "string",
      "description": "State or region name or abbreviation, for example California or CA."
    },
    "country": {
      "type": "string",
      "default": "United States",
      "description": "Country name or two-letter country code, for example United States or US. Defaults to United States."
    }
  }
}
```

## Output schema

```json
{
  "type": "object",
  "required": [
    "postal_codes"
  ],
  "properties": {
    "postal_codes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "country",
          "state",
          "town",
          "postal_code",
          "place_name",
          "latitude",
          "longitude",
          "page_link"
        ],
        "properties": {
          "town": {
            "type": "string",
            "description": "Town searched."
          },
          "state": {
            "type": "string",
            "description": "State or region name."
          },
          "country": {
            "type": "string",
            "description": "Country name."
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ],
            "description": "Latitude, if available."
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ],
            "description": "Longitude, if available."
          },
          "page_link": {
            "type": "string",
            "description": "Link to the postal code details."
          },
          "place_name": {
            "type": "string",
            "description": "Place name associated with the postal code."
          },
          "postal_code": {
            "type": "string",
            "description": "Postal code."
          }
        },
        "additionalProperties": false
      },
      "description": "Postal codes in ascending order; empty if none match."
    }
  },
  "additionalProperties": false
}
```

## See more

- [Zippopotam.us API: Get postal code](https://fous.com/methods/zippopotam.us/get-postal-code.md): Looks up the places, regions and coordinates for a postal code in a supported country on Zippopotam.us.
- [U.S. Census Bureau API: Get address details](https://fous.com/methods/census.gov/get-address-details.md): Matches a US street address and returns its city or place, county, state, ZIP code, census tract, congressional and state legislative districts, coordinates and FIPS codes. Districts follow the Census Geocoder's current geography vintage and may differ from sitting representation.
- [Postal PIN Code API: Search post offices by place](https://fous.com/methods/postalpincode.in/search-pin-codes.md): Finds Indian post offices matching a place name, with PIN codes, branch types, delivery statuses, districts and states. Optionally narrows by state or district.
- [Postcodes.io API: Get postcode details](https://fous.com/methods/postcodes.io/get-postcode.md): Looks up a UK postcode on Postcodes.io, including its location, administrative areas and whether it is still in use. Retired postcodes return location and retirement year only.
- [House API: Get my representatives](https://fous.com/methods/house.gov/get-my-representatives.md): Finds the current House representative and both senators for a US ZIP code or street address, with office contacts and photos. A ZIP covering several districts returns every possible representative until an address identifies one.
- [OpenStreetMap API: Search places](https://fous.com/methods/openstreetmap.org/search-places.md): Finds named places or kinds of places in a city or area, in search order, using OpenStreetMap Nominatim. Results may be fewer than requested. Data © OpenStreetMap contributors (ODbL).
- [OpenStreetMap API: Get coordinates for an address](https://fous.com/methods/openstreetmap.org/get-coordinates.md): Finds map coordinates and address details for an address or place on OpenStreetMap, optionally restricted to a country.
- [AutoZone API: Search stores near a location](https://fous.com/methods/autozone.com/search-stores.md): Finds the AutoZone stores nearest a US ZIP code, city or street address, with contact details, opening hours, whether each is open now, distance and store page links.
- [All Zippopotam.us methods](https://fous.com/methods/zippopotam.us.md)