Postcode search

GET /v1/postcode/search returns the postcode feature for a postcode string, or the postcode covering a latitude and longitude. Use it to validate a ZIP or postal code, get a representative point for it, or fetch its boundary polygon. For prefix search and filtering over many postcodes, use the postcode list endpoint instead.

How it worksCopy Anchor Link

No Engine is called. The gateway answers from PostGIS tables in the geo schema, joined to Nominatim's placex for the state name.

1. On first use the gateway builds a point index (gateway.postcode_index) from the source tables, and rebuilds it when their row counts change.

2. Text lookup: the input is upper-cased with spaces and hyphens removed, then matched exactly against the index. A nine-digit US ZIP+4 is cut to its 5-digit ZIP. If a code exists as both an FSA and a full code, the FSA comes first.

3. Point lookup: returns every ZCTA or FSA polygon that covers the point. If none does, it returns the single nearest postcode point within 1 km, with distance in meters. Otherwise the result is empty.

Data sources:

Quick startCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/postcode/search?postcode=46204&countrycode=us&apiKey=$GRAPHITE_API_KEY"

{
  "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": "46204",
        "ref": "46204",
        "country": "United States",
        "country_code": "us",
        "state": "Indiana",
        "state_code": "IN",
        "iso3166_2": "US-IN",
        "lon": -86.15696934391093,
        "lat": 39.772695,
        "formatted": "46204, Indiana, United States",
        "result_type": "postcode",
        "place_id": "gp:pc:US-46204"
      },
      "geometry": {
        "type": "Feature",
        "properties": {},
        "geometry": { "type": "Point", "coordinates": [-86.15696934391093, 39.772695] }
      },
      "bbox": [-86.15696934391093, 39.772695, -86.15696934391093, 39.772695]
    }
  ]
}

The response is trimmed (continent omitted).

ParametersCopy Anchor Link

Send postcode, or both lat and lon. Sending both forms is a 400, and so is sending neither.

Full parameter reference

ResponseCopy Anchor Link

With format=geojson the body is a FeatureCollection. With format=json it is { "results": [...] }, one object per feature properties.

An unknown postcode is HTTP 200 with features: [] (or results: []), not 404. This endpoint does not return rank.

Differences from GeoapifyCopy Anchor Link

• approximated: US results use Census ZCTA, not USPS ZIP codes. PO-box-only ZIPs have no polygon and return empty.

• approximated: Canadian full 6-character codes return an address-derived centroid only. FSA codes return the StatCan polygon.

• empty: Only US and Canadian postcodes exist. Special codes such as K1A 0B1 return empty, and any other countrycode returns an empty result.

• extra: Typed place_id (gp:pc:...) and datasource sourcename values census-zcta5, statcan-fsa, statcan-nar.

Parameter-level deviations: postcode is an exact match after normalization (no fuzzy matching); lang localizes only state; geometry=original is the Census or StatCan boundary, not USPS or Canada Post geometry.

US and Canada notesCopy Anchor Link

• US: ZCTA is a Census approximation of ZIP delivery areas. ZIPs for PO boxes only or for single organizations have no polygon. ZIP+4 input is reduced to the 5-digit ZIP.

• Canada: a 3-character input hits the FSA (polygon available). A 6-character input hits a NAR-derived point, never a polygon, even with geometry=original. Government codes such as K1A 0B1 are not in the data.

• Reverse search outside every polygon snaps to the nearest postcode point within 1 km (ZCTA, FSA or full-code centroid), one result.

More examplesCopy Anchor Link

curl -s "https://api.data.graphitelab.ai/v1/postcode/search?postcode=K1M2B2&countrycode=ca&apiKey=$GRAPHITE_API_KEY"

Errors and limitsCopy Anchor Link

Limits: postcode is at most 1024 characters, and the reverse nearest-point fallback reaches 1 km.