API Reference

Full reference for the Service Area WIZARD check endpoint, including request body, response and errors.

API Reference

Check a postcode

POST https://serviceareawizard.com/api/v1/check

Headers

HeaderValue
AuthorizationBearer <your-secret-token>
Content-Typeapplication/json

Body

FieldTypeRequiredDescription
destinationstringYesThe customer's postcode / zip code. Spaces and case don't matter.
service_area_idstringNoWhich service area to check against. Defaults to your default service area. Find IDs in the response, or on the Service areas page.
{
  "destination": "EC1A 1BB"
}

Response

200 OK

{
  "in_area": true,
  "reason": "within_radius",
  "distance_km": 3.12,
  "radius_km": 30,
  "service_area": {
    "id": "4f1c2a3b-5d6e-4f70-8a91-b2c3d4e5f601",
    "name": "Head office",
    "country": "GB",
    "postcode": "SW1A 1AA"
  },
  "destination": {
    "postcode": "EC1A 1BB",
    "place": "London"
  }
}
FieldDescription
in_areatrue if the destination is in your service area
reasonWhy: district_included, area_included, within_radius, district_excluded, area_excluded, outside_radius or not_listed
distance_kmStraight-line distance from your service area's postcode, in kilometres
radius_kmThe service area's radius, or null if it only uses a list of postcodes
service_areaThe service area that was used
destinationThe normalised postcode and its place name

How the decision is made

A service area can use a radius, a list of postcodes, or both. The most specific setting wins:

  1. A postcode district you've included or excluded (e.g. SE28, 10001, 2150)
  2. A whole area you've included or excluded (e.g. all SE, all 100xx, all 20xx)
  3. Your radius, if you've set one

So "everything within 30 km, plus all of SE, except SE28" works as you'd expect. New or unlisted full postcodes are matched by their district.

Errors

Errors return a JSON body with statusCode, statusMessage and, where relevant, data.code.

Statusdata.codeMeaning
400Missing or invalid destination
401invalid_tokenMissing, invalid or revoked token
404postcode_not_foundWe don't recognise the postcode / zip code in your service area's country
422no_service_areaYou haven't created a service area, or service_area_id isn't yours
Treat postcode_not_found as "unknown" rather than "out of area". New postcodes and typos are common, and it's better to let those enquiries through.

Postcode data

Look up postcodes, find postcodes near a point, and search postcodes and suburbs. These endpoints use the same API token as the check endpoint. They don't need a service area.

  • Rate limit: 600 requests a minute per token.
  • Caching: successful responses can be cached for a day (Cache-Control: private, max-age=86400).
  • Countries: AU, GB and US.
  • UK data is by postcode district (like SW11). within and search return districts, and a district's localities are the place names its postcodes use. Looking up a full UK postcode (like SW11 1AA) returns its own place name. UK place names are broad, often just the town or city.

Look up a postcode

GET https://serviceareawizard.com/api/v1/postcodes/{country}/{code}

Returns the postcode's point, its state and every locality it covers. Spaces and case don't matter.

{
  "country": "AU",
  "code": "2042",
  "state": "NSW",
  "lat": -33.8989,
  "lng": 151.1754,
  "localities": [
    { "name": "Enmore", "state": "NSW", "lat": -33.8997, "lng": 151.1709 },
    { "name": "Newtown", "state": "NSW", "lat": -33.8981, "lng": 151.1799 }
  ]
}

A few postcodes cross a state border. state on the postcode is its most common state, and each locality has its own.

Postcodes within a radius

GET https://serviceareawizard.com/api/v1/postcodes/within?country=AU&postcode=2042&radius_km=10
ParameterDescription
countryAU, GB or US
postcodeThe centre postcode. Or send lat and lng instead.
radius_km1 to 100
exclude_po_boxesOptional. true leaves out Australian PO box postcodes (see below).

Returns postcodes whose point is inside the radius, nearest first, up to 2,000.

{
  "centre": { "lat": -33.8989, "lng": 151.1754 },
  "radius_km": 10,
  "postcodes": [
    { "code": "2042", "state": "NSW", "distance_km": 0 },
    { "code": "1450", "state": "NSW", "distance_km": 1 },
    { "code": "2043", "state": "NSW", "distance_km": 1.1 }
  ]
}

Search postcodes and suburbs

GET https://serviceareawizard.com/api/v1/postcodes/search?country=AU&q=newt&limit=10

Made for search-as-you-type. Matches the start of a suburb name, or the start of a postcode if q contains a number. limit is 1 to 20 (default 10). Add exclude_po_boxes=true to leave out Australian PO box postcodes. Returns one result per suburb.

{
  "results": [
    { "code": "2042", "locality": "Newtown", "state": "NSW", "lat": -33.8981, "lng": 151.1799 },
    { "code": "3220", "locality": "Newtown", "state": "VIC", "lat": -38.1535, "lng": 144.338 }
  ]
}

PO box postcodes

Australia sets aside postcode ranges for PO boxes and large mail users, such as 1000 to 1999 in NSW. They have no suburb of their own, so searching "sydney" returns 1001, 1002 and so on before 2000. Add exclude_po_boxes=true to within or search to leave them out. The ranges are 0200 to 0299 (ACT), 0900 to 0999 (NT), 1000 to 1999 (NSW), 5800 to 5999 (SA), 6800 to 6999 (WA), 7800 to 7999 (TAS), 8000 to 8999 (VIC) and 9000 to 9999 (QLD). It has no effect for the UK or US.

Errors

Postcode data endpoints return errors as JSON:

{ "error": { "code": "postcode_not_found", "message": "9999 is not a known AU postcode." } }
StatusMeaning
400Bad input, e.g. a missing or out of range parameter
401Missing or invalid API token
404Unknown postcode
429Rate limit reached. Wait a minute (see the Retry-After header).

Data source

Postcode, suburb and state data comes from GeoNames, licensed under CC BY 4.0. If you show this data in your app, please credit GeoNames. See Data sources.