Premium Data Sets for Address Capture Integration

As these datasets are covered by separate terms and agreements they will need to be activated on your account for you, please get in touch if you are interested in taking advantage of any of our premium datasets. There are a few approaches you can take in consuming these extra datasets, and which one is appropriate depends on how you want to integrate with the service.

Direct Via the API

Find

Your extra dataset can be activated by us as a setting on the key itself. This means that the selected API key will always return data from the selected dataset. Alternatively, you can use any API key from your account and specify the dataset required via a parameter on the request.

Note: If a premium dataset is requested using an API key from an account that does not have that dataset enabled, the request will fail. Reach out to customer support in case you need assistance.

If the dataset has not been enabled on the key itself, you will need to add the datasets parameter to the Find request. The following example requests the Business dataset be used for this Find request:

https://api.addressy.com/Capture/Interactive/Find/v1.00/csv.ws?Key=AA11-AA11-AA11-AA11&Text=wr5 3da&Datasets=gb_db

The Find request will then continue as normal using the Business data as its dataset. Once the user selects an address from the list you will pass the Id of that address into the retrieve request as per a normal flow.

Retrieve

Each premium dataset contains certain extra fields that are available in addition to the standard fields provided by a Retrieve request. By default, if you use an Id from a premium dataset Find request, the Retrieve will still only return the standard set of fields. In order to retrieve these special fields, you will need to supply field format strings for them into the FieldFormat Parameters of a Retrieve request. These fields are in the style of FieldXFormat, with X being the number of that field. The requested field will then be returned in the corresponding response field, FieldX. A normal field format will be in the style of {FIELDNAME}. For example, in order to retrieve the Company number from the Business dataset you would use the following request:

https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/csv.ws?Key=AA11-AA11-AA11-AA11&Id=IDFROMFIND&Field1Format={CompanyNumber}

This would return the the Company number in the returned property Field1. The Retrieve request is limited to 20 Field Format fields by default. Should you require more fields than this you will need to specify a fields property along with your field formats that will set the number of extra fields to respond with, for example:

https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/csv.ws?Key=AA11-AA11-AA11-AA11&Id=IDFROMFIND&Field1Format={CompanyNumber}......................&Field21Format={TelephoneNumber}&Fields=21

Capture SDK Guide

If you are using our JavaScript SDK to make requests to the service, as outlined in our advanced guide, you can enable premium datasets via the options object used in the construction of the control object, e.g.:

var options = {
    key: 'AA11-AA11-AA11',
    search: {
        datasets: ['gb_db']
    },
    advancedFields: [
        '{CompanyNumber}'
    ]
}

The same restrictions apply to the datasets as apply when directly integrating via API.

Using the simple setup

If you are using our simple setup wizard to install your lookup control you can specify the field formats directly in the field mapping control using the field format syntax, {FIELDFORMAT}.

Utilities Standard/Premium

Field	Description
`UDPRN`	8-digit unique numeric identifier assigned by Royal Mail to every delivery point on the Postcode Address File. Remains unchanged regardless of address corrections or postcode changes
`UMRRN`	8-digit unique numeric identifier assigned by Royal Mail to premises where multiple households share a single letterbox (e.g., blocks of flats). Links to individual UDPRNs within the Multiple Residence dataset
`ParentUDPRN`	UDPRN of the parent or ‘shell’ building for multiple residence properties, linking child addresses (flats/apartments) to their primary building delivery point
`MPANPostcode`	Postcode associated with the Meter Point Administration Number, linking the electricity supply point to its postal address
`MPRNPostcode`	Postcode associated with the Meter Point Reference Number, linking the gas supply point to its postal address
`DeliveryPointSuffix`	2-character Royal Mail code that, combined with postcode, uniquely identifies each delivery point. First character is numeric (1-9), second is alphabetical (excluding C, I, K, M, O, V)
`MPANCount`	Number of electricity Meter Point Administration Numbers (MPANs) at the address, indicating multiple electricity supply points
`MPRNCount`	Number of gas Meter Point Reference Numbers (MPRNs) at the address, indicating multiple gas supply points
`FuelFlag`	Indicator denoting whether a property has gas, electricity, or both fuel types available based on associated MPAN and MPRN records
`LargeGasUser`	Classification flag for properties with significantly higher-than-average gas consumption, typically industrial or commercial premises requiring specialized metering
`EnergyUseOnly`	Flag indicating the address exists solely for energy utility purposes and may not be a fully validated postal address (often for properties under construction)

The following fields are available with numeric suffixes from 1-20 (e.g., MPRN1, MPRN2, etc.):

Field Pattern	Description
`MPRN{1-20}`	6-11 digit unique identifier for each gas supply point in the UK. Contains no letters and identifies specific gas meters
`MPAN{1-20}`	21-digit reference number (preceded by ‘S’) that uniquely identifies electricity supply points in Great Britain
`GasMeterSerial{1-20}`	Unique alphanumeric serial number physically inscribed on the gas meter (typically starts with ‘L’ and ends with ‘M’), distinct from MPRN
`ElectricMeterSerial{1-20}`	Unique alphanumeric serial number physically inscribed on the electricity meter (typically starts with ‘F’), distinct from MPAN
`GSPID{1-20}`	Grid Supply Point Identifier - unique identifier for each point where electricity transfers from National Grid transmission to regional distribution network
`ElectricMeterType{1-20}`	Classification of the electricity meter (single-rate, multi-rate, half-hourly, smart meter) determining billing arrangements and data collection frequency
`MPANTopLine{1-20}`	First 8 digits of MPAN specifying profile class (2 digits), meter time-switch code (3 digits), and line loss factor/DUoS Tariff ID (3 digits)

Business Data

Field	Description
`CompanyNumber`	8-character unique identifier assigned by Companies House upon incorporation. Format: 8 digits (England & Wales) or 2 letters + 6 digits (e.g., SC for Scotland, OC for LLPs, NI for Northern Ireland)
`TelephoneNumber`	Primary contact telephone number for the business, typically the main switchboard or customer service line
`UK2003Code`	4-digit Standard Industrial Classification code from the SIC 2003 system (effective January 2003 to January 2008)
`SICCode`	5-digit UK Standard Industrial Classification code from SIC 2007 system (effective from January 2008), aligned with European NACE Rev. 2 standards
`SICDescription`	Textual description of the economic activity associated with the SIC code (e.g., “70229 - Management consultancy activities other than financial management”)
`LineOfBusiness`	Broader categorical description of the company’s primary commercial activity, providing more accessible descriptions than technical SIC terminology
`EmployeesAtCompany`	Total workforce across all locations of the legal entity or enterprise
`EmployeesAtSite`	Number of employees working at this specific physical establishment or branch location
`LocationIndicator`	Code identifying the type or status of a business location (headquarters, branch office, manufacturing facility, or registered office)
`Sales`	Total gross revenue or turnover from core trading activities over a 12-month accounting period, before deducting expenses, returns, or taxes
`YearStarted`	Calendar year when the business commenced trading operations or was incorporated with Companies House
`Executive1Function`	Job title/role of the first company officer (director or secretary) registered at Companies House
`Executive1FirstName`	First name of the first executive
`Executive1Surname`	Surname of the first executive
`Executive1Salutation`	Title of the first executive (Mr., Ms., Dr., etc.)
`Executive2Function`	Job title/role of the second company officer
`Executive2FirstName`	First name of the second executive
`Executive2Surname`	Surname of the second executive
`Executive2Salutation`	Title of the second executive
`Executive3Function`	Job title/role of the third company officer
`Executive3FirstName`	First name of the third executive
`Executive3Surname`	Surname of the third executive
`Executive3Salutation`	Title of the third executive
`Executive4Function`	Job title/role of the fourth company officer
`Executive4FirstName`	First name of the fourth executive
`Executive4Surname`	Surname of the fourth executive
`Executive4Salutation`	Title of the fourth executive
`Executive5Function`	Job title/role of the fifth company officer
`Executive5FirstName`	First name of the fifth executive
`Executive5Surname`	Surname of the fifth executive
`Executive5Salutation`	Title of the fifth executive
`Executive6Function`	Job title/role of the sixth company officer
`Executive6FirstName`	First name of the sixth executive
`Executive6Surname`	Surname of the sixth executive
`Executive6Salutation`	Title of the sixth executive
`Executive7Function`	Job title/role of the seventh company officer
`Executive7FirstName`	First name of the seventh executive
`Executive7Surname`	Surname of the seventh executive
`Executive7Salutation`	Title of the seventh executive
`Executive8Function`	Job title/role of the eighth company officer
`Executive8FirstName`	First name of the eighth executive
`Executive8Surname`	Surname of the eighth executive
`Executive8Salutation`	Title of the eighth executive

Geo+

Field	Description
`PropertyType`	Classification of property nature and use (residential, commercial, industrial, agricultural, etc.) derived from local authority addressing data
`UPRN`	12-digit Unique Property Reference Number assigned by local authorities and Ordnance Survey to every addressable location in Great Britain, covering approximately 40 million locations
`UDPRN`	8-digit Unique Delivery Point Reference Number from Royal Mail’s Postcode Address File
`UMRRN`	8-digit Unique Multiple Residence Reference Number for premises where multiple households share a single letterbox
`Owning_UDPRN`	Royal Mail delivery point identifier for the parent or main building
`InferredParentUPRN`	Ordnance Survey property reference number derived through algorithmic matching when linking PAF addresses to AddressBase property records
`AddressKey`	8-digit Royal Mail PAF identifier that, with OrganisationKey and PostcodeType, uniquely identifies a delivery point
`OrganisationKey`	8-digit code distinguishing small user organizations at the same address (set to 0 for residential addresses), enabling differentiation of multiple businesses at a single delivery point
`DPS`	Delivery Point Suffix - 2-character Royal Mail code that uniquely identifies delivery points within a postcode
`LargeSmallUserFlag`	Royal Mail classification flag: “L” for Large User (dedicated postcode based on mail volume) or “S” for Small User
`SmallOrganisationFlag`	Flag identifying whether a delivery point is a small business or organization rather than residential
`NotYetBuiltFlag`	Flag (typically ‘Y’) indicating a property in planning or construction phase that is not yet deliverable by Royal Mail
`Eastings`	Ordnance Survey Easting coordinate in meters measured east from the false origin of the British National Grid (EPSG:27700)
`Northings`	Ordnance Survey Northing coordinate in meters measured north from the false origin of the British National Grid (EPSG:27700)
`Latitude`	Geographic latitude coordinate using WGS84 datum (EPSG:4326), providing rooftop-accurate location in decimal degrees
`Longitude`	Geographic longitude coordinate using WGS84 datum (EPSG:4326), providing rooftop-accurate location in decimal degrees
`UPRNDerivation`	Methodology used to assign the UPRN: allocated by local authorities during property creation, assigned by Ordnance Survey to landscape features, or derived through matching algorithms
`GeoDerivation`	Method used to assign geographic coordinates: direct survey measurement, address interpolation, postcode centroid, or dataset matching. Indicates spatial accuracy and reliability
`LinkedUDPRNs`	Related UDPRNs indicating spatial or organizational relationships, such as multiple occupancies within the same building
`LinkedUMRRNs`	Related UMRRNs for flats sharing a single letterbox, enabling navigation of multi-occupancy structures
`LinkedUPRNs`	Related UPRNs for properties with dependent addressing relationships, enabling navigation of address hierarchies

Overview

Location Solutions

Data Validation

Resources

Premium Data Sets for Address Capture Integration

Direct Via the API

Find

Retrieve

Capture SDK Guide

Using the simple setup

Utilities Standard/Premium

Business Data

Geo+

​Direct Via the API

​Find

​Retrieve

​Capture SDK Guide

​Using the simple setup

​Utilities Standard/Premium

​Business Data

​Geo+

Direct Via the API

Find

Retrieve

Capture SDK Guide

Using the simple setup

Utilities Standard/Premium

Business Data

Geo+