UMPRN

UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.

Lookup a UMPRN

GET /umprn/:umprn

Returns an address identified via its UMPRN.

Query Parameters

Property	Description
`api_key`	Required unless authenticating with Authorization HTTP Header
`filter`	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
`licensee`	Only required if you are using a sublicensed key. This parameter will associate the request with your licensee

Examples

Request

https://api.ideal-postcodes.co.uk/v1/umprn/0?api_key=iddqd

 # Or in your terminal
curl -k -G https://api.ideal-postcodes.co.uk/v1/umprn/0 \
    -d "api_key=iddqd"

Response

{
    "result":{
        "postcode":"ID1 1QD",
        "postcode_inward":"IQD",
        "postcode_outward":"ID1",
        "post_town":"LONDON",
        "dependant_locality":"",
        "double_dependant_locality":"",
        "thoroughfare":"Barons Court Road",
        "dependant_thoroughfare":"",
        "building_number":"2",
        "building_name":"",
        "sub_building_name":"",
        "po_box":"",
        "department_name":"",
        "organisation_name":"",
        "udprn":25962203,
        "umprn" : 923827402,
        "postcode_type":"S",
        "su_organisation_indicator":"",
        "delivery_point_suffix":"1G",
        "line_1":"2 Barons Court Road",
        "line_2":"",
        "line_3":"",
        "premise":"2",
        "county": "Greater London",
        "administrative_county": "",
        "postal_county": "",
        "traditional_county": "Greater London",
        "district": "Hammersmith and Fulham",
        "ward": "North End",
        "country": "England",
        "longitude":-0.208644362766368,
        "latitude":51.4899488390558,
        "eastings":524466,
        "northings":178299
    },
    "code":2000,
    "message":"Success"
}

A single address object is returned in the result attribute.

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 requests will undergo usual authentication and restriction rules (individual and daily lookup limits) to surface any problems you may have during implementation. However, it will not count towards a postcode lookup on your key.

Pricing

Per lookup charges apply. Empty responses are not charged.

Data Source

Royal Mail (Postcode Address File), Ordnance Survey (Code-Point Open).

Documentation