Data API
PlaygroundDashboardWebsite
Postcode

Search postcodes

Signed in? Open this endpoint in the dashboard playground, which uses your organization automatically. Signed out, use Try in Playground below with your API key.

GET
/postcode/search

Looks up a postcode by text, or the postcode covering a point.

  • Provide postcode, or provide both lat and lon. Sending both forms is a 400.
  • US: Census ZCTA5 polygons. Deviation (approximated): ZCTA is not a USPS ZIP code. PO-box-only and unique-organisation ZIPs have no polygon, so they return an empty result. ZIP+4 input (46204-1234, 9 digits) is reduced to the 5-digit ZIP.
  • Canada: Statistics Canada FSA polygons (3 characters, e.g. K1M), plus points for full 6-character codes (e.g. K1M 2B2) derived from National Address Register address points. Deviation (approximated): full codes have a centroid only, never a polygon, even with geometry=original. Special government codes such as K1A 0B1 are not in the data and return an empty result.
  • Matching is exact after upper-casing and removing spaces and hyphens. With lat/lon, the polygon(s) covering the point are returned; outside every polygon, the nearest postcode point (ZCTA, FSA or full-code centroid) within 1 km, one result (with distance in metres), else an empty result.
  • An empty result is HTTP 200 with features: [] (or results: []), not 404.
  • datasource per result: census-zcta5, statcan-fsa or statcan-nar, each with its attribution.

Not supported: none of Geoapify's parameters are dropped. Countries other than US and CA are accepted by countrycode but have no data.

Example: postcode=46204&countrycode=us

Authorization

queryapiKey<token>

Your API key from the dashboard, sent as ?apiKey=<key>.

Query Parameters

postcode?string

Postcode text. Mutually exclusive with lat/lon. Case, spaces and hyphens are ignored (k1m 2b2 = K1M2B2). US: 5 digits (ZIP+4 accepted). Canada: 3-character FSA or 6-character code. Deviation (approximated): exact match only, no prefix or fuzzy matching.

Length1 <= length <= 1024
lat?number

Latitude for reverse postcode search. Requires lon; not allowed with postcode.

Range-90 <= value <= 90
lon?number

Longitude for reverse postcode search. Requires lat; not allowed with postcode.

Range-180 <= value <= 180
countrycode?string

ISO 3166-1 alpha-2 country filter (lowercase). Only us and ca can return results. Deviation (empty): any other country returns an empty result.

Value in"ad""ae""af""ag""ai""al""am""an""ao""ap""aq""ar""as""at""au""aw""az""ba""bb""bd""be""bf""bg""bh""bi""bj""bm""bn""bo""br""bs""bt""bv""bw""by""bz""ca""cc""cd""cf""cg""ch""ci""ck""cl""cm""cn""co""cr""cu""cv""cx""cy""cz""de""dj""dk""dm""do""dz""ec""ee""eg""eh""er""es""et""eu""fi""fj""fk""fm""fo""fr""ga""gb""gd""ge""gf""gg""gh""gi""gl""gm""gn""gp""gq""gr""gs""gt""gu""gw""gy""hk""hm""hn""hr""ht""hu""id""ie""im""il""in""io""iq""ir""is""it""je""jm""jo""jp""ke""kg""kh""ki""km""kn""kp""kr""kw""ky""kz""la""lb""lc""li""lk""lr""ls""lt""lu""lv""ly""ma""mc""md""me""mg""mh""mk""ml""mm""mn""mo""mp""mq""mr""ms""mt""mu""mv""mw""mx""my""mz""na""nc""ne""nf""ng""ni""nl""no""np""nr""nu""nz""om""pa""pe""pf""pg""ph""pk""pl""pm""pr""ps""pt""pw""py""qa""re""ro""rs""ru""rw""sa""sb""sc""sd""se""sg""sh""si""sj""sk""sl""sm""sn""so""sr""st""sv""sy""sz""tc""td""tf""tg""th""tj""tk""tm""tn""to""tr""tt""tv""tw""tz""ua""ug""um""us""uy""uz""va""vc""ve""vg""vi""vn""vu""wf""ws""ye""yt""za""zm""zw"
lang?string

Language for the state name (falls back to the default OSM name). Other fields are not translated. Deviation (approximated): only state is localised.

Value in"ab""aa""af""ak""sq""am""ar""an""hy""as""av""ae""ay""az""bm""ba""eu""be""bn""bh""bi""bs""br""bg""my""ca""ch""ce""ny""zh""cv""kw""co""cr""hr""cs""da""dv""nl""en""eo""et""ee""fo""fj""fi""fr""ff""gl""ka""de""el""gn""gu""ht""ha""he""hz""hi""ho""hu""ia""id""ie""ga""ig""ik""io""is""it""iu""ja""jv""kl""kn""kr""ks""kk""km""ki""rw""ky""kv""kg""ko""ku""kj""la""lb""lg""li""ln""lo""lt""lu""lv""gv""mk""mg""ms""ml""mt""mi""mr""mh""mn""na""nv""nb""nd""ne""ng""nn""no""ii""nr""oc""oj""cu""om""or""os""pa""pi""fa""pl""ps""pt""qu""rm""rn""ro""ru""sa""sc""sd""se""sm""sg""sr""gd""sn""si""sk""sl""so""st""es""su""sw""ss""sv""ta""te""tg""th""ti""bo""tk""tl""tn""to""tr""ts""tt""tw""ty""ug""uk""ur""uz""ve""vi""vo""wa""cy""wo""fy""xh""yi""yo""za"
format?string

geojson (default, application/geo+json), json (application/json, a results array of the feature properties) or xml (application/xml).

Default"geojson"
Value in"json""geojson""xml"
geometry?string

point (default): a point inside the postcode. original: the source polygon (ZCTA or FSA); full Canadian codes have no polygon and stay points. Applies to geojson format. Deviation (approximated): original is the Census/StatCan boundary, not USPS/Canada Post geometry.

Default"point"
Value in"point""original"

Response Body

Postcode search result in the requested format. An unknown postcode gives an empty list.

  1. response
type*unknown
features*array<>
Example Request
curl -X GET 'https://api.data.graphitelab.ai/v1/postcode/search?postcode=46204&lat=39.7684&lon=-86.1581&countrycode=us&lang=en&format=json&geometry=point'
Example Response
{  "results": [    {      "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",      "continent": "North America",      "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"    }  ]}

Find boundaries contained by a place GET

Previous Page

List postcodes GET

Next Page