API Reference
API Reference
Check a postcode
POST https://serviceareawizard.com/api/v1/check
Headers
| Header | Value |
|---|---|
Authorization | Bearer <your-secret-token> |
Content-Type | application/json |
Body
| Field | Type | Required | Description |
|---|---|---|---|
destination | string | Yes | The customer's postcode / zip code. Spaces and case don't matter. |
service_area_id | string | No | Which 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"
}
}
| Field | Description |
|---|---|
in_area | true if the destination is in your service area |
reason | Why: district_included, area_included, within_radius, district_excluded, area_excluded, outside_radius or not_listed |
distance_km | Straight-line distance from your service area's postcode, in kilometres |
radius_km | The service area's radius, or null if it only uses a list of postcodes |
service_area | The service area that was used |
destination | The 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:
- A postcode district you've included or excluded (e.g.
SE28,10001,2150) - A whole area you've included or excluded (e.g. all
SE, all100xx, all20xx) - 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.
| Status | data.code | Meaning |
|---|---|---|
400 | Missing or invalid destination | |
401 | invalid_token | Missing, invalid or revoked token |
404 | postcode_not_found | We don't recognise the postcode / zip code in your service area's country |
422 | no_service_area | You haven't created a service area, or service_area_id isn't yours |
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,GBandUS. - UK data is by postcode district (like
SW11).withinandsearchreturn districts, and a district's localities are the place names its postcodes use. Looking up a full UK postcode (likeSW11 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
| Parameter | Description |
|---|---|
country | AU, GB or US |
postcode | The centre postcode. Or send lat and lng instead. |
radius_km | 1 to 100 |
exclude_po_boxes | Optional. 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." } }
| Status | Meaning |
|---|---|
400 | Bad input, e.g. a missing or out of range parameter |
401 | Missing or invalid API token |
404 | Unknown postcode |
429 | Rate 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.