# Standard UK Address Our APIs return all data contained in Royal Mail's Postcode Address File. Postcode Address File dataset results are labeled with `paf`. ## Example Record | Field | Example | Type | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------- | -------- | | [Address Identifier `id`](#address-identifier) | paf\_23747771 | `string` | | [Dataset `dataset`](#dataset) | paf | `string` | | [ISO Country Code (3) `country_iso`](#iso-country-code-3) | GBR | `string` | | [ISO Country Code (2) `country_iso_2`](#iso-country-code-2) | GB | `string` | | [Country `country`](#country) | England | `string` | | [Language `language`](#language) | en | `string` | | [Postcode `postcode`](#postcode) | SW1A 2AA | `string` | | [Postcode Inward `postcode_inward`](#postcode-inward) | 2AA | `string` | | [Postcode Outward `postcode_outward`](#postcode-outward) | SW1A | `string` | | [Post Town `post_town`](#post-town) | London | `string` | | [Dependant Locality `dependant_locality`](#dependant-locality) | Empty in this example | `string` | | [Double Dependant Locality `double_dependant_locality`](#double-dependant-locality) | Empty in this example | `string` | | [Thoroughfare `thoroughfare`](#thoroughfare) | Downing Street | `string` | | [Dependant Thoroughfare `dependant_thoroughfare`](#dependant-thoroughfare) | Empty in this example | `string` | | [Building Number `building_number`](#building-number) | 10 | `string` | | [Building Name `building_name`](#building-name) | Empty in this example | `string` | | [Sub-Building Name `sub_building_name`](#sub-building-name) | Empty in this example | `string` | | [PO Box `po_box`](#po-box) | Empty in this example | `string` | | [Department Name `department_name`](#department-name) | Empty in this example | `string` | | [Organisation Name `organisation_name`](#organisation-name) | Prime Minister & First Lord Of The Treasury | `string` | | [Unique Delivery Point Reference Number (UDPRN) `udprn`](#unique-delivery-point-reference-number-udprn) | `23747771` | `number` | | [UMPRN `umprn`](#umprn) | Empty in this example | `string` | | [Unique Property Reference Number `uprn`](#unique-property-reference-number) | 100023336956 | `string` | | [Postcode Type `postcode_type`](#postcode-type) | S | `string` | | [Small User Organisation Indicator `su_organisation_indicator`](#small-user-organisation-indicator) | Empty in this example | `string` | | [Delivery Point Suffix `delivery_point_suffix`](#delivery-point-suffix) | 1A | `string` | | [Line 1 `line_1`](#line-1) | Prime Minister & First Lord Of The Treasury | `string` | | [Line 2 `line_2`](#line-2) | 10 Downing Street | `string` | | [Line 3 `line_3`](#line-3) | Empty in this example | `string` | | [Premise `premise`](#premise) | 10 | `string` | | [Longitude `longitude`](#longitude) | `-0.12767` | `number` | | [Latitude `latitude`](#latitude) | `51.503541` | `number` | | [Eastings `eastings`](#eastings) | `530047` | `number` | | [Northings `northings`](#northings) | `179951` | `number` | | [County `county`](#county) | London | `string` | | [County Code `county_code`](#county-code) | Empty in this example | `string` | | [Traditional County `traditional_county`](#traditional-county) | Greater London | `string` | | [Administrative County `administrative_county`](#administrative-county) | Empty in this example | `string` | | [Postal County `postal_county`](#postal-county) | London | `string` | | [District `district`](#district) | Westminster | `string` | | [Ward `ward`](#ward) | St. James's | `string` | | [Native Record `native`](#native-record) | `{ 17 fields }` | `object` | ```json { "id": "paf_23747771", "dataset": "paf", "country_iso": "GBR", "country_iso_2": "GB", "country": "England", "language": "en", "postcode": "SW1A 2AA", "postcode_inward": "2AA", "postcode_outward": "SW1A", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "umprn": "", "uprn": "100023336956", "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A", "line_1": "Prime Minister & First Lord Of The Treasury", "line_2": "10 Downing Street", "line_3": "", "premise": "10", "longitude": -0.12767, "latitude": 51.503541, "eastings": 530047, "northings": 179951, "county": "London", "county_code": "", "traditional_county": "Greater London", "administrative_county": "", "postal_county": "London", "district": "Westminster", "ward": "St. James's", "native": { "dataset": "paf", "postcode": "SW1A 2AA", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A" } } ``` Every field is documented below. ## Essential Elements With each address lookup, the API will automatically aggregate all the available addressing information for any given premise into a reliable 3 lined address format which meets Royal Mail's clear addressing specifications. These 3 address lines plus the Post Town and Postcode represent all the information needed to reliably identify a premise according to Royal Mail. * `line_1` string Line 1 First address line. Often contains premise and thoroughfare information. For a commercial premise the first line is the full name of the registered organisation. Never empty. Example: `Prime Minister & First Lord Of The Treasury` * `line_2` string Line 2 Second address line. Often contains thoroughfare and locality information. May be empty. Example: `10 Downing Street` * `line_3` string Line 3 Third address line. Takes the address elements left after `line_1` and `line_2` are filled; where the address needs more than three lines the remaining elements are joined into `line_3`, comma separated. May be empty. Example: Empty in this example * `post_town` string Post Town The town or city used to route mail to the address. For UK addresses this is the Royal Mail post town, which is a routing instruction rather than the nearest town geographically. Present on every address. Example: `London` * `postcode` string Postcode Correctly formatted postcode. Capitalised and spaced. Empty (`""`) where the address has no postcode. Example: `SW1A 2AA` ## Premise Elements These elements identify a specific premise. A combination of building number, building name and sub-building fields may be present. We also provide a pre-computed premise field if you are unaware of how premise elements are combined. * `building_number` string Building Number Number identifying the premise on a thoroughfare or dependant thoroughfare. May be empty. Example: `10` * `building_name` string Building Name Name of a residential or commercial premise. May be empty. Examples: * The Manor * 1-2 * A * 12A * K * Victoria House Example: Empty in this example * `sub_building_name` string Sub-Building Name Identifies a unit where a premise is split into flats, apartments or business units. Cannot be present without either building\_name or building\_number. E.g. Flat 1, A, 10B. May be empty. Example: Empty in this example * `premise` string Premise A pre-computed string which sensibly combines building\_number, building\_name and sub\_building\_name. Those three fields hold raw dataset values and can be difficult to parse if you are unaware of how they work together, so we also provide this single, simple premise string. Ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data. Example: `10` * `po_box` string PO Box PO Box number for the address, occasionally a combination of numbers and letters. Allocated to Large User postcodes only. May be empty. Example: Empty in this example * `organisation_name` string Organisation Name Name of the business or organisation at this address. May be empty. Example: `Prime Minister & First Lord Of The Treasury` * `department_name` string Department Name Supplements organisation name to identify a department within the organisation. May be empty. Example: Empty in this example ## Thoroughfare Elements * `thoroughfare` string Thoroughfare Also known as the street or road name. May be empty. Example: `Downing Street` * `dependant_thoroughfare` string Dependant Thoroughfare Supplements thoroughfare. Used where a thoroughfare name occurs twice in the same post town, to identify the address uniquely. May be empty. Example: Empty in this example ## Locality Elements * `dependant_locality` string Dependant Locality A locality that qualifies the thoroughfare. Used where the same thoroughfare name occurs more than once in a post town and no dependant thoroughfare distinguishes them. May be empty. Example: Empty in this example * `double_dependant_locality` string Double Dependant Locality Supplements dependant locality. Supplied where the dependant locality itself occurs twice in the same locality. May be empty. Example: Empty in this example ## Administrative Address Elements Each address also comes with certain data points regarding its administrative authorities including county, district and ward. Administrative data for postcodes is retrieved using Royal Mail, ONS and Ordnance Survey data. ONS and Ordnance Survey data is released every quarter. A very small percentage of new postcodes (less than 0.1%) will not have this information until the next release. In this scenario, the API will return an empty string. Please note that county data is no longer required to identify an address and we strongly recommend discarding county data altogether. This data is provided primarily for users of legacy systems which require some county data. Since the use of county information has been deprecated for many years, this data can be inaccurate or missing. * `county` string County Whatever county data is available for the address. Normally the postal county. If that is not present it falls back to the administrative county, then to the traditional county. May be empty where none of the three is present. Example: `London` * `postal_county` string Postal County 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. Example: `London` * `administrative_county` string Administrative County 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. Source: ONS. May be empty. Example: Empty in this example * `traditional_county` string Traditional County Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty. Example: `Greater London` * `county_code` string County Code Short code representing the county or province. May be empty (`""`) Example: Empty in this example * `district` string District The current district/unitary authority to which the postcode has been assigned. May be empty. Example: `Westminster` * `ward` string Ward The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses. Example: `St. James's` * `country` string Country Full country names (ISO 3166) Example: `England` Enum: 248 possible values ## Geolocation England, Scotland and Wales geolocation data is accurate to the rooftop level. If `uprn` is not present, it will be accurate to the postcode centroid level only. Northern Ireland geolocation is accurate to postcode centroid level only. A very small percentage of addresses will not have geolocation data either because the premise is new (England, Scotland, Wales) or the data is unavailable (Northern Ireland). High level (approximate) geolocations have been allocated to the Channel Islands and Isle of Man based on outward code for the address. * `longitude` string | number Longitude The longitude of the address or postcode (WGS84). Can be a positive or negative decimal. E.g. -0.1283983 Returns an empty string if no location data is available. Example: `-0.12767` * `latitude` string | number Latitude The latitude of the address or postcode (WGS84). Can be a positive or negative decimal. E.g. `51.5083983`. Returns an empty string if no location data is available. Example: `51.503541` * `northings` string | number Northings 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. Example: `179951` * `eastings` string | number Eastings 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. Example: `530047` ## Identifiers Every address carries a set of identifiers and postcode components alongside the address elements above. * `id` string Address Identifier Global unique internally generated identifier for an address Example: `paf_23747771` * `dataset` string Dataset Indicates the provenance of an address. Example: `paf` Enum: "paf", "pafw", "pafa", "mr", "nyb", "usps", "ecaf", "ecad", "ab", "abp", "herewe", "heret", "heresa", "hereo", "herena", "heremeas", "heremea", "herem", "herei", "herehk", "hereee", "hereap", "gnaf", "kadaster", "kartverket", "sdfi", "cannar", "fodbosa", "mois", "upujp", "bev", "ban", "swt" * `language` string Language Language represented by 2 letter ISO Code (639-1) Example: `en` Enum: 64 possible values * `country_iso` string ISO Country Code (3) 3 letter country code (ISO 3166-1) Example: `GBR` Enum: 243 possible values * `country_iso_2` string ISO Country Code (2) 2 letter country code (ISO 3166-1) Example: `GB` Enum: 243 possible values * `udprn` integer | string Unique Delivery Point Reference Number (UDPRN) 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. Returns `0` on a UK dataset that carries no UDPRN for the address, and an empty string `""` on a non-UK address. Use `id` for an identifier present on every address. Example: `23747771` * `uprn` string Unique Property Reference Number 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, as it does for addresses outside the UK. 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. Example: `100023336956` * `umprn` string | number UMPRN 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. Example: Empty in this example * `postcode_outward` string Postcode Outward The first part of a postcode is known as the outward code. e.g. The outward code of BR8 7RE is BR8. 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'. Empty (`""`) where the address has no UK postcode. Example: `SW1A` * `postcode_inward` string Postcode Inward The second part of a postcode is known as the inward code. e.g. The inward code of BR8 7RE is 7RE. 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. Empty (`""`) where the address has no UK postcode. Example: `2AA` * `postcode_type` string Postcode Type Royal Mail postcode user type. UK addresses only. * `S` small user. The postcode identifies a group of delivery points. There are on average 19 delivery points per postcode, and never more than 100 * `L` large user. The postcode is assigned to a single address, either because of the volume of mail it receives or because a PO Box or Selectapost service is set up Empty (`""`) where not applicable. Example: `S` Enum: "S", "L", "" * `su_organisation_indicator` string Small User Organisation Indicator `Y` where an organisation is present at a small user postcode. Empty (`""`) otherwise. UK addresses only. Example: Empty in this example * `delivery_point_suffix` string Delivery Point Suffix Two-character code (the first numeric, the second alphabetical) which, added to the postcode, uniquely identifies a delivery point. May be reused once a delivery point is deleted, though not until every remaining code in the range has been allocated. Always `1A` for a large user postcode, since each large user has its own postcode. Empty (`""`) where not available. Example: `1A` See our guide on [organisational information on PAF](https://ideal-postcodes.co.uk/guides/organisations) for more information on organisation names, department names, postcode type and small user organisation indicator. ## Native Record * `native` object Native Record The raw dataset record backing an address, exactly as the dataset supplies it. One schema per dataset; `dataset` on the record says which. Raw Royal Mail Postcode Address File record backing a `paf` address. Fields shared by every Royal Mail PAF family native record (`paf`, `mr`, `nyb`, `pafa`, `pafw`). The Royal Mail record as held in Postgres, before any derived fields are added. Formatted lines, `premise`, postcode parts, geocodes, UPRN and county fields belong to the address, not to the native record. `dataset` is the one field not taken from Royal Mail. Two values differ from the raw PAF file: `post_town` is title cased (Royal Mail supplies it upper cased), and a `building_number` of `0`, PAF's sentinel for "none", is returned as an empty string. ### Example Record | Field | Example | Type | | ---------------------------------------------------------------- | ------------------------------------------- | -------- | | [`dataset`](#native-dataset) | paf | `string` | | [`postcode`](#native-postcode) | SW1A 2AA | `string` | | [`post_town`](#native-post_town) | London | `string` | | [`dependant_locality`](#native-dependant_locality) | Empty in this example | `string` | | [`double_dependant_locality`](#native-double_dependant_locality) | Empty in this example | `string` | | [`thoroughfare`](#native-thoroughfare) | Downing Street | `string` | | [`dependant_thoroughfare`](#native-dependant_thoroughfare) | Empty in this example | `string` | | [`building_number`](#native-building_number) | 10 | `string` | | [`building_name`](#native-building_name) | Empty in this example | `string` | | [`sub_building_name`](#native-sub_building_name) | Empty in this example | `string` | | [`po_box`](#native-po_box) | Empty in this example | `string` | | [`department_name`](#native-department_name) | Empty in this example | `string` | | [`organisation_name`](#native-organisation_name) | Prime Minister & First Lord Of The Treasury | `string` | | [`udprn`](#native-udprn) | `23747771` | `number` | | [`postcode_type`](#native-postcode_type) | S | `string` | | [`su_organisation_indicator`](#native-su_organisation_indicator) | Empty in this example | `string` | | [`delivery_point_suffix`](#native-delivery_point_suffix) | 1A | `string` | ```json { "dataset": "paf", "postcode": "SW1A 2AA", "post_town": "London", "dependant_locality": "", "double_dependant_locality": "", "thoroughfare": "Downing Street", "dependant_thoroughfare": "", "building_number": "10", "building_name": "", "sub_building_name": "", "po_box": "", "department_name": "", "organisation_name": "Prime Minister & First Lord Of The Treasury", "udprn": 23747771, "postcode_type": "S", "su_organisation_indicator": "", "delivery_point_suffix": "1A" } ``` Every field is documented below. * `dataset` string Example: `paf` Enum: "paf" * `postcode` string Postcode, space separated Example: `SW1A 2AA` * `post_town` string Royal Mail post town, title cased Example: `London` * `dependant_locality` string Dependant locality. Empty string when not present Example: Empty in this example * `double_dependant_locality` string Double dependant locality. Empty string when not present Example: Empty in this example * `thoroughfare` string Street name Example: `Downing Street` * `dependant_thoroughfare` string Dependant street name. Empty string when not present Example: Empty in this example * `building_number` string Building number. Empty string when not present, or when PAF merges it into the building name Example: `10` * `building_name` string Building name. Empty string when not present Example: Empty in this example * `sub_building_name` string Sub building name. Empty string when not present Example: Empty in this example * `department_name` string Department name within an organisation. Empty string when not present Example: Empty in this example * `organisation_name` string Organisation name. Empty string when not present Example: `Prime Minister & First Lord Of The Treasury` * `udprn` integer Unique Delivery Point Reference Number Example: `23747771` * `postcode_type` string Postcode type. * `S` Small user * `L` Large user * `""` where Royal Mail supplies none Example: `S` Enum: "S", "L", "" * `su_organisation_indicator` string Small user organisation indicator. `Y` where the small user postcode is held by an organisation Example: Empty in this example * `delivery_point_suffix` string Royal Mail delivery point suffix Example: `1A` * `po_box` string PO Box number. Empty string when not present Example: Empty in this example ## Identifying a Commercial Premise A commercial premise (i.e. a business or PO Box) will have an `su_organisation_indicator` value of `Y` **or** `postcode_type` of `L`. A PO Box will always have `postcode_type` of `L`. ## Identifying a Residential Premise A residential premise will have an empty `su_organisation_indicator` (i.e. not `Y`) **and** `postcode_type` of `S`. ## Sizing The column sizes for the address elements used by the PAF dataset are outlined below | Address Elements | Maximum Length | | ----------------------------------- | -------------- | | Sub Building Name | 30 | | Building Name | 50 | | Building Number | 4 | | Organisation Name | 60 | | Department Name | 60 | | PO Box Number | 6 | | Dependant Thoroughfare + Descriptor | 80 | | Thoroughfare Name + Descriptor | 80 | | Double Dependant Locality | 35 | | Dependant Locality | 35 | | Post Town | 30 | | Postcode | 7 | Note that: * `County` data is not available in the Postcode Address File. This datapoint is no longer used to identify a premise in the UK * `Premise` can potentially include sub building name, building name, building number plus comma dividers `", "`. The maximum length of this field is therefore 84 characters (30 + 50 + 4 + 2 + 2) * `Line 1`...`Line 3` can be a wide number of combinations across the above premise attributes as well as thoroughfare, department thoroughfare, locality, double department locality, organisation name and department name. The dynamic range in terms of length is therefore much bigger. We recommend against adding fixed width columns for those fields See the [Programmer's Guide from Royal Mail for more information](https://js.ideal-postcodes.co.uk/guide.pdf)