# Standard Address The standard Ideal Postcodes address, which maps both UK and International addresses. Its fields follow the layout UK address databases typically use, and much of it reflects Royal Mail's Postcode Address File, the UK's primary address database. The API converts non-UK addresses into the same UK layout so international addresses will also seamlessly insert into a standard address database. Despite this mapping fidelity to the source is never compromised with the `native` address field. Pay attention to the address lines (`line_1`, `line_2` and `line_3`), post town, postcode, county and country. Together they are all you need to identify an address uniquely, in the UK or as an international address. For international addresses, cities map to `post_town` and states map to `county`. Every address carries a `native` object: the raw record from its source dataset, exactly as the dataset supplies it, with local detail the standard fields cannot hold. E.g. * ECAD records say whether an address sits in a Gaeltacht (Irish-speaking) district and whether the building is residential or commercial * USPS records carry the carrier route and congressional district * Kadaster records carry the floor area, year of completion and use (residential, office, retail) The postcode and address list endpoints return the older `AddressListItem` shape instead, where `native` is absent for the Royal Mail PAF family. The example below is a UK address from the [Postcode Address File](/docs/data/paf.md). An address from any other [dataset](/docs/data.md) has the same fields, and its `native` record carries that dataset's raw fields. ## Example Record Every row links to the field's full definition on the [Standard UK Address](/docs/data/paf.md) page. | Field | Example | Type | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | -------- | | [Address Identifier `id`](/docs/data/paf.md#address-identifier) | paf\_23747771 | `string` | | [Dataset `dataset`](/docs/data/paf.md#dataset) | paf | `string` | | [ISO Country Code (3) `country_iso`](/docs/data/paf.md#iso-country-code-3) | GBR | `string` | | [ISO Country Code (2) `country_iso_2`](/docs/data/paf.md#iso-country-code-2) | GB | `string` | | [Country `country`](/docs/data/paf.md#country) | England | `string` | | [Language `language`](/docs/data/paf.md#language) | en | `string` | | [Postcode `postcode`](/docs/data/paf.md#postcode) | SW1A 2AA | `string` | | [Postcode Inward `postcode_inward`](/docs/data/paf.md#postcode-inward) | 2AA | `string` | | [Postcode Outward `postcode_outward`](/docs/data/paf.md#postcode-outward) | SW1A | `string` | | [Post Town `post_town`](/docs/data/paf.md#post-town) | London | `string` | | [Dependant Locality `dependant_locality`](/docs/data/paf.md#dependant-locality) | Empty in this example | `string` | | [Double Dependant Locality `double_dependant_locality`](/docs/data/paf.md#double-dependant-locality) | Empty in this example | `string` | | [Thoroughfare `thoroughfare`](/docs/data/paf.md#thoroughfare) | Downing Street | `string` | | [Dependant Thoroughfare `dependant_thoroughfare`](/docs/data/paf.md#dependant-thoroughfare) | Empty in this example | `string` | | [Building Number `building_number`](/docs/data/paf.md#building-number) | 10 | `string` | | [Building Name `building_name`](/docs/data/paf.md#building-name) | Empty in this example | `string` | | [Sub-Building Name `sub_building_name`](/docs/data/paf.md#sub-building-name) | Empty in this example | `string` | | [PO Box `po_box`](/docs/data/paf.md#po-box) | Empty in this example | `string` | | [Department Name `department_name`](/docs/data/paf.md#department-name) | Empty in this example | `string` | | [Organisation Name `organisation_name`](/docs/data/paf.md#organisation-name) | Prime Minister & First Lord Of The Treasury | `string` | | [Unique Delivery Point Reference Number (UDPRN) `udprn`](/docs/data/paf.md#unique-delivery-point-reference-number-udprn) | `23747771` | `number` | | [UMPRN `umprn`](/docs/data/paf.md#umprn) | Empty in this example | `string` | | [Unique Property Reference Number `uprn`](/docs/data/paf.md#unique-property-reference-number) | 100023336956 | `string` | | [Postcode Type `postcode_type`](/docs/data/paf.md#postcode-type) | S | `string` | | [Small User Organisation Indicator `su_organisation_indicator`](/docs/data/paf.md#small-user-organisation-indicator) | Empty in this example | `string` | | [Delivery Point Suffix `delivery_point_suffix`](/docs/data/paf.md#delivery-point-suffix) | 1A | `string` | | [Line 1 `line_1`](/docs/data/paf.md#line-1) | Prime Minister & First Lord Of The Treasury | `string` | | [Line 2 `line_2`](/docs/data/paf.md#line-2) | 10 Downing Street | `string` | | [Line 3 `line_3`](/docs/data/paf.md#line-3) | Empty in this example | `string` | | [Premise `premise`](/docs/data/paf.md#premise) | 10 | `string` | | [Longitude `longitude`](/docs/data/paf.md#longitude) | `-0.12767` | `number` | | [Latitude `latitude`](/docs/data/paf.md#latitude) | `51.503541` | `number` | | [Eastings `eastings`](/docs/data/paf.md#eastings) | `530047` | `number` | | [Northings `northings`](/docs/data/paf.md#northings) | `179951` | `number` | | [County `county`](/docs/data/paf.md#county) | London | `string` | | [County Code `county_code`](/docs/data/paf.md#county-code) | Empty in this example | `string` | | [Traditional County `traditional_county`](/docs/data/paf.md#traditional-county) | Greater London | `string` | | [Administrative County `administrative_county`](/docs/data/paf.md#administrative-county) | Empty in this example | `string` | | [Postal County `postal_county`](/docs/data/paf.md#postal-county) | London | `string` | | [District `district`](/docs/data/paf.md#district) | Westminster | `string` | | [Ward `ward`](/docs/data/paf.md#ward) | St. James's | `string` | | [Native Record `native`](/docs/data/paf.md#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" } } ``` ## Key Elements The fields most integrations read. The [Standard UK Address](/docs/data/paf.md) page documents all 42. ### Address lines Three lines, a post town and a postcode identify a delivery point. `line_1` is never empty. * `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` ### Country * `country` string Country Full country names (ISO 3166) Example: `England` Enum: 248 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 ### Identifiers `id` is unique across every dataset and is what a search result carries. `dataset` says which dataset the address came from. UK addresses also carry Royal Mail's `udprn` and Ordnance Survey's `uprn`. * `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" * `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` ### Geolocation * `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` ### 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. ## Where addresses come from Every address carries `dataset` and `country_iso`. [Supported Countries](/docs/data/supported-countries.md) lists which dataset serves each country and how fine its coverage is; each dataset page documents the `native` record.