API reference

GET/v1/addresses

Suggest addresses as the customer types

Narrows to an address from the starts of its words, its number and its outward code, in any order (`ches 37 brom mk43`), forgiving a typo. Scope `address:search`. Free: the lookup of the pick is charged.

• 200 At most 10 suggestions, the best first.

GET/v1/addresses/{uprn}

Look up an address by its UPRN

Scope `address:lookup`. One credit where the address is found.

• 200 The address's record.
• 404 A failure, with its code.

GET/v1/postcodes/{postcode}/addresses

Every address of a postcode

Scope `address:lookup`. One credit where the postcode has addresses.

• 200 The postcode as Royal Mail writes it, and its addresses in order.
• 404 A failure, with its code.

GET/v1/geocode/forward

Geocode an address as written

Scope `geocode`. One credit.

• 200 The addresses that the text may be, the best first.

POST/v1/geocode/forward

Geocode up to 100 addresses

Scope `geocode`. One credit each.

• 200 What each query found, in their order.

GET/v1/geocode/reverse

The addresses nearest a point

Scope `geocode`. One credit.

• 200 The addresses within the radius, nearest first.

POST/v1/geocode/reverse

Reverse geocode up to 100 points

Scope `geocode`. One credit each.

• 200 What each query found, in their order.

POST/v1/cleansing/jobs

Send a job of addresses to cleanse

Up to 100,000 addresses as written, each matched to its record apart from this request. Scope `geocode`. One credit each, as each is cleansed; a live job needs the credits it will use (`credits_exhausted`).

• 202 The job, to poll at its `Location`.

GET/v1/cleansing/jobs/{id}

A job, and how far through it is

• 200 The job.
• 404 A failure, with its code.

GET/v1/cleansing/jobs/{id}/results

A page of a job's results

• 200 The job, its items from `after`, and the `after` of the next page.
• 404 A failure, with its code.

GET/v1/geography

The areas of a point or a postcode

Give a point (`lat`, `lng`), for the areas whose boundaries cover it, or a `postcode`, for those the ONS Postcode Directory gives it. Scope `place:read`. One credit.

• 200 The areas, by kind.
• 404 A failure, with its code.

POST/v1/zones/contains

Which of your zones hold each point

Scope `place:read`. One credit for each point.

• 200 Each point, and the IDs of the zones that hold it.

GET/v1/places

Places of interest near a point

Rail stations, Tube, metro and tram stations and bus stops (Great Britain), and schools with their Ofsted inspection (England). Scope `place:read`. One credit.

• 200 The places, nearest first.

GET/v1/places/amenities

The nearest place of each category

Scope `place:read`. One credit.

• 200 The nearest of each category within the distance, in the order of the categories.

GET/v1/location-lists

Your location lists

Scope `locations:read`.

• 200 The lists.

POST/v1/location-lists

Make a location list

Scope `locations:write`.

• 201 The list.

GET/v1/location-lists/{list_id}

A list

• 200 The list.
• 404 A failure, with its code.

PATCH/v1/location-lists/{list_id}

Rename a list

• 200 The list.

DELETE/v1/location-lists/{list_id}

Delete a list and its locations

• 204 Deleted.
• 404 A failure, with its code.

GET/v1/location-lists/{list_id}/locations

A page of a list's locations

Scope `locations:read`.

• 200 The locations, and the cursor of the next page.

POST/v1/location-lists/{list_id}/locations

Write up to 1,000 locations

Each item has its own result; the batch is `200` unless the list is not found or it has too many items. Scope `locations:write`.

• 200 A result for each item, in their order.

GET/v1/location-lists/{list_id}/locations/{id}

A location

• 200 The location.
• 404 A failure, with its code.

PUT/v1/location-lists/{list_id}/locations/{id}

Write a location in full

An address without `lat` and `lng` is geocoded, for one credit. Scope `locations:write`.

• 200 Updated
• 201 Created.

PATCH/v1/location-lists/{list_id}/locations/{id}

Change some of a location's fields

A field given as `null` is removed.

• 200 The location.

DELETE/v1/location-lists/{list_id}/locations/{id}

Delete a location

• 204 Deleted.
• 404 A failure, with its code.

GET/v1/location-lists/{list_id}/changes

A list's changes since a sequence

• 200 The changes in order, the cursor of the next page, and the list's sequence.

GET/v1/location-lists/{list_id}/nearest

The nearest of a list's locations

From a point, a postcode or an address (one credit more), within a radius or a box. Scope `locations:query`, which a publishable key may have. One credit.

• 200 The origin as it was found, and the locations, nearest first.

GET/v1/location-lists/{list_id}/search

Search a list by name or ID

• 200 The matches, the best first.

POST/v1/locations/nearest

The nearest of up to 1,000 points sent with the query

• 200 The origin, and the points nearest first.

GET/v1/maps/styles/{style}

A map's style

For MapLibre GL: `new maplibregl.Map({style: 'https://api.zapex.co.uk/v1/maps/styles/color?key=zpx_pk_live_…'})`. Its parts are at the routes below, with the publishable key in their URLs. Scope `maps:read`. One credit: a map load.

• 200 A MapLibre style.

GET/v1/maps/tilesets/{archive}

The TileJSON of an archive

• 200 TileJSON 3.0.0.

GET/v1/maps/tiles/{archive}/{z}/{x}/{y}

A tile

As it is stored, with its `Content-Encoding`. Not rate limited, and not charged.

• 200 The tile.
• 204 The archive has no tile there.

GET/v1/maps/fonts/{fontstack}/{range}

A range of a font stack's glyphs

• 200 The glyphs.

GET/v1/maps/sprites/{style}/{file}

A file of a style's sprite

• 200 The file.

GET/v1/maps/static

A static map, as a PNG

Scope `maps:read`. One credit.

• 200 The map.

GET/v1/datasets

The datasets the API answers from

Each dataset's publisher, licence and coverage, and the release loaded. No key is needed.

• 200 The datasets.