# 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`. ## Essential Elements[​](#essential-elements "Direct link to 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 meet Royal Mail’s clear addressing specifications. These 3 address lines plus the Post Town and Postcode represents all the information needed to reliably identify a premise according to Royal Mail. ### Address Line One[​](#address-line-one "Direct link to Address Line One") `line_1` * 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. ### Address Line Two[​](#address-line-two "Direct link to Address Line Two") `line_2` * Second Address Line. Often contains thoroughfare and locality information. * May be empty. ### Address Line Three[​](#address-line-three "Direct link to Address Line Three") `line_3` * Third address line. * May be empty. ### Post Town[​](#post-town "Direct link to Post Town") `post_town` * 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[​](#postcode "Direct link to Postcode") `postcode` * Correctly formatted postcode. Capitalised and spaced. *** ## Premise Elements[​](#premise-elements "Direct link to 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[​](#building-number "Direct link to Building Number") `building_number` * Number to identify premise on a thoroughfare or dependant thoroughfare. * E.g. `2`, `4`, `8`, `16` ### Building Name[​](#building-name "Direct link to Building Name") `building_name` * Name of residential or commercial premise * E.g. `The Manor`, `1-2`, `A`, `12A`, `K`, `Victoria House` ### Sub Building Name[​](#sub-building-name "Direct link to Sub Building Name") `sub_building_name` * 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` ### Premise[​](#premise "Direct link to Premise") `premise` * 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. * E.g. For a premise with just a number: `2` E.g. For a premise with both a building and sub-building name: `Caretakers Flat, 110-114` * E.g. For a premise with number, building name and sub-building name: `2B The Tower, 27` * This field may be an empty string if all of the premise attributes are empty. In this instance, it means that the premise is identified by its organisation name (including a possible department name) ### PO Box[​](#po-box "Direct link to PO Box") `po_box` * 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 e.g. HK860. * PO Box Numbers are only allocated to Large Users. ### Organisation Name[​](#organisation-name "Direct link to Organisation Name") `organisation_name` * Name of the organisation registered at this address. ### Department Name[​](#department-name "Direct link to Department Name") `department_name` * Used to supplment Organisation Name to identify a department within the organisation. ## Thoroughfare Elements[​](#thoroughfare-elements "Direct link to Thoroughfare Elements") ### Thoroughfare[​](#thoroughfare "Direct link to Thoroughfare") `thoroughfare` * 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. * However, there are some historic instances where a Postcode may contain more than one Thoroughfare. ### Dependant Thoroughfare[​](#dependant-thoroughfare "Direct link to Dependant Thoroughfare") `dependant_thoroughfare` * Used to supplement thoroughfare. * When a thoroughfare name is used twice in the same Post Town, the dependant thoroughfare is added to uniquely identify a delivery point. ## Locality Elements[​](#locality-elements "Direct link to Locality Elements") ### Dependant Locality[​](#dependant-locality "Direct link to Dependant Locality") `dependant_locality` * When the same thoroughfare name reoccurs in a Post town, it may not be possible to make it dependant on a dependant thoroughfare. In this case the thoroughfare is dependant on a locality. For example if we want to find 1 Back Lane in Huddersfield we see that there are three. ### Double Dependant Locality[​](#double-dependant-locality "Direct link to Double Dependant Locality") `double_dependant_locality` * 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. ### Post Town[​](#post-town-1 "Direct link to Post Town") `post_town` * 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[​](#postcode-1 "Direct link to Postcode") `postcode` * Correctly formatted postcode. Capitalised and spaced. ## Administrative Address Elements[​](#administrative-address-elements "Direct link to 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 which 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[​](#county "Direct link to County") `county` * 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 * This is primarily used for those who have a county requirement for legacy addressing systems. However, please take care as it could be empty for a small number of addresses. * May be empty in cases where no administrative, postal or traditional county present. ### Postal County[​](#postal-county "Direct link to Postal County") `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. ### Administrative County[​](#administrative-county "Direct link to Administrative County") `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. * May be empty. ### Traditional County[​](#traditional-county "Direct link to Traditional County") `traditional_county` * Traditional counties are provided by the Association of British Counties. It’s historical data, and can date from the 1800s. ### Administrative District[​](#administrative-district "Direct link to Administrative District") `district` * The current district/unitary authority to which the postcode has been assigned. ### Administrative Ward[​](#administrative-ward "Direct link to Administrative Ward") `ward` * The current administrative/electoral area to which the postcode has been assigned. * May be empty for a small number of addresses. ### Country[​](#country "Direct link to Country") `country` * The country for which the postcode belongs to: * England * Scotland * Wales * Northern Ireland * Channel Islands * Isle of Man * May be empty for a small number of addresses. ## Geolocation[​](#geolocation "Direct link to 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 & Isle of Man based on outward code for the address. ### Longitude[​](#longitude "Direct link to Longitude") `longitude` * The longitude of the postcode (WGS84/ETRS89). Accurate at the postcode level * Can be a positive or negative decimal. E.g. `-0.1283983` * Returns an empty string if no location data is available. Otherwise, a number is returned ### Latitude[​](#latitude "Direct link to Latitude") `latitude` * The latitude of the postcode (WGS84/ETRS89). Accurate at the postcode level * Can be a positive or negative decimal. E.g. `51.5083983` * Returns an empty string if no location data is available. Otherwise a number is returned ### Northings[​](#northings "Direct link to Northings") `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 ### Eastings[​](#eastings "Direct link to Eastings") `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 ## Miscellaneous[​](#miscellaneous "Direct link to Miscellaneous") ### UDPRN[​](#udprn "Direct link to UDPRN") > 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. * See our [UDPRN guide](https://ideal-postcodes.co.uk/guides/udprn) for more information. * Up to 8-digit numeric code. * A new UDPRN is automatically assigned to each new Delivery Point added to PAF. ### UPRN[​](#uprn "Direct link to UPRN") > Unique Property Reference Number `uprn` * [UPRN](https://ideal-postcodes.co.uk/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. * See our [UPRN guide](https://ideal-postcodes.co.uk/guides/uprn) for more information. * 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. ### Postcode Outward Code[​](#postcode-outward-code "Direct link to Postcode Outward Code") `postcode_outward` * 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 Code[​](#postcode-inward-code "Direct link to Postcode Inward Code") `postcode_inward` * The second part of a postcode is known as the inward Code. e.g. The inward code of ID1 1QD is 1QD. * This part is one number followed by two letters. The number identifies the sector in the postal district. The letters then define one or more properties in that sector. ### Postcode Type[​](#postcode-type "Direct link to Postcode Type") `postcode_type` * 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 15 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. ### Small User Organisation Indicator[​](#small-user-organisation-indicator "Direct link to Small User Organisation Indicator") `su_organisation_indicator` * Small User Organisation Indicator can have the values "Y" or space. * A value of "Y" indicates that a Small User Organisation is present at this address. ### Delivery Point Suffix[​](#delivery-point-suffix "Direct link to Delivery Point Suffix") `delivery_point_suffix` * 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. * E.g. `2B` 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. ## Identifying a Commercial Premise[​](#identifying-a-commercial-premise "Direct link to 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[​](#identifying-a-residential-premise "Direct link to Identifying a Residential Premise") A residential premise will have an empty `su_organisation_indicator` (i.e. not `Y`) **and** `postcode_type` of `S`. ## Sizing[​](#sizing "Direct link to 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)