Cleanse Address

POST 
/cleanse/addresses

The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse.

Confidence Score

The confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score.

Deciding on an Acceptable Confidence Score Threshold

Different address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organistation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals.

When determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine:

• Which confidence scores indicate ambigious matches (i.e. up to building level only)
• Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address)

Depending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the throroughfare or building name only? Are accurate organisation names an important feature?

Request

Query Parameters

api_key string
API Key
Your unique identifier that allows access to our APIs.
Begins ak_. Available from your dashboard
Example: ak_test
Tags string
A comma separated list of tags to query over.
Useful if you want to specify the circumstances in which the request was made.
If multiple tags are specified, the response will only comprise of requests for which all the tags are satisfied - i.e. searching "foo,bar" will only query requests which tagged both "foo" and "bar".
Example: foo,bar

application/json

Body

required

query stringrequired

Freeform address input to cleanse

postcode string

Optionally specify postal code for the address.

post_town string

Optionally specify the city or town of the address.

For UK verifications, this should be the "post town" of the address.

For USA verifications, this should be the city of the address.

county string

Optionally specify the county or state of the address.

For UK verifications, we recommend omitting this field as county data is unreliable.

For USA verifications, this should be the state of the address.

Responses

200

Success

application/json

Schema

Schema

code int32required

Possible values: [2000]

message stringrequired

Possible values: [Success]

result object required

oneOf

Address Match

query stringrequired

Originally submitted query

match object required

Nearest matching address

oneOf

Postcode Address File Address

id IDrequired

Global unique internally generated identifier for an address

dataset Datasetrequired

Possible values: [paf]

Indicates the provenance of an address

country_iso ISO Country Code (3)required

Possible values: [GBR, IMN, JEY, GGY]

3 letter country code (ISO 3166-1)

country_iso_2 ISO Country Code (2)required

Possible values: [GB, IM, JE, GG]

2 letter country code (ISO 3166-1)

country Countryrequired

Possible values: [England, Scotland, Wales, Northern Ireland, Jersey, Guernsey, Isle of Man]

Full country names (ISO 3166)

language Languagerequired

Possible values: [en]

Language represented by 2 letter ISO Code (639-1)

line_1 Line 1required

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 Line 2required

Second Address Line. Often contains thoroughfare and locality information. May be empty

line_3 Line 3required

Third address line. May be empty.

post_town paf_post_townrequired

Possible values: <= 30 characters

**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 Postcoderequired

Possible values: >= 6 characters and <= 8 characters

Correctly formatted postcode. Capitalised and spaced.

county Countyrequired

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 County Coderequired

Short code representing the county or province. May be empty ("")

uprn Unique Property Reference Numberrequired

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 int32required

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 object 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.

oneOf

MOD1

string

MOD2

number

postcode_outward Postcode Outwardrequired

Possible values: >= 2 characters and <= 4 characters

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 Postcode Inwardrequired

Possible values: >= 3 characters and <= 3 characters

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 Dependant Localityrequired

Possible values: <= 35 characters

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 Localityrequired

Possible values: <= 35 characters

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 Thoroughfarerequired

Possible values: <= 80 characters

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 Dependant Thoroughfarerequired

Possible values: <= 80 characters

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 Building Numberrequired

Possible values: <= 4 characters

Number to identify premise on a thoroughfare or dependant thoroughfare.

building_name Building Namerequired

Possible values: <= 50 characters

Name of residential or commercial premise.

Examples:

• The Manor
• 1-2
• A
• 12A
• K
• Victoria House

sub_building_name Sub-Building Namerequired

Possible values: <= 30 characters

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 PO Boxrequired

Possible values: <= 6 characters

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 Department Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation.

organisation_name Organisation Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation

postcode_type Postcode Typerequired

Possible values: [S, L, ``]

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 Small User Organisation Indicatorrequired

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 Suffixrequired

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 Premiserequired

Possible values: <= 84 characters

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 Administrative Countyrequired

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 Postal Countyrequired

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 Traditional Countyrequired

Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.

district Districtrequired

The current district/unitary authority to which the postcode has been assigned.

ward Wardrequired

The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.

longitude object 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.

oneOf

MOD1

string

MOD2

number

latitude object 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.

oneOf

MOD1

string

MOD2

number

eastings object required

Eastings reference using the Ordnance Survey National Grid reference system.

Northern Ireland Eastings uses the 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.

oneOf

MOD1

string

MOD2

number

northings object required

Northings reference using the Ordnance Survey National Grid reference system

Northern Ireland Northings uses the 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

oneOf

MOD1

string

MOD2

number

Multiple Residence Address

id IDrequired

Global unique internally generated identifier for an address

dataset Datasetrequired

Possible values: [mr]

Indicates the provenance of an address

country_iso ISO Country Code (3)required

Possible values: [GBR, IMN, JEY, GGY]

3 letter country code (ISO 3166-1)

country_iso_2 ISO Country Code (2)required

Possible values: [GB, IM, JE, GG]

2 letter country code (ISO 3166-1)

country Countryrequired

Possible values: [England, Scotland, Wales, Northern Ireland, Jersey, Guernsey, Isle of Man]

Full country names (ISO 3166)

language Languagerequired

Possible values: [en]

Language represented by 2 letter ISO Code (639-1)

line_1 Line 1required

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 Line 2required

Second Address Line. Often contains thoroughfare and locality information. May be empty

line_3 Line 3required

Third address line. May be empty.

post_town paf_post_townrequired

Possible values: <= 30 characters

**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 Postcoderequired

Possible values: >= 6 characters and <= 8 characters

Correctly formatted postcode. Capitalised and spaced.

county Countyrequired

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 County Coderequired

Short code representing the county or province. May be empty ("")

uprn Unique Property Reference Numberrequired

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 int32required

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 object 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.

oneOf

MOD1

string

MOD2

number

postcode_outward Postcode Outwardrequired

Possible values: >= 2 characters and <= 4 characters

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 Postcode Inwardrequired

Possible values: >= 3 characters and <= 3 characters

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 Dependant Localityrequired

Possible values: <= 35 characters

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 Localityrequired

Possible values: <= 35 characters

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 Thoroughfarerequired

Possible values: <= 80 characters

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 Dependant Thoroughfarerequired

Possible values: <= 80 characters

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 Building Numberrequired

Possible values: <= 4 characters

Number to identify premise on a thoroughfare or dependant thoroughfare.

building_name Building Namerequired

Possible values: <= 50 characters

Name of residential or commercial premise.

Examples:

• The Manor
• 1-2
• A
• 12A
• K
• Victoria House

sub_building_name Sub-Building Namerequired

Possible values: <= 30 characters

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 PO Boxrequired

Possible values: <= 6 characters

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 Department Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation.

organisation_name Organisation Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation

postcode_type Postcode Typerequired

Possible values: [S, L, ``]

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 Small User Organisation Indicatorrequired

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 Suffixrequired

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 Premiserequired

Possible values: <= 84 characters

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 Administrative Countyrequired

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 Postal Countyrequired

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 Traditional Countyrequired

Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.

district Districtrequired

The current district/unitary authority to which the postcode has been assigned.

ward Wardrequired

The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.

longitude object 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.

oneOf

MOD1

string

MOD2

number

latitude object 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.

oneOf

MOD1

string

MOD2

number

eastings object required

Eastings reference using the Ordnance Survey National Grid reference system.

Northern Ireland Eastings uses the 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.

oneOf

MOD1

string

MOD2

number

northings object required

Northings reference using the Ordnance Survey National Grid reference system

Northern Ireland Northings uses the 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

oneOf

MOD1

string

MOD2

number

Not Yet Built Address

id IDrequired

Global unique internally generated identifier for an address

dataset Datasetrequired

Possible values: [nyb]

Indicates the provenance of an address

country_iso ISO Country Code (3)required

Possible values: [GBR, IMN, JEY, GGY]

3 letter country code (ISO 3166-1)

country_iso_2 ISO Country Code (2)required

Possible values: [GB, IM, JE, GG]

2 letter country code (ISO 3166-1)

country Countryrequired

Possible values: [England, Scotland, Wales, Northern Ireland, Jersey, Guernsey, Isle of Man]

Full country names (ISO 3166)

language Languagerequired

Possible values: [en]

Language represented by 2 letter ISO Code (639-1)

line_1 Line 1required

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 Line 2required

Second Address Line. Often contains thoroughfare and locality information. May be empty

line_3 Line 3required

Third address line. May be empty.

post_town paf_post_townrequired

Possible values: <= 30 characters

**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 Postcoderequired

Possible values: >= 6 characters and <= 8 characters

Correctly formatted postcode. Capitalised and spaced.

county Countyrequired

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 County Coderequired

Short code representing the county or province. May be empty ("")

uprn Unique Property Reference Numberrequired

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 int32required

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 object 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.

oneOf

MOD1

string

MOD2

number

postcode_outward Postcode Outwardrequired

Possible values: >= 2 characters and <= 4 characters

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 Postcode Inwardrequired

Possible values: >= 3 characters and <= 3 characters

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 Dependant Localityrequired

Possible values: <= 35 characters

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 Localityrequired

Possible values: <= 35 characters

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 Thoroughfarerequired

Possible values: <= 80 characters

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 Dependant Thoroughfarerequired

Possible values: <= 80 characters

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 Building Numberrequired

Possible values: <= 4 characters

Number to identify premise on a thoroughfare or dependant thoroughfare.

building_name Building Namerequired

Possible values: <= 50 characters

Name of residential or commercial premise.

Examples:

• The Manor
• 1-2
• A
• 12A
• K
• Victoria House

sub_building_name Sub-Building Namerequired

Possible values: <= 30 characters

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 PO Boxrequired

Possible values: <= 6 characters

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 Department Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation.

organisation_name Organisation Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation

postcode_type Postcode Typerequired

Possible values: [S, L, ``]

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 Small User Organisation Indicatorrequired

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 Suffixrequired

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 Premiserequired

Possible values: <= 84 characters

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 Administrative Countyrequired

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 Postal Countyrequired

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 Traditional Countyrequired

Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.

district Districtrequired

The current district/unitary authority to which the postcode has been assigned.

ward Wardrequired

The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.

longitude object 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.

oneOf

MOD1

string

MOD2

number

latitude object 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.

oneOf

MOD1

string

MOD2

number

eastings object required

Eastings reference using the Ordnance Survey National Grid reference system.

Northern Ireland Eastings uses the 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.

oneOf

MOD1

string

MOD2

number

northings object required

Northings reference using the Ordnance Survey National Grid reference system

Northern Ireland Northings uses the 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

oneOf

MOD1

string

MOD2

number

PAF Alias Address

id IDrequired

Global unique internally generated identifier for an address

dataset Datasetrequired

Possible values: [pafa]

Indicates the provenance of an address

country_iso ISO Country Code (3)required

Possible values: [GBR, IMN, JEY, GGY]

3 letter country code (ISO 3166-1)

country_iso_2 ISO Country Code (2)required

Possible values: [GB, IM, JE, GG]

2 letter country code (ISO 3166-1)

country Countryrequired

Possible values: [England, Scotland, Wales, Northern Ireland, Jersey, Guernsey, Isle of Man]

Full country names (ISO 3166)

language Languagerequired

Possible values: [en]

Language represented by 2 letter ISO Code (639-1)

line_1 Line 1required

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 Line 2required

Second Address Line. Often contains thoroughfare and locality information. May be empty

line_3 Line 3required

Third address line. May be empty.

post_town paf_post_townrequired

Possible values: <= 30 characters

**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 Postcoderequired

Possible values: >= 6 characters and <= 8 characters

Correctly formatted postcode. Capitalised and spaced.

county Countyrequired

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 County Coderequired

Short code representing the county or province. May be empty ("")

uprn Unique Property Reference Numberrequired

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 int32required

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 object 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.

oneOf

MOD1

string

MOD2

number

postcode_outward Postcode Outwardrequired

Possible values: >= 2 characters and <= 4 characters

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 Postcode Inwardrequired

Possible values: >= 3 characters and <= 3 characters

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 Dependant Localityrequired

Possible values: <= 35 characters

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 Localityrequired

Possible values: <= 35 characters

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 Thoroughfarerequired

Possible values: <= 80 characters

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 Dependant Thoroughfarerequired

Possible values: <= 80 characters

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 Building Numberrequired

Possible values: <= 4 characters

Number to identify premise on a thoroughfare or dependant thoroughfare.

building_name Building Namerequired

Possible values: <= 50 characters

Name of residential or commercial premise.

Examples:

• The Manor
• 1-2
• A
• 12A
• K
• Victoria House

sub_building_name Sub-Building Namerequired

Possible values: <= 30 characters

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 PO Boxrequired

Possible values: <= 6 characters

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 Department Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation.

organisation_name Organisation Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation

postcode_type Postcode Typerequired

Possible values: [S, L, ``]

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 Small User Organisation Indicatorrequired

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 Suffixrequired

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 Premiserequired

Possible values: <= 84 characters

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 Administrative Countyrequired

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 Postal Countyrequired

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 Traditional Countyrequired

Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.

district Districtrequired

The current district/unitary authority to which the postcode has been assigned.

ward Wardrequired

The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.

longitude object 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.

oneOf

MOD1

string

MOD2

number

latitude object 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.

oneOf

MOD1

string

MOD2

number

eastings object required

Eastings reference using the Ordnance Survey National Grid reference system.

Northern Ireland Eastings uses the 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.

oneOf

MOD1

string

MOD2

number

northings object required

Northings reference using the Ordnance Survey National Grid reference system

Northern Ireland Northings uses the 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

oneOf

MOD1

string

MOD2

number

Welsh PAF Address

id IDrequired

Global unique internally generated identifier for an address

dataset Datasetrequired

Possible values: [pafw]

Indicates the provenance of an address

country_iso ISO Country Code (3)required

Possible values: [GBR]

3 letter country code (ISO 3166-1)

country_iso_2 ISO Country Code (2)required

Possible values: [GB]

2 letter country code (ISO 3166-1)

country Countryrequired

Possible values: [Wales]

Full country names (ISO 3166)

language Languagerequired

Possible values: [cy]

Language represented by 2 letter ISO Code (639-1)

line_1 Line 1required

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 Line 2required

Second Address Line. Often contains thoroughfare and locality information. May be empty

line_3 Line 3required

Third address line. May be empty.

post_town paf_post_townrequired

Possible values: <= 30 characters

**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 Postcoderequired

Possible values: >= 6 characters and <= 8 characters

Correctly formatted postcode. Capitalised and spaced.

county Countyrequired

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 County Coderequired

Short code representing the county or province. May be empty ("")

uprn Unique Property Reference Numberrequired

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 int32required

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 object 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.

oneOf

MOD1

string

MOD2

number

postcode_outward Postcode Outwardrequired

Possible values: >= 2 characters and <= 4 characters

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 Postcode Inwardrequired

Possible values: >= 3 characters and <= 3 characters

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 Dependant Localityrequired

Possible values: <= 35 characters

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 Localityrequired

Possible values: <= 35 characters

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 Thoroughfarerequired

Possible values: <= 80 characters

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 Dependant Thoroughfarerequired

Possible values: <= 80 characters

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 Building Numberrequired

Possible values: <= 4 characters

Number to identify premise on a thoroughfare or dependant thoroughfare.

building_name Building Namerequired

Possible values: <= 50 characters

Name of residential or commercial premise.

Examples:

• The Manor
• 1-2
• A
• 12A
• K
• Victoria House

sub_building_name Sub-Building Namerequired

Possible values: <= 30 characters

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 PO Boxrequired

Possible values: <= 6 characters

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 Department Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation.

organisation_name Organisation Namerequired

Possible values: <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation

postcode_type Postcode Typerequired

Possible values: [S, L, ``]

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 Small User Organisation Indicatorrequired

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 Suffixrequired

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 Premiserequired

Possible values: <= 84 characters

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 Administrative Countyrequired

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 Postal Countyrequired

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 Traditional Countyrequired

Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.

district Districtrequired

The current district/unitary authority to which the postcode has been assigned.

ward Wardrequired

The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.

longitude object 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.

oneOf

MOD1

string

MOD2

number

latitude object 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.

oneOf

MOD1

string

MOD2

number

eastings object required

Eastings reference using the Ordnance Survey National Grid reference system.

Northern Ireland Eastings uses the 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.

oneOf

MOD1

string

MOD2

number

northings object required

Northings reference using the Ordnance Survey National Grid reference system

Northern Ireland Northings uses the 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

oneOf

MOD1

string

MOD2

number

United States CASS Verified Address

address1 stringrequired

Primary delivery address

address2 stringrequired

Secondary address information

address3 stringrequired

Additional secondary address information

area_code stringrequired

Area code

carrier_route stringrequired

Data required to perform a Carrier Route sort

check_digit stringrequired

Character following the 5- or 9-digit ZIP Code

city stringrequired

City name

city_abbreviation stringrequired

City Abbreviation. Empty string if not present

congressional_district stringrequired

Identifies the Congressional District. Empty string if not present

country_code stringrequired

ISO3166 country code. Empty string if not present

county stringrequired

Name of the county

day_light_savings stringrequired

Daylight saving time indicator

delivery_point stringrequired

Last 2 digits of the primary street address number or Post Office™ box

dpv stringrequired

DPV Confirmation code. Possible values: 'Y' (Yes), 'S' (Suspicious), 'D' (No).

dpv_cmra stringrequired

DPV CMRA code. Possible values: 'Y' (Yes), 'N' (No).

dpv_footnotes stringrequired

DPV Footnotes. Empty string if not present

dpv_fp stringrequired

False Positive Indicator from the DPV lookup. Possible values: 'Y' (Yes), 'N' (No), ' ' (Space). Empty string if not present

dpv_no_stat stringrequired

DPV NoStat code. Empty string if not present

dpv_vacant stringrequired

DPV Vacant code. Empty string if not present

elot stringrequired

Enhanced Line of Travel

finance_number object required

Internal accounting number used by the USPS. Empty string if not present

oneOf

MOD1

string

MOD2

number

fips_county_code stringrequired

Federal Information Processing Standard code for a county. Empty string if not present

firm stringrequired

Company name in a business address

footnotes stringrequired

Letter codes returned by ZIP + 4® encoding. Empty string if not present

geo_coded stringrequired

Indicates whether the address was geo-coded. Possible values: 'Y' (Yes), 'N' (No).

lacs_indicator stringrequired

Indicates whether a record may benefit from LACS processing. Possible values: 'L' (Yes), ' ' (No).

lacs_link_footnote stringrequired

LACSLink Footnote. Empty string if not present

lacs_link_indicator stringrequired

LACSLink Indicator. Empty string if not present

latitude object required

Latitude of the encoded address. Empty string if not present

oneOf

MOD1

string

MOD2

number

longitude object required

Longitude of the encoded address. Empty string if not present

oneOf

MOD1

string

MOD2

number

parsed_pmb_designator stringrequired

Information if a PMB is found in an address. Empty string if not present

parsed_pmb_number object required

Information if a PMB is found in an address. Empty string if not present

oneOf

MOD1

string

MOD2

number

parsed_post_directional object required

Notation following the street name indicating street direction. Empty string if not present

oneOf

MOD1

string

MOD2

number

parsed_pre_directional stringrequired

Notation preceding the street name indicating street direction. Empty string if not present

parsed_primary_number object required

Number preceding the street name. Empty string if not present

oneOf

MOD1

string

MOD2

number

parsed_street_name stringrequired

Street name. Empty string if not present

parsed_suffix stringrequired

Part of the delivery address line following the street name. Empty string if not present

parsed_unit_designator stringrequired

Identification of the secondary address unit. Empty string if not present

parsed_unit_number stringrequired

Apartment or suite number. Empty string if not present

rdi stringrequired

Reserved for future use. Empty string if not present

record_type stringrequired

Type of address record (Street, PO Box, High-rise, etc.)

secondary_address_info stringrequired

Additional secondary address information. Empty string if not present

state stringrequired

Standard two-letter state abbreviation

suite_link_footnote stringrequired

Results of the SuiteLink lookup. Possible values: ' ' (Space), '00' (Double Zero), 'A' (A). Empty string if not present

time_zone stringrequired

Time zone. Empty string if not present

urbanization stringrequired

Urban name required in the address of all mail being delivered to Puerto Rico. Empty string if not present

zip_code stringrequired

5-digit ZIP Code™ and the four additional digits

count numberrequired

Possible values: <= 10

The number of addresses we matched to the input. We return the closest match by default.

fit numberrequired

Possible values: <= 1

A score represented as number between 1 and 0. Fit compares the address elements present in your query against the matching address elements. It does not incorporate elements you have not presented in the score. A partial address (e.g. 12 Pye Green Road) will have a fit of 1 even though it is missing post town and postcode. Its confidence score will be less than 1 however because it is missing some crucial elements.

confidence numberrequired

Possible values: <= 1

A confidence score represented as number between 1 and 0. 1 indicates a full match. 0 indicates no complete matching elements.

organisation_match stringrequired

Possible values: [FULL, PARTIAL, INCORRECT, MISSING, NA]

Match indicator for the organisation

premise_match stringrequired

Possible values: [FULL, PARTIAL, INCORRECT, MISSING, NA]

Match indicator for the premise

postcode_match stringrequired

Possible values: [FULL, PARTIAL, INCORRECT, MISSING, NA]

Match indicator for the postcode

thoroughfare_match stringrequired

Possible values: [FULL, PARTIAL, INCORRECT, MISSING, NA]

Match indicator for the street

locality_match stringrequired

Possible values: [FULL, PARTIAL, INCORRECT, MISSING, NA]

Match indicator for the locality

post_town_match stringrequired

Possible values: [FULL, PARTIAL, INCORRECT, MISSING, NA]

Match indicator for the post_town

No Address Match

query stringrequired

Originally submitted query

match objectnullablerequired

Possible values: [null]

Nearest matching address

count numberrequired

Possible values: [0]

fit floatrequired

Possible values: [0]

confidence floatrequired

Possible values: [0]

organisation_match stringrequired

Possible values: [NO_MATCH]

premise_match stringrequired

Possible values: [NO_MATCH]

postcode_match stringrequired

Possible values: [NO_MATCH]

thoroughfare_match stringrequired

Possible values: [NO_MATCH]

locality_match stringrequired

Possible values: [NO_MATCH]

post_town_match stringrequired

Possible values: [NO_MATCH]

Example (from schema)

{
  "code": 2000,
  "message": "Success",
  "result": {}
}

400

Bad Request

application/json

Schema

Schema

code int32required

API Response Code. Non 2xxx code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.

message stringrequired

Human readable error message supplied with every error response.

errors object[]
Array [
message stringrequired
Indicates location of error in request query or URL parameter
path stringrequired
Indicates location of error in request query or URL parameter
errorCode string
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    {
      "message": "should have required property 'type'",
      "path": ".query.type",
      "errorCode": "required.openapi.validation"
    }
  ]
}

401

Unauthorized

application/json

Schema

Schema

code int32required

API Response Code. Non 2xxx code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.

message stringrequired

Human readable error message supplied with every error response.

Example (from schema)

{
  "code": 0,
  "message": "string"
}

429

Rate Limited

application/json

Schema

Schema

code int32required

API Response Code. Non 2xxx code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.

message stringrequired

Human readable error message supplied with every error response.

Example (from schema)

{
  "code": 0,
  "message": "string"
}

Loading...