--- title: "Extract Addresses" method: GET path: "/addresses" tags: ["UK"] --- # 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. ## Query parameters - `api_key` string - `query` string - `limit` integer - `page` integer - `filter` string - `lon` number, float - `lat` number, float - `postcode_outward` string - `postcode` string - `postcode_area` string - `postcode_sector` string - `post_town` string - `uprn` integer - `country` string - `postcode_type` string - `su_organisation_indicator` string - `box` string - `bias_postcode_outward` string - `bias_postcode` string - `bias_postcode_area` string - `bias_postcode_sector` string - `bias_post_town` string - `bias_thoroughfare` string - `bias_country` string - `bias_lonlat` string - `tags` string ## Response `200` Success - AddressResponse - `code` 2000, required - `message` 'Success', required - `result` object, required - `hits` union[], required — List of matching addresses - union - PafAddress — Standard UK Address. Also known as a Postcode Address File (PAF) address is defined by Royal Mail and updated on a daily cadence. A PAF Address represents a deliverable endpoint. - `id` string, required — Global unique internally generated identifier for an address - `dataset` 'paf', required — Indicates the provenance of an address - `country_iso` 'GBR' | 'IMN' | 'JEY' | 'GGY', required — 3 letter country code (ISO 3166-1) - `country_iso_2` 'GB' | 'IM' | 'JE' | 'GG', required — 2 letter country code (ISO 3166-1) - `country` 'England' | 'Scotland' | 'Wales' | 'Northern Ireland' | 'Jersey' | 'Guernsey' | 'Isle of Man', required — Full country names (ISO 3166) - `language` 'en', required — Language represented by 2 letter ISO Code (639-1) - `line_1` string, required — 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` string, required — Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` string, required — Third address line. May be empty. - `post_town` string, required — **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` string, required — Correctly formatted postcode. Capitalised and spaced. - `county` string, required — 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` string, required — Short code representing the county or province. May be empty (`""`) - `uprn` string, required — 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` integer, required — 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` union, 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. - string — If premise is not multiple occupancy, this will be an empty string - number — If premise is multiple occupancy, this will be an integer - `postcode_outward` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Number to identify premise on a thoroughfare or dependant thoroughfare. - `building_name` string, required — Name of residential or commercial premise. Examples: - The Manor - 1-2 - A - 12A - K - Victoria House - `sub_building_name` string, required — 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` string, required — 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` string, required — Used to supplment Organisation Name to identify a deparment within the organisation. - `organisation_name` string, required — Used to supplment Organisation Name to identify a deparment within the organisation - `postcode_type` 'S' | 'L' | '', required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` string, required — The current district/unitary authority to which the postcode has been assigned. - `ward` string, required — The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `longitude` union, 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. - string — Empty string `""` if not available - number — Represents longitude - `latitude` union, 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. - string — Empty string `""` if not available - number — Represents latitude - `eastings` union, required — Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). Northern Ireland Eastings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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. - string — Empty string `""` if not available - number — Metres offset east from origin - `northings` union, required — Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid) Northern Ireland Northings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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 - string — Empty string `""` if not available - number — Metres offset north from origin - MrAddress — Subdivision of a Postcode Address File address. Also known as a Multiple Residence or Multiple Occupancy address. A Multiple Residence address does not have its own deliverable endpoint. Instead it relies on the deliverable endpoint of a parent address, where the parent address can be found on the main Postcode Address File. - `id` string, required — Global unique internally generated identifier for an address - `dataset` 'mr', required — Indicates the provenance of an address - `country_iso` 'GBR' | 'IMN' | 'JEY' | 'GGY', required — 3 letter country code (ISO 3166-1) - `country_iso_2` 'GB' | 'IM' | 'JE' | 'GG', required — 2 letter country code (ISO 3166-1) - `country` 'England' | 'Scotland' | 'Wales' | 'Northern Ireland' | 'Jersey' | 'Guernsey' | 'Isle of Man', required — Full country names (ISO 3166) - `language` 'en', required — Language represented by 2 letter ISO Code (639-1) - `line_1` string, required — 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` string, required — Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` string, required — Third address line. May be empty. - `post_town` string, required — **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` string, required — Correctly formatted postcode. Capitalised and spaced. - `county` string, required — 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` string, required — Short code representing the county or province. May be empty (`""`) - `uprn` string, required — 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` integer, required — 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` union, 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. - string — If premise is not multiple occupancy, this will be an empty string - number — If premise is multiple occupancy, this will be an integer - `postcode_outward` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Number to identify premise on a thoroughfare or dependant thoroughfare. - `building_name` string, required — Name of residential or commercial premise. Examples: - The Manor - 1-2 - A - 12A - K - Victoria House - `sub_building_name` string, required — 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` string, required — 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` string, required — Used to supplment Organisation Name to identify a deparment within the organisation. - `organisation_name` string, required — Used to supplment Organisation Name to identify a deparment within the organisation - `postcode_type` 'S' | 'L' | '', required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` string, required — The current district/unitary authority to which the postcode has been assigned. - `ward` string, required — The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `longitude` union, 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. - string — Empty string `""` if not available - number — Represents longitude - `latitude` union, 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. - string — Empty string `""` if not available - number — Represents latitude - `eastings` union, required — Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). Northern Ireland Eastings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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. - string — Empty string `""` if not available - number — Metres offset east from origin - `northings` union, required — Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid) Northern Ireland Northings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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 - string — Empty string `""` if not available - number — Metres offset north from origin - NybAddress — A UK premise under construction and currently not occupied. This dataset is updated by Royal Mail on a monthly cadence. - `id` string, required — Global unique internally generated identifier for an address - `dataset` 'nyb', required — Indicates the provenance of an address - `country_iso` 'GBR' | 'IMN' | 'JEY' | 'GGY', required — 3 letter country code (ISO 3166-1) - `country_iso_2` 'GB' | 'IM' | 'JE' | 'GG', required — 2 letter country code (ISO 3166-1) - `country` 'England' | 'Scotland' | 'Wales' | 'Northern Ireland' | 'Jersey' | 'Guernsey' | 'Isle of Man', required — Full country names (ISO 3166) - `language` 'en', required — Language represented by 2 letter ISO Code (639-1) - `line_1` string, required — 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` string, required — Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` string, required — Third address line. May be empty. - `post_town` string, required — **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` string, required — Correctly formatted postcode. Capitalised and spaced. - `county` string, required — 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` string, required — Short code representing the county or province. May be empty (`""`) - `uprn` string, required — 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` integer, required — 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` union, 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. - string — If premise is not multiple occupancy, this will be an empty string - number — If premise is multiple occupancy, this will be an integer - `postcode_outward` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Number to identify premise on a thoroughfare or dependant thoroughfare. - `building_name` string, required — Name of residential or commercial premise. Examples: - The Manor - 1-2 - A - 12A - K - Victoria House - `sub_building_name` string, required — 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` string, required — 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` string, required — Used to supplment Organisation Name to identify a deparment within the organisation. - `organisation_name` string, required — Used to supplment Organisation Name to identify a deparment within the organisation - `postcode_type` 'S' | 'L' | '', required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` string, required — The current district/unitary authority to which the postcode has been assigned. - `ward` string, required — The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `longitude` union, 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. - string — Empty string `""` if not available - number — Represents longitude - `latitude` union, 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. - string — Empty string `""` if not available - number — Represents latitude - `eastings` union, required — Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). Northern Ireland Eastings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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. - string — Empty string `""` if not available - number — Metres offset east from origin - `northings` union, required — Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid) Northern Ireland Northings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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 - string — Empty string `""` if not available - number — Metres offset north from origin - WelshPafAddress — Welsh language alternative for a PAF Address - `id` string, required — Global unique internally generated identifier for an address - `dataset` 'pafw', required — Indicates the provenance of an address - `country_iso` 'GBR', required — 3 letter country code (ISO 3166-1) - `country_iso_2` 'GB', required — 2 letter country code (ISO 3166-1) - `country` 'Wales', required — Full country names (ISO 3166) - `language` 'cy', required — Language represented by 2 letter ISO Code (639-1) - `line_1` string, required — 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` string, required — Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` string, required — Third address line. May be empty. - `post_town` string, required — **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` string, required — Correctly formatted postcode. Capitalised and spaced. - `county` string, required — 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` string, required — Short code representing the county or province. May be empty (`""`) - `uprn` string, required — 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` integer, required — 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` union, 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. - string — If premise is not multiple occupancy, this will be an empty string - number — If premise is multiple occupancy, this will be an integer - `postcode_outward` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Number to identify premise on a thoroughfare or dependant thoroughfare. - `building_name` string, required — Name of residential or commercial premise. Examples: - The Manor - 1-2 - A - 12A - K - Victoria House - `sub_building_name` string, required — 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` string, required — 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` string, required — Used to supplment Organisation Name to identify a deparment within the organisation. - `organisation_name` string, required — Used to supplment Organisation Name to identify a deparment within the organisation - `postcode_type` 'S' | 'L' | '', required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` string, required — The current district/unitary authority to which the postcode has been assigned. - `ward` string, required — The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `longitude` union, 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. - string — Empty string `""` if not available - number — Represents longitude - `latitude` union, 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. - string — Empty string `""` if not available - number — Represents latitude - `eastings` union, required — Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). Northern Ireland Eastings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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. - string — Empty string `""` if not available - number — Metres offset east from origin - `northings` union, required — Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid) Northern Ireland Northings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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 - string — Empty string `""` if not available - number — Metres offset north from origin - PafAliasAddress — PAF Aliases addresses are alternate ways to present an address already found on PAF. Alias data is information the public chooses to use when addressing mail, but which isn’t actually required for delivery purposes. The Alias data contains records of alternative address details that are included in the address but not necessarily needed for delivery purposes. - `id` string, required — Global unique internally generated identifier for an address - `dataset` 'pafa', required — Indicates the provenance of an address - `country_iso` 'GBR' | 'IMN' | 'JEY' | 'GGY', required — 3 letter country code (ISO 3166-1) - `country_iso_2` 'GB' | 'IM' | 'JE' | 'GG', required — 2 letter country code (ISO 3166-1) - `country` 'England' | 'Scotland' | 'Wales' | 'Northern Ireland' | 'Jersey' | 'Guernsey' | 'Isle of Man', required — Full country names (ISO 3166) - `language` 'en', required — Language represented by 2 letter ISO Code (639-1) - `line_1` string, required — 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` string, required — Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` string, required — Third address line. May be empty. - `post_town` string, required — **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` string, required — Correctly formatted postcode. Capitalised and spaced. - `county` string, required — 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` string, required — Short code representing the county or province. May be empty (`""`) - `uprn` string, required — 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` integer, required — 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` union, 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. - string — If premise is not multiple occupancy, this will be an empty string - number — If premise is multiple occupancy, this will be an integer - `postcode_outward` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Number to identify premise on a thoroughfare or dependant thoroughfare. - `building_name` string, required — Name of residential or commercial premise. Examples: - The Manor - 1-2 - A - 12A - K - Victoria House - `sub_building_name` string, required — 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` string, required — 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` string, required — Used to supplment Organisation Name to identify a deparment within the organisation. - `organisation_name` string, required — Used to supplment Organisation Name to identify a deparment within the organisation - `postcode_type` 'S' | 'L' | '', required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` string, required — The current district/unitary authority to which the postcode has been assigned. - `ward` string, required — The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `longitude` union, 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. - string — Empty string `""` if not available - number — Represents longitude - `latitude` union, 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. - string — Empty string `""` if not available - number — Represents latitude - `eastings` union, required — Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). Northern Ireland Eastings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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. - string — Empty string `""` if not available - number — Metres offset east from origin - `northings` union, required — Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid) Northern Ireland Northings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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 - string — Empty string `""` if not available - number — Metres offset north from origin - AbAddress — Address from Ordnance Survey AddressBase Core dataset. Please contact us to have this enabled on your account. All AddressBase Core address have a UPRN and a rooftop geolocation available however they may not have a UDPRN. - `id` string, required — Global unique internally generated identifier for an address - `dataset` 'ab', required — Indicates the provenance of an address - `country_iso` 'GBR', required — 3 letter country code (ISO 3166-1) - `country_iso_2` 'GB', required — 2 letter country code (ISO 3166-1) - `country` 'England' | 'Scotland' | 'Wales', required — Full country names (ISO 3166) - `language` 'en', required — Language represented by 2 letter ISO Code (639-1) - `line_1` string, required — 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` string, required — Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` string, required — Third address line. May be empty. - `post_town` string, required — **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` string, required — Correctly formatted postcode. Capitalised and spaced. - `county` string, required — 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` string, required — Short code representing the county or province. May be empty (`""`) - `uprn` string, required — 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` integer, required — 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` union, 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. - string — If premise is not multiple occupancy, this will be an empty string - number — If premise is multiple occupancy, this will be an integer - `postcode_outward` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Number to identify premise on a thoroughfare or dependant thoroughfare. - `building_name` string, required — Name of residential or commercial premise. Examples: - The Manor - 1-2 - A - 12A - K - Victoria House - `sub_building_name` string, required — 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` string, required — 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` string, required — Used to supplment Organisation Name to identify a deparment within the organisation. - `organisation_name` string, required — Used to supplment Organisation Name to identify a deparment within the organisation - `postcode_type` '', required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — 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` string, required — Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `district` string, required — The current district/unitary authority to which the postcode has been assigned. - `ward` string, required — The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `longitude` union, 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. - string — Empty string `""` if not available - number — Represents longitude - `latitude` union, 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. - string — Empty string `""` if not available - number — Represents latitude - `eastings` union, required — Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid). Northern Ireland Eastings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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. - string — Empty string `""` if not available - number — Metres offset east from origin - `northings` union, required — Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid) Northern Ireland Northings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/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 - string — Empty string `""` if not available - number — Metres offset north from origin - `native` AddressBaseCore, required — Represents a GB address in Ordnance Survey's AddressBase Core dataset - `id` string, required — Global unique internally generated identifier for an address - `dataset` 'ab', required — Indicates the provenance of an address - `language` 'en' | 'ar' | 'as' | 'az' | 'be' | 'bg' | 'bn' | 'bs' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fi' | 'fo' | 'fr' | 'ga' | 'gl' | 'gn' | 'he' | 'hi' | 'hr' | 'hu' | 'hy' | 'id' | 'is' | 'it' | 'ja' | 'ka' | 'kk' | 'km' | 'kn' | 'ko' | 'lt' | 'lv' | 'mk' | 'mn' | 'ms' | 'mt' | 'my' | 'nl' | 'no' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'sq' | 'sr' | 'sv' | 'ta' | 'th' | 'tr' | 'uk' | 'uz' | 'vi' | 'wa' | 'zh', required — Language represented by 2 letter ISO Code (639-1) - `line_1` string, required — 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` string, required — Second Address Line. Often contains thoroughfare and locality information. May be empty - `line_3` string, required — Third address line. May be empty. - `premise` string, required — 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. - `uprn` string, required — Unique Property Reference Number (UPRN) assigned by the LLPG Custodian or Ordnance Survey. - `udprn` number, required — Royal Mail's Unique Delivery Point Reference Number (UDPRN). - `parent_uprn` string, required — UPRN of the parent Record if a parent-child relationship exists. - `usrn` number, required — Unique Street Reference Number assigned by the Street Name and Numbering Custodian OR Ordnance Survey depending on the address record. - `toid` string, required — The Topographic Identifier taken from OS MasterMap Topography Layer. This TOID is assigned to the UPRN by performing a spatial intersection between the two identifiers. It consists of the letters 'osgb' and is followed by up to sixteen digits. - `classification_code` string, required — A code that describes the classification of the address record to a maximum of a secondary level. - `eastings` number, required — A value in metres defining the x location in accordance with the British National Grid. - `northings` number, required — A value in metres defining the y location in accordance with the British National Grid. - `latitude` number, required — A value in metres defining the y location in accordance with the British National Grid. - `longitude` number, required — A value defining the Longitude location in accordance with the ETRS89 coordinate reference system. - `single_address_line` string, required — A single attribute containing text concatenation of the address elements separated by a comma. - `street_name` string, required — Street / Road name for the address record. - `locality` string, required — A locality defines an area or geographical identifier within a town, village or hamlet. Locality represents the lower level geographical area. The locality field should be used in conjunction with the town name and street description fields to uniquely identify geographic area where there may be more than one within an administrative area. - `town_name` string, required — Geographical town name assigned by the Local Authority. Please note this can be different from the Post Town value assigned by Royal Mail. - `delivery_point_suffix` string, required — A two-character code uniquely identifying an individual delivery point within a postcode, assigned by Royal Mail. - `post_town` string, required — The town or city in which the Royal Mail sorting office is located which services this address record. Condition: POST_TOWN is not populated if this is the same as TOWN_NAME. - `gss_code` string, required — The Office for National Statistics Governmental Statistical Service (GSS) code representing the contributing Local Authority. - `rpc` number, required — Representative Point Code describes the accuracy of the coordinate that has been allocated to the UPRN as indicated by the Local Authority and enhanced using large scale OS data. - `last_update_date` string, date, required — The latest date on which any of the attributes on this record were last changed. - `island` string, required — Third level of geographic area name to record island names where appropriate. - `change_code` 'I' | 'U' | 'D', required — This enumeration is used in association with the attribute “CHANGE_CODE”. This enumeration identifies the type of change that has been made to a feature. The change type must be set when a feature is inserted, updated or deleted. Please see section 3 for more information. Example I = Insert, U = Update, D = Delete - `building_name` string, required — The building name is a description applied to a single address or a group of addresses. - `building_number` string, required — The building number is a number or range of numbers given to a single address or a group of addresses. - `sub_building` string, required — The sub-building name and/or number for the address record. - `postcode` string, required — A postcode assigned by Royal Mail for the address record. - `po_box` string, required — Text concatenation of 'PO BOX' and the Post Office Box (PO Box) number or 'BFPO' and the British Forces Post Office number. - `organisation` string, required — The organisation name is the business name given, when appropriate, to an address record. - `country` string, required — Full country names (ISO 3166) - `country_iso` string, required — 3 letter country code (ISO 3166-1) - `county` string, required — 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. - `district` string, required — The current district/unitary authority to which the postcode has been assigned. - `ward` string, required — The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. - `traditional_county` string, required — Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. - `administrative_county` string, required — 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` string, required — 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. - `total` integer, required - `limit` integer, required - `page` integer, required ## Other responses - `400` — Bad Request - `404` — Postcode Not Found --- [API](https://skmtc.net/ideal-postcodes/apis/api-reference.md) · [All operations](https://skmtc.net/ideal-postcodes/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ideal-postcodes/api-reference/revisions/295dd3238f22/schema)