Retrieve by UMPRN
Returns a multiple occupancy address identified via its UMPRN (Multiple Residence Unique ID).
UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.
Testing
To test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following
- 0 Returns a successful UMPRN lookup response 2000
- -1 Returns "UMPRN not found", error 4044
- -2 Returns "no lookups remaining", error 4020
- -3 Returns "daily (or individual) lookup limit breached", error 4021
Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.
Pricing
Per lookup charges apply. Empty responses are not charged.
Path parameters
UMPRN to be retrieved
Query parameters
API Key
Your unique identifier that allows access to our APIs.
Begins ak_. Available from your dashboard
Restrict Result Fields
Comma separated whitelist of address elements to return.
E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response
Response
Success
Example response
{
"result": {
"postcode": "CV4 7AL",
"postcode_inward": "7AL",
"postcode_outward": "CV4",
"post_town": "Coventry",
"dependant_locality": "",
"double_dependant_locality": "",
"thoroughfare": "Gibbet Hill Road",
"dependant_thoroughfare": "",
"building_number": "",
"building_name": "Block 1 Arthur Vick",
"sub_building_name": "Room 249a",
"po_box": "",
"department_name": "",
"organisation_name": "",
"udprn": 5770157,
"postcode_type": "S",
"su_organisation_indicator": "",
"delivery_point_suffix": "1A",
"line_1": "Room 249a, Block 1 Arthur Vick",
"line_2": "Gibbet Hill Road",
"line_3": "",
"premise": "Room 249a, Block 1 Arthur Vick",
"longitude": -1.5648072,
"latitude": 52.3858227,
"eastings": 429716,
"northings": 276509,
"country": "England",
"traditional_county": "Warwickshire",
"administrative_county": "",
"postal_county": "West Midlands",
"county": "West Midlands",
"district": "Coventry",
"ward": "Wainbody",
"uprn": "200001572050",
"id": "mr_50906058",
"country_iso": "GBR",
"country_iso_2": "GB",
"county_code": "",
"language": "en",
"umprn": 50906058,
"dataset": "mr"
},
"code": 2000,
"message": "Success"
}