Skip to main content

Extract Addresses

GET 
/addresses

Extract a list of complete 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 passed as a result. Note, in these cases, limit and page parameters are ignored.

This API is designed as a multi-purpose tool for generating address lists, cleansing and wholesale data extraction according to specific parameters.

For address autocomplete, see our address finder API - which is designed for speed and address completion.

Reverse Geocoding​

Return a list of addresses around a point using the lon= and lat= querystring arguments. Addresses will be sorted in order of distance to the point. The search radius is 100m.

Filters​

You can strictly narrow your result by adding filters to your query string which correspond with an address attribute.

For instance, you can restrict to postcode SW1A 2AA by appending postcode=sw1a2aa.

If a filter term is invalid, e.g. postcode=SW1A2AAA, then an empty result set is returned and no lookup is incurred.

You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: postcode_outward=e1,e2,e3. Multiple terms are OR'ed, i.e. the matching result sets are combined.

All filters can accept multiple terms unless stated otherwise below.

Multiple filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: su_organisation_indicator=Y&postcode_area=n. Multiple filters are AND'ed, i.e. each additional filter narrows the result set.

A combined maximum of 5 terms are allowed across all filters.

Biases​

You can boost certain addresses results that correspond with a certain address attribute. All bias searches are prefixed with bias_.

Biased searches, unlike filtered searches, also allow unmatched addresses to appear . These will rank lower.

For instance, you can boost addresses with postcode areas SW and SE by appending bias_postcode_area=SW,SE.

If a bias term is invalid, e.g. bias_postcode=SW1A2AAA no bias effect is applied.

You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: bias_postcode_outward=e1,e2,e3.

All biases can accept multiple terms unless stated otherwise below.

A combined maximum of 5 terms are allowed across all biases.

Search by Postcode and Building Name or Number​

Search by postcode and building attribute with the postcode filter and query argument. E.g. For "SW1A 2AA Prime Minister" /v1/addresses?postcode=sw1a2aa&q=prime minister.

The advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned.

Search By UPRN​

Search by UPRN using the uprn filter and excluding the query argument. E.g. /v1/addresses?uprn=100.

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 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.

Request​

Query Parameters

    api_key string

    API Key

    Your unique identifier that allows access to our APIs.

    Begins ak_. Available from your dashboard

    Example: ak_test
    query string

    Specifies the address you wish to query.

    limit int32

    Possible values: >= 1 and <= 100

    Default value: 10

    Limit

    Specifies the maximum number of records to retrieve.

    By default the limit is 10. Requesting a larger result set will result in more latency

    Example: 5
    page int32

    Possible values: <= 100

    Page

    0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0.

    A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).

    Example: 1
    filter string

    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

    Example: line_1,line_2,line_3
    lon float

    Possible values: >= -180 and <= 180

    Longitude

    Longitude query for reverse geocoding.

    An accompanying latitude (lat=) query must be submitted for a valid reverse geocode query.

    Example: -0.12767
    lat float

    Possible values: >= -90 and <= 90

    Latitude

    Latitude query for reverse geocoding.

    An accompanying longitude (lon=) query must be submitted for a valid reverse geocode query.

    Example: 51.503541
    postcode_outward string

    Filter by Outward Code

    Restrict result set to addresses with a matching outward code.

    The outward code is the first half of a postcode. E.g. the outward code for SW1A 2AA is SW1A.

    Example: SW1A
    postcode string

    Filter by postcode Restrict result set to matching postcodes only. Can be combined with query to perform a postcode and building number or name search.

    Example: SW1A 2AA
    postcode_area string

    Filter by Postcode Area

    Postcode area represents the first one or two non-numeric characters of a postcode. E.g. the postcode area of SW1A 2AA is SW.

    Can be combined with query to perform a postcode and building search.

    Example: SW
    postcode_sector string

    Filter by Postcode Sector

    Postcode sector is the outward code plus first numeric of the inward code. E.g. postcode sector of SW1A 2AA is SW1A 2

    Example: SW1A 2
    post_town string

    Filter by Town or City

    Restrict addresses to matching town, city or other locality identifier.

    Example: London
    uprn integer

    Filter by UPRN

    Does not accept comma separated terms. Only a single term is permitted

    Example: 100023336956
    country string

    Filter by country

    Filters by country name.

    In the context of GBR, country values are not United Kingdom. Instead they are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.

    Example: England
    postcode_type string

    Filter by Postcode Type

    Filter by Postcode Type. Useful for separating organisational and residential addresses

    su_organisation_indicator string

    Filter by Organisation Indicator

    Useful for separating organisational and residential addresses

    Example: Y
    box string

    Filter by Bounding Box

    Restrict search to a geospatial box determined by the "top-left" and "bottom-right" gelocations.
    Only one geospatial box can be provided.

    Example: 2.095,57.15,-2.096,57.14
    bias_postcode_outward string

    Bias by Outward Code Boosts addresses with a matching outward code. Outward code is the first have of a postcode. For instance, the outward code of SW1A 2AA is SW1A

    Example: SW1A
    bias_postcode string

    Bias by postcode Boost addresses which match postcode. Can be combined with query to perform a postcode and building number or name search.

    Example: SW1A2AA
    bias_postcode_area string

    Bias by Postcode Area

    Boosts if the first one or two non-numeric characters of a postcode match

    The postcode area of SW1A 2AA and N1 6RT are SW and N respectively

    Example: SW
    bias_postcode_sector string

    Bias by Postcode Sector

    Boost postcode sector matches. The postcode sector comprises the outward code plus first numeric of the inward code.

    Example: SW1A 2
    bias_post_town string

    Bias by Town or City

    Biases results to matching town, city or other locality name.

    bias_thoroughfare string

    Bias by Street

    Bias by street or thoroughfare name.

    bias_country string

    Bias by Country

    Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.

    bias_lonlat string

    Bias by Geolocation

    Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is 50000. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres] Only one geospatial bias may be provided

    Example: -2.095,57.15,100
    Tags string

    A comma separated list of tags to query over.

    Useful if you want to specify the circumstances in which the request was made.

    If multiple tags are specified, the response will only comprise of requests for which all the tags are satisfied - i.e. searching "foo,bar" will only query requests which tagged both "foo" and "bar".

    Example: foo,bar

Responses​

Success

Schema
    code int32required

    Possible values: [2000]

    message stringrequired

    Possible values: [Success]

    result objectrequired
    hits object[]required

    List of matching addresses

  • Array [
    • oneOf
    id IDrequired

    Global unique internally generated identifier for an address

    dataset Datasetrequired

    Possible values: [paf]

    Indicates the provenance of an address

    country_iso ISO Country Code (3)required

    Possible values: [GBR, IMN, JEY, GGY]

    3 letter country code (ISO 3166-1)

    country_iso_2 ISO Country Code (2)required

    Possible values: [GB, IM, JE, GG]

    2 letter country code (ISO 3166-1)

    country Countryrequired

    Possible values: [England, Scotland, Wales, Northern Ireland, Jersey, Guernsey, Isle of Man]

    Full country names (ISO 3166)

    language Languagerequired

    Possible values: [en]

    Language represented by 2 letter ISO Code (639-1)

    line_1 Line 1required

    First Address Line. Often contains premise and thoroughfare information. In the case of a commercial premise, the first line is always the full name of the registered organisation. Never empty.

    line_2 Line 2required

    Second Address Line. Often contains thoroughfare and locality information. May be empty

    line_3 Line 3required

    Third address line. May be empty.

    post_town paf_post_townrequired

    Possible values: <= 30 characters

    **Filter by Town or City" A Post Town is mandatory for delivery of mail to a Delivery Point. This is not necessarily the nearest town geographically, but a routing instruction to the Royal Mail delivery office sorting mail for that Delivery Point. A Post Town will always be present in every address, and for some Localities the Post Town will be the only locality element present.

    postcode Postcoderequired

    Possible values: >= 6 characters and <= 8 characters

    Correctly formatted postcode. Capitalised and spaced.

    county Countyrequired

    Since postal, administrative or traditional counties may not apply to some addresses, the county field is designed to return whatever county data is available. Normally, the postal county is returned. If this is not present, the county field will fall back to the administrative county. If the administrative county is also not present, the county field will fall back to the traditional county. May be empty in cases where no administrative, postal or traditional county present.

    county_code County Coderequired

    Short code representing the county or province. May be empty ("")

    uprn Unique Property Reference Numberrequired

    UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property.

    Up to 12 digits in length.

    Multiple Residence premises currently share the same UPRN as the parent premise.

    May not be available for a small number of Great Britain addresses due to longer update cycles for Ordnance Survey's AddressBase datasets. Returns empty string "" in these instances.

    Although UPRN takes an integer format, we encode and transmit this data as strings. As a 12 digit number, the UPRN can exceed the maximum safe integer Number.MAX_SAFE_INTEGER in most browsers causing this datapoint to be corrupted.

    Take special care when storing UPRN. As a 12 digit identifier, you will need 64 bits to encode every possible UPRN value. This means applications like Excel will corrupt cells containing UPRN values.

    udprn int32required

    UDPRN stands for ‘Unique Delivery Point Reference Number’. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires.

    Up to 8-digit numeric code.

    A new UDPRN is automatically assigned to each new Delivery Point added to PAF.

    umprn object required

    A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant.

    Note: this will be an empty string "" when not used.

    oneOf

    string

    postcode_outward Postcode Outwardrequired

    Possible values: >= 2 characters and <= 4 characters

    The first part of a postcode is known as the outward code. e.g. The outward code of ID1 1QD is ID1. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. ‘PO1’, ‘SW1A’ or ‘B23’.

    postcode_inward Postcode Inwardrequired

    Possible values: >= 3 characters and <= 3 characters

    The second part of a postcode is known as the inward code. e.g. The inward code of ID1 1QD is 1QD.

    The number identifies the sector in the postal district. The number is followed by 2 letters. The letters then define one or more properties in that sector.

    dependant_locality Dependant Localityrequired

    Possible values: <= 35 characters

    When the same thoroughfare name reoccurs in a Post town, it may not be possible to make it dependant on a dependant thoroughfare. In this case the thoroughfare is dependant on a locality. For example if we want to find 1 Back Lane in Huddersfield we see that there are three.

    double_dependant_locality Double Dependant Localityrequired

    Possible values: <= 35 characters

    Used to supplement Dependant Locality. A Double Dependant Locality supplied along with a Dependant Locality if the Dependant Locality exists twice in the same locality.

    thoroughfare Thoroughfarerequired

    Possible values: <= 80 characters

    Also known as the street or road name. In general each Thoroughfare Name will have a separate Postcode. Longer Thoroughfares with high number ranges often have multiple Postcodes covering the entire length of the road, with breaks at suitable points e.g. junctions or natural breaks in the road.

    dependant_thoroughfare Dependant Thoroughfarerequired

    Possible values: <= 80 characters

    Used to supplement thoroughfare. When a thoroughfare name is used twice in the same Post Town, the dependant thoroughfare is added to uniquely indentify a delivery point.

    building_number Building Numberrequired

    Possible values: <= 4 characters

    Number to identify premise on a thoroughfare or dependant thoroughfare.

    building_name Building Namerequired

    Possible values: <= 50 characters

    Name of residential or commercial premise.

    Examples:

    • The Manor
    • 1-2
    • A
    • 12A
    • K
    • Victoria House
    sub_building_name Sub-Building Namerequired

    Possible values: <= 30 characters

    When a premise is split into individual units such as flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B

    po_box PO Boxrequired

    Possible values: <= 6 characters

    When the PO Box Number field is populated it will contain PO BOX nnnnnn where n represents the PO Box number. Note that the PO Box details can occasionally consist of a combination of numbers and letters. PO Box Numbers are only allocated to Large Users.

    department_name Department Namerequired

    Possible values: <= 60 characters

    Used to supplment Organisation Name to identify a deparment within the organisation.

    organisation_name Organisation Namerequired

    Possible values: <= 60 characters

    Used to supplment Organisation Name to identify a deparment within the organisation

    postcode_type Postcode Typerequired

    Possible values: [S, L, ``]

    This indicates the type of user. It can only take the values 'S' or 'L' indicating small or large respectively. Large User Postcodes. These are assigned to one single address either due to the large volume of mail received at that address, or because a PO Box or Selectapost service has been set up. Small User Postcodes. These identify a group of Delivery Points.

    On average there are 19 Delivery Points per Postcode. However this can vary between 1 and, in some cases, 100. There will never be more than 100 Delivery Points on a Postcode.

    su_organisation_indicator Small User Organisation Indicatorrequired

    Small User Organisation Indicator can have the values 'Y' or space. A value of 'Y' indicates that a Small User Organisation is present at this address.

    delivery_point_suffix Delivery Point Suffixrequired

    A unique Royal Mail 2-character code (the first numeric & the second alphabetical), which, when added to the Postcode, enables each live Delivery Point to be uniquely identified. Once the Delivery Point is deleted from PAF the DPS may be reused (although they aren’t reused until all remaining Delivery Points in the range have been allocated). The DPS for a Large User is always '1A' as each Large User has its own Postcode.

    premise Premiserequired

    Possible values: <= 84 characters

    A pre-computed string which sensibly combines building_number, building_name and sub_building_name. building_number, building_name and sub_building_name represent raw data from Royal Mail's and can be difficult to parse if you are unaware of how the Postcode Address File premise fields work together. For this reason, we also provide a pre-computed premise field which intelligently gathers these points into a single, simple premise string. This field is ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data.

    administrative_county Administrative Countyrequired

    The current administrative county to which the postcode has been assigned.

    A Unitary Authority name, where one is present. If there is no Unitary Authority, the County name is used. This information is not static, because County boundaries may change due to administrative changes. Data

    source: ONS

    postal_county Postal Countyrequired

    Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty.

    traditional_county Traditional Countyrequired

    Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.

    district Districtrequired

    The current district/unitary authority to which the postcode has been assigned.

    ward Wardrequired

    The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.

    longitude object required

    The longitude of the postcode (WGS84/ETRS89).

    Can be a positive or negative decimal. E.g. -0.1283983

    Returns an empty string if no location data is available.

    oneOf

    string

    latitude object required

    The latitude of the postcode (WGS84/ETRS89).

    Can be a positive or negative decimal. E.g. 51.5083983.

    Returns an empty string if no location data is available.

    oneOf

    string

    eastings object required

    Eastings reference using the Ordnance Survey National Grid reference system.

    Northern Ireland Eastings uses the Irish Grid Reference System.

    Metres from origin. E.g. 550458

    Returns an empty string if no location data is available. Otherwise a number is returned.

    oneOf

    string

    northings object required

    Northings reference using the Ordnance Survey National Grid reference system

    Northern Ireland Northings uses the Irish Grid Reference System

    Metres from origin. E.g. 180458

    Returns an empty string if no location data is available. Otherwise a number is returned

    oneOf

    string

  • ]
    • total int32required

    Possible values: <= 10000

    limit int32required

    Possible values: <= 100

    Default value: 10

    page int32required

    Possible values: <= 10

Loading...