List postcodes

GET /v1/postcode/list returns postcodes for the United States and Canada. Narrow them with a code prefix (text), spatial or place filters and a country, order them with bias, and page with limit and offset. Use it to find which postcodes fall inside a circle, rectangle or another postcode area, or to autocomplete a code prefix. For a single lookup by code or coordinates, see Postcode search.

How it worksCopy Anchor Link

No Waterfall or routing Engine is involved. The gateway answers from one indexed PostGIS table (gateway.postcode_index) in the Nominatim Postgres cluster, as one SQL query with your filters, bias ordering and paging applied. It is the same data as /postcode/search.

state, state_code and iso3166_2 come from the OSM state or province boundary covering the postcode's point. Postcode results themselves are never OSM-derived.

Quick startCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/postcode/list?filter=circle:-86.158,39.768,3000&countrycode=us&limit=2&apiKey=$GRAPHITE_API_KEY"

ZCTA5 areas within 3 km of downtown Indianapolis (trimmed to the first result):

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "datasource": {
          "sourcename": "census-zcta5",
          "attribution": "US Census Bureau, TIGER/Line ZIP Code Tabulation Areas",
          "url": "https://www.census.gov/programs-surveys/geography/guidance/geo-areas/zctas.html"
        },
        "postcode": "46202",
        "ref": "46202",
        "distance": 2016,
        "country": "United States",
        "continent": "North America",
        "country_code": "us",
        "state": "Indiana",
        "state_code": "IN",
        "iso3166_2": "US-IN",
        "lon": -86.1752756520431,
        "lat": 39.7803265,
        "formatted": "46202, Indiana, United States",
        "result_type": "postcode",
        "place_id": "gp:pc:US-46202"
      },
      "geometry": {
        "type": "Feature",
        "properties": {},
        "geometry": { "type": "Point", "coordinates": [-86.1752756520431, 39.7803265] }
      },
      "bbox": [-86.1752756520431, 39.7803265, -86.1752756520431, 39.7803265]
    }
  ]
}

ParametersCopy Anchor Link

Full parameter reference

ResponseCopy Anchor Link

Each result has these fields in properties (or directly on each item with format=json):

With geometry=point the GeoJSON feature holds a nested Feature with the Point and a degenerate bbox. With geometry=original it holds the Polygon or MultiPolygon and its real bbox; 6-character Canadian codes have no polygon and stay points. Polygons can be large, so keep limit small. There is no rank on this endpoint.

Differences from GeoapifyCopy Anchor Link

• empty: Address-component, timezone and plus_code fields (city, district, suburb, county, timezone, plus_code, address_line1, ...) are never returned; only the fields in the schema are emitted.

• extra: place_id is the readable gp:pc:<COUNTRY>-<code> format. Geoapify place IDs are not accepted.

• unsupported: Coverage is US and Canada only; other country codes return no results.

• approximated (text): Prefix match on the code only, not free-text search.

• approximated (filter): rect, circle and place test the postcode's representative point, not area overlap; place: takes our gp: IDs (gp:pc:* and gp:osm:*), and an unknown ID matches nothing.

• approximated (geometry): original returns the ZCTA5/FSA boundary at full detail; 6-character Canadian codes have no polygon.

• approximated (lang): Only the state name is localized; country names are always English.

US and Canada notesCopy Anchor Link

• A ZCTA is not a USPS ZIP. PO-box-only ZIPs have no area and are not listed.

• Canada returns two kinds of results: 3-character FSAs (areas) and full 6-character postal codes (centroid points from the NAR). A text prefix such as K1A returns both, areas first, then 6-character codes, then by code.

• Several bias values apply in the order given.

• state comes from the OSM boundary covering the point; lang localizes its name, falling back to the default name when none exists.

More examplesCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/postcode/list?text=46204&countrycode=us&limit=1&geometry=original&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

limit is 1-500 (default 5), offset is 0 or more, text is 1-1024 characters. An empty match returns a 200 with an empty list.