Documentation

Addresses

An address instance resource represents a single UK address.


Address Search

GET /addresses?query=

Returns a list of addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).

If a valid postcode is passed as the query string, the entire address list for that postcode is returned as the result. Note, in these cases, limit parameter is ignored and fixed at 100. If your key is configured to return Multiple Residence data, you may need to query more pages to return the entire list as more than 100 delivery points or residences may be returned.

Query Parameters

Property Description
api_key Required unless authenticating with Authorization HTTP Header
query Required. Specifies the address you wish to query. Query can be shortened to q=
limit Specifies the upper limit on the number of address results to be returned. Max is 100 addresses. Query can be shortened to l=
page Specifies the page of results to be returned. Query can be shortened to p=
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
postcode_outward Comma separated list of outward codes with which to restrict result set. E.g. postcode_outward=sw1a, postcode_outward=tr8,le18
licensee Only required if you are using a sublicensed key. This parameter will associate the request with your licensee

Request

https://api.ideal-postcodes.co.uk/v1/addresses?api_key=iddqd&query=10%20downing%20street%20london
 # Or in your terminal
curl -k -G 'https://api.ideal-postcodes.co.uk/v1/addresses' \
    -d 'api_key=iddqd' \
    --data-urlencode 'query=10 downing street london'

Response

{
    "result":{
        "total":2,
        "limit":10,
        "page":0,
        "hits":[
            {
                "dependant_locality" : "",
                "postcode_type" : "L",
                "po_box" : "",
                "post_town" : "LONDON",
                "delivery_point_suffix" : "1A",
                "double_dependant_locality" : "",
                "su_organisation_indicator" : " ",
                "longitude" : -0.127695242183412,
                "department_name" : "",
                "district" : "Westminster",
                "building_name" : "",
                "dependant_thoroughfare" : "",
                "northings" : 179951,
                "premise" : "10",
                "postcode_outward" : "SW1A",
                "postcode_inward" : "2AA",
                "sub_building_name" : "",
                "eastings" : 530047,
                "postcode" : "SW1A 2AA",
                "country" : "England",
                "udprn" : 23747771,
                "umprn" : "",
                "line_3" : "",
                "organisation_name" : "Prime Minister & First Lord Of The Treasury",
                "ward" : "St James's",
                "line_1" : "Prime Minister & First Lord Of The Treasury",
                "building_number" : "10",
                "thoroughfare" : "Downing Street",
                "traditional_county": "Greater London",
                "administrative_county": "City of Westminster",
                "postal_county": "",
                "county": "City of Westminster",
                "line_2" : "10 Downing Street",
                "latitude" : 51.5035398826274
            }, {
                "dependant_locality" : "",
                "postcode_type" : "S",
                "po_box" : "",
                "post_town" : "LONDON",
                "delivery_point_suffix" : "1B",
                "double_dependant_locality" : "",
                "su_organisation_indicator" : " ",
                "longitude" : -0.122624730080001,
                "department_name" : "",
                "district" : "Camden",
                "building_name" : "Downing Court",
                "dependant_thoroughfare" : "",
                "northings" : 182178,
                "premise" : "Flat 10, Downing Court",
                "postcode_outward" : "WC1N",
                "postcode_inward" : "1LX",
                "sub_building_name" : "Flat 10",
                "eastings" : 530342,
                "postcode" : "WC1N 1LX",
                "country" : "England",
                "udprn" : 26245117,
                "umprn" : "",
                "line_3" : "Grenville Street",
                "organisation_name" : "",
                "ward" : "Bloomsbury",
                "county" : "",
                "traditional_county": "",
                "administrative_county": "",
                "postal_county": "",
                "line_1" : "Flat 10",
                "building_number" : " ",
                "thoroughfare" : "Grenville Street",
                "line_2" : "Downing Court",
                "latitude" : 51.5234851731108
            }
        ]
    },
    "code":2000,
    "message":"Success"
}

The result object contains the following attributes.

  • total The total number of addresses matching your search query.
  • limit The maximum number of addresses returned by this request.
  • page The current page number of results. If the total number of addresses exceeds the limit, there will be total / limit pages you can search through.
  • hits An array of address objects ordered by search relevance.

Testing

  • ID1 1QD Returns a successful query response 2000
  • ID1 KFA Returns an empty query response 2000
  • ID1 CLIP Returns "no lookups remaining" error 4020
  • ID1 CHOP 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.

Notes

This is not an address autocomplete method. Each request that returns an address is incurs a lookup charge.

If a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.

Pricing

Per lookup charges apply. Queries which find no match are not charged.

Data Source

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


UDPRN (Address ID) to Address

GET /addresses/:udprn

Returns an address identified via its Unique Delivery Point Reference Number (UDPRN).

UDPRNs are an eight digit unique numeric code (e.g. 25962203) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database.

You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a "decommissioned" address.

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/addresses/0?api_key=iddqd
 # Or in your terminal
curl -k -G https://api.ideal-postcodes.co.uk/v1/addresses/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" : "",
        "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 UDPRNs that yield both successful and unsuccessful responses to your request. They are the following

  • 0 Returns a successful UDPRN lookup response 2000
  • -1 Returns "UDPRN 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)


Address Model Overview

The Address Model or Object has the following attributes.