DEVELOPER GUIDE

Start with a postcode.
Build from there.

A practical introduction to the read-only mapapi endpoints. Access, source licensing and the enabled services are agreed for your integration.

Download OpenAPI specification ↓

Connect securely

Use HTTPS and a Bearer token issued for your integration. Keep the token on your server. The examples below contain a placeholder, not a working key.

curl --get 'https://api.mapapi.co.uk/v1/addresses' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'postcode=LS8 5HS' \
  --data-urlencode 'limit=20'

All listed endpoints use GET. A key can be limited to specific scopes, usage limits and source IPs. PAF endpoints also require the relevant licensed access to be enabled.

Addresses & postcodes

Endpoint	Use it to
`/v1/addresses?postcode=LS8%205HS`	List addresses for an exact postcode.
`/v1/addresses/{id}`	Retrieve an address by the source address ID returned by the list.
`/v1/postcodes/{postcode}`	Retrieve postcode coordinates and matching published regions.

Postcode responses distinguish whether coordinates are available. precision: "postcode" describes a postcode location, not a building entrance. The address ID and Royal Mail UDPRN are separate identifiers.

GET /v1/postcodes/LS8%205HS

// Selected example fields; this is not a live lookup.
{
  "data": {
    "postcode": "LS8 5HS",
    "available": true,
    "precision": "postcode"
  }
}

Handle available: false explicitly. Missing coordinates should not automatically approve a delivery or silently substitute a guessed point.

Areas & boundaries

Endpoint	Use it to
`/v1/regions`	Browse published regions.
`/v1/regions/{id}`	Retrieve an individual published region and its geometry.
`/v1/regions/{id}/children`	Follow the published region hierarchy.
`/v1/regions/lookup?lat=53.8&lng=-1.55`	Find published regions containing a coordinate.
`/v1/regions/changes?since=0`	Synchronise published region changes.

Use region IDs together with their type and source. Administrative wards, informal neighbourhoods and custom delivery areas can have different boundaries. Coverage depends on the available published data.

Driving distance in miles

curl --get 'https://api.mapapi.co.uk/v1/routes/distance' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'from=LS1 4DY' \
  --data-urlencode 'to=LS8 5HS'

The endpoint returns distance_miles, distance_metres, estimated duration and the road points used by the routing engine. The route follows the self-hosted engine’s driving recommendation. It is not a guarantee of the shortest or fastest possible journey.

Both postcodes need valid coordinates and a routable connection within the installed road dataset. Postcode points may be snapped to nearby roads; they are not individual entrances. Live traffic is not included. Confirm geographic coverage when arranging access.

Pagination, errors & retries

List responses use data and meta. When meta.next_cursor is present, send it as cursor with the same filters to continue. Treat cursor values as opaque and stop when the next cursor is null.

Status	What to do
401 / 403	Check the key, its scopes and access restrictions.
404	Handle a missing resource without assuming a replacement.
422	Check the request or the returned coordinate/route availability reason.
429	Respect the `Retry-After` response header.
502 / 503 / 504	Use bounded retries and handle temporary service unavailability.

The OpenAPI specification gives endpoint parameters, schemas and error details. Preserve any X-Request-ID when reporting an issue.

Discuss your integration →