UPRN to Address API

Resolve a canonical Great Britain address from a UPRN, or match an address and postcode to its UPRN.

Great BritainBidirectional lookupAPI key authentication35 credits per completed lookup

Overview

This endpoint uses AddressBase data to connect a Unique Property Reference Number to its canonical address. The same endpoint can work in reverse when you provide an address and full postcode.

UPRN to address: an exact UPRN lookup returns one canonical address.
Address to UPRN: an address is matched only against records in the supplied postcode.
Ambiguous input: the API returns candidates instead of selecting a property without enough evidence.

Authentication

All requests to the UPRN to Address API require authentication using an API key. You can obtain your API key from your PropertyInsights dashboard after subscribing to an API plan.

Include your API key in the request header as follows:

X-API-Key: your_api_key_here

Security Warning

Never expose your API key in client-side code. Always make API calls from your server-side application to protect your credentials.

Endpoint

GET

https://propertyinsights.co.uk/api/v1/property/address

Request parameters

Parameter	Required	Description
uprn	Conditional	A 1 to 12 digit UPRN. Send it on its own.
address	Conditional	A full or partial address. Required with `postcode` when `uprn` is not supplied.
postcode	Conditional	A full Great Britain postcode. Required with `address`.

Choose one lookup direction. Do not combine uprn with address or postcode in the same request.

Address matching

The postcode is used first to create a small candidate set. Address text is then compared in this order:

Exact match after case, spacing, punctuation and a trailing postcode are normalised.
Partial match where the supplied address is the start of the canonical address, or vice versa.
Token match where every supplied address term is present in one candidate.

If one candidate remains, the API returns its canonical address. If several candidates remain, the API returns 409 ADDRESS_AMBIGUOUS with up to 10 candidates.

Billing details in the response

Successful chargeable JSON responses include a top-level billing object. The endpoint examples on this page focus on the endpoint-specific data, so this repeated block may not be shown in every example.

"billing": {
  "mode": "prepaid",
  "creditsCharged": 1,
  "creditsRemaining": 1999,
  "creditsRefreshAt": "2026-08-14T09:30:00.000Z"
}

Field or header	Meaning
billing.creditsCharged X-Credits-Charged	Credits charged by this call. Failed and non-chargeable calls return `0` in the header.
billing.creditsRemaining X-Credits-Remaining	The credit balance after the call.
billing.creditsRefreshAt X-Credits-Refresh-At	The next monthly credit refresh as an ISO 8601 timestamp. Trial and non-renewing balances return `null` and omit the header.

All authenticated API-key calls expose the billing headers, including validation errors and zero-credit status or management requests. Only successful chargeable JSON responses add the billing object to the response body.

Response

All values below are fictional examples.

{
  "success": true,
  "data": {
    "uprn": "100000000001",
    "address": "1 EXAMPLE STREET, EXAMPLETON, EX1 2AB",
    "postcode": "EX1 2AB"
  }
}

Examples

These requests use fictional property details.

UPRN to address

curl "https://propertyinsights.co.uk/api/v1/property/address?uprn=100000000001" \
  -H "x-api-key: YOUR_API_KEY"

Address to UPRN

curl "https://propertyinsights.co.uk/api/v1/property/address?address=1%20Example%20Street&postcode=EX1%202AB" \
  -H "x-api-key: YOUR_API_KEY"

Error handling

HTTP	Code	Meaning
400	MISSING_LOOKUP	Neither a UPRN nor an address and postcode pair was supplied.
400	CONFLICTING_LOOKUP_FIELDS	Both lookup directions were supplied in one request.
404	UPRN_NOT_FOUND	The UPRN is not present in the address dataset.
404	ADDRESS_NOT_FOUND	No UPRN matched the supplied address and postcode.
409	ADDRESS_AMBIGUOUS	Several UPRNs match. Candidate addresses and UPRNs are returned.
402	INSUFFICIENT_CREDITS	The API account has fewer than the 35 credits required.
502	ADDRESS_LOOKUP_UNAVAILABLE	The address dataset could not be queried. No credit is deducted.

Ambiguous address response

{
  "success": false,
  "error": {
    "code": "ADDRESS_AMBIGUOUS",
    "message": "More than one UPRN matches this address.",
    "candidates": [
      {
        "uprn": "100000000010",
        "address": "FLAT 1, EXAMPLE HOUSE, EXAMPLE ROAD, EX1 2AB",
        "postcode": "EX1 2AB"
      },
      {
        "uprn": "100000000011",
        "address": "FLAT 2, EXAMPLE HOUSE, EXAMPLE ROAD, EX1 2AB",
        "postcode": "EX1 2AB"
      }
    ]
  }
}