The Postcode Evolution Service provides full access to the AFD API for all our products. The API is easy to use and quick to implement and returns XML/JSON data, whilst providing full flexibility.
This enables you to rapidly develop using the API with practically any development environment to provide the data that you require. All AFD products provide rapid lookup and search functionality al lowing you to implement address management solutions and provide bank data, account, and card validation.
The API is also backed up by our free customer support services. For full developer support, you can visit our website at https://www.afd.co.uk/support or contact us below:
Contact | Phone | |
---|---|---|
Sales | +44 333 433 0711 | postcode@afd.co.uk |
Support | +44 333 433 0712 | support@afd.co.uk |
System Requirements: 12GB RAM/12GB HDD Space.
Using any standard environment, you can simply make GET requests to our service and retrieve JSON or XML.
PCE is capable of integrating with any development platform that can make HTTP requests. We provide tools for some popular development platforms and frameworks, and recommend using these tools for projects built in these environment.
For projects built in other environments, below is a full documentation of the PCE service.
All calls to the Postcode Evolution XML/JSON server follow the same basic structure. The parameters that make up each call to the server can either be specified as parameters in the URL string, separated by ampersands i.e., using GET functionality, or can be sent to the server as a POST.
Note that in the case of Internet applications we strongly recommend that you have calls to the service running server-side with the code inaccessible to end-users to prevent abuse of the service, and in the case of the hosted service to protect your serial number and password.
The base URL for PCE requests is SERVER + /afddata.pce?
. For example, https://pce.afd.co.uk/afddata.pce?
would be our hosted server URL for Common-API requests.
The parameters usually supplied are then as follows:
Parameter | Description |
---|---|
Serial | Your assigned serial number |
Password | Your assigned password |
UserID | Enables you to identify different users or systems when comparing requests to any logs you may hold |
Data | Specifies the data you are using (see Data Selector below) |
Task | Specifies the task to carry out. |
Fields | Specifies the fields to use (see Field Presets (Section 5)) |
MaxQuantity | Specifies the maximum number of records to return |
Format | Specifies the format (XML or JSON) |
You should note that regardless of the maximum quantity setting there is a timeout setting (default 30 seconds) and a 128 KB buffer limit for the server to retain server responsiveness and prevent buffer overflows.
AFD’s performance engine doesn’t impose arbitrary field limits on data. This provides maximum compatibility and flexibility with future changes. We recommend where possible, customer applications do not set small fixed length limits for fields and use variable length fields where possible. For example in the past the Office of National Statistics provided a number of fields that were limited to between 3-5 characters. They then standardised on 9 characters which meant applications had to be updated to accommodate that, having a variable length field in the first place would have avoided that issue.
However, we appreciate some development environments and database systems may require fixed length fields and in such cases our Support team can assist you in setting appropriate lengths. These can be set to accommodate the maximum possible values currently in use and add headroom for future expansion where likely.
URL part | Value | Description |
---|---|---|
Service URL | https://pce.afd.co.uk | This is our hosted service. (Local installed is available) |
Data | address | See the data selector below for other options |
Country ISO | GBR | Other countries are available. |
Task | fast find | The task endpoint is the action being carried out (see Address Products (Section 6)) for all supported tasks |
Fields | list | See Field Presets (Section 5) |
Serial | 333333 | Supplied by AFD |
Password | pwd | Supplied by AFD |
Querystring | lookup | This is the last part where you can choose to have lookup or a search |
Format | JSON or XML | This can be either JSON or XML |
Taking each part above, the following is the complete URL to send to the service:
https://pce.afd.co.uk/afddata.pce?data=address&CountryISO=GBR&task=fastfind&fields=list&serial=333333&password=pwd&lookup=B6%204AA&format=json
This would then show as:
{
"Result": "1",
"ErrorText": "",
"Item": [
{
@value: "1",
"Postcode": "B6 4AA",
"PostcodeFrom": "",
"List": "B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM",
"Key": "3388990",
"CountryISO": "GBR"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&CountryISO=GBR&task=fastfind&fields=list&serial=333333&password=pwd&lookup=B6%204AA&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText></ErrorText>
<Item value="1">
<Postcode>B6 4AA</Postcode>
<PostcodeFrom></PostcodeFrom>
<List>B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM</List>
<Key>338899</Key>
<CountryISO>GBR</CountryISO>
</Item>
</AFDPostcodeEverywhere>
< update>
section and change the time value for < CheckTimeProductName>
where ProductName is your productThe below table shows which AFD product maps to which data selector in the API.
For example, if using the Postcode Plus product, then address
data should be specified in the call with GBR
as the country ISO.
Product | Data | CountryISO | Description |
---|---|---|---|
Postcode / Plotter | address | GBR | UK thoroughfare (see Section 6) (street) level address data |
Postcode Plus | address | GBR | UK address level data with postcode level grids |
Postcode Plus Business | address | GBR | UK address level data with postcode level grids and business data |
Eircode Validation | address | IRL | Irish address data |
ZipAddress | address | USA | USA address data |
WorldAddress | address | See List | Rest of world not including GBR, USA and IRL |
Names & Numbers | address | GBR | UK address level data with postcode level grids, business data and electoral roll information |
BankFinder | bank | GBR ,IRL or ALL | BACS (GBR) and IPSO (IRL) data and validation |
email | GBR | Provides access to Email validations (see Section 14) | |
Phone | phone | ALL | Provides access to Phone validations (see Section 13) |
Refiner | refiner | GBR | Provides access to Refiner (see Section 10) |
Nearest | nearest | GBR | Provides access to Nearest (see Section 12) |
Grid | grid | GBR | Provides access to Grid (see Section 8) |
List | list | GBR | Provides access to Utilities (see Section 7) |
If you do not know which data is accessible to you, please use the following ListProducts
Task URL: https://pce.afd.co.uk/afddata.pce?data=list&task=listproducts&serial=333333&password=pwd&format=json
Data in AFD Postcode Plus is sourced from the Royal Mail.
It is important to note that the standards regarding what is an acceptable address vary widely from country to country as do the levels of data that are available. So you must accommodate for different levels of data coming back and therefore different amounts of manual entry which may be required by users of your software to provide a complete address.
Some products or tasks support different field presets as output. A preset is selected by including &fields=
followed by the name of the preset in the query string to specify which fields should be returned.
Fields Preset | Valid for Data Selectors | Description |
---|---|---|
List | Address (see Section 6), Bank (see Section 9), Nearest (see Section 12) | Only the bare essential fields to allow the user to select the desired result from a list box. This includes the list item and key and for Address fields also includes the Postcode and PostcodeFrom parameters to allow changed postcodes to be detected. |
Standard | (All) | Returns all applicable fields for the data type, including a fully formatted address, as would be used on an address label, where applicable. |
Raw | Address (see Section 6), Bank (see Section 9) | Returns all applicable fields for the data type, but the address is included in the raw PAF format, for example house number, dependant thoroughfare and thoroughfare are returned as individual fields rather than a single Street field. |
BS7666 | Address (see Section 6) | Returns all applicable fields for the data type, but the address is included in a BS7666 compliant format which is useful if you require to store addresses in this form. |
USA | ZipAddress only | Returns fields in the format used in the USA when used with ZipAddress for looking up US addresses. |
Simple | Address (see Section 6) | Returns only the standard UK name and address, list and key fields when you require address data only and wish to minimise the amount of data returned. |
International | Address (see Section 6) | Recommended for international addresses, but also useable with UK addresses. This returns formatted address lines which provide the address in a format ready for printing on an envelope or address label, as well as component address fields. |
Account | Bank (see Section 9) | Contains applicable fields for Account Number validation. |
Card | Bank (see Section 9) | Contains applicable fields for Card Number validation. |
GeoList | Address (see Section 6) | Only returns fields specifically for the task fastfindgeo , along with any special data sets. |
Fflist | Address (see Section 5) | Can be used as a substitute for List, where the postcode is required at the end of the list box |
Custom * | Address (see Section 6), Bank (see Section 9), Nearest (see Section 12), Refiner (see Section 10) | You can return any of the available fields once specified. |
* You can specify any of our Available Fields (see Section 6.1) to be returned with an @
, for example &fields=address1@address2@address3
PostcodePlus, PostcodePlus Business, Postcode, Plotter, Names & Numbers, Eircode Validation, Zip Address, World Address
This section describes the Addressing group of product tasks for retrieving address information for a wider range of countries. The &CountryISO
parameter coupled with your AFD license determines which product you access.
When integrating with Address Management products the same code will work with any of our Address Management products (AFD Postcode, AFD Plotter, AFD Postcode Plus, AFD Names & Numbers, AFD Zip Address, Eircode Validation, and AFD World Address).
The fields within the Item
block will be dependent on the task carried out.Result
is numeric and either indicates an error (value less than 0
) or success (value > 0
).ErrorText
contains a description of the error which occurred if the value for Result is less than 0
.
The results are contained in Item
nodes (there will be one or more nodes if the operation was successful). Email
, Phone
and Bank
validation will only ever return 1
item node.
● = Fields returned by this product and fully searchable.
⚬ = Fields returned by this product, but not searchable.
Please note that the Field Lengths are only guidelines and are not limits.
Fieldname | Field Length | Data Type | Postcode | Postcode Plus | Postcode Plus Bus. | Names & Numbers | ZipAddress | WorldAddress | Eircode Validation |
---|---|---|---|---|---|---|---|---|---|
Postcode | 10 | Text | ● | ● | ● | ● | ● | ● | ● |
PostcodeFrom | 10 | Text | ⚬ | ● | ● | ● | ● | ||
List | 512 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Key | 8 | Numeric | ● | ● | ● | ● | ● | ● | ● |
CountryISO | 3 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Organisation | 120 | Text | ● | ● | ● | ● | ⚬ | ● | |
Property | 120 | Text | ● | ● | ● | ⚬ | ⚬ | ● | |
Street | 120 | Text | ● | ● | ● | ● | ● | ⚬ | ● |
Locality | 70 | Text | ● | ● | ● | ● | ⚬ | ⚬ | |
Town | 30 | Text | ● | ● | ● | ● | ● | ⚬ | ● |
DPS (Delivery Point Suffix) | 3 | Text | ⚬ | ⚬ | ⚬ | ||||
UDPRN (Unique Delivery Point Reference Number) | 8 | Numeric | ● | ● | ● | ● | |||
What3Words ** | 120 | Text | ● | ● | |||||
JustBuilt | 10 | Numeric | ● | ● | ● | ||||
Phone | 20 | Text | ● | ● | ● | ● | |||
PostalCounty | 30 | Text | ● | ● | ● | ● | ● | ⚬ | ● |
Abbreviated PostalCounty | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
OptionalCounty | 30 | Text | ● | ● | ● | ● | ● | ⚬ | ● |
Abbreviated OptionalCounty | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Traditional County | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Administrative County | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
NHSCode (National Health Service Code) | 6 | Text | ⚬ | ⚬ | ● | ||||
NHSName (National Health Service Name) | 50 | Text | ⚬ | ⚬ | ⚬ | ||||
NHSRegion Code (National Health Service Region Code) | 3 | Text | ⚬ | ⚬ | ⚬ | ||||
NHSRegion Name (National Health Service Region Name) | 20 | Text | ⚬ | ⚬ | ⚬ | ||||
PCTCode (Primary Care Trust Code) | 9 | Text | ⚬ | ⚬ | ● | ||||
PCTName (Primary Care Trust Name) | 50 | Text | ⚬ | ⚬ | ⚬ | ||||
WardCode | 9 | Text | ⚬ | ⚬ | ● | ||||
WardName | 50 | Text | ⚬ | ⚬ | ⚬ | ||||
Constituency Code | 9 | Text | ⚬ | ⚬ | ● | ||||
Constituency | 50 | Text | ⚬ | ⚬ | ⚬ | ||||
AuthorityCode | 9 | Text | ⚬ | ⚬ | ● | ||||
Authority | 50 | Text | ⚬ | ⚬ | ⚬ | ||||
LEACode (Local Education Authority Code) | 3 | Text | ⚬ | ⚬ | ● | ||||
LEAName (Local Education Authority Name) | 50 | Text | ⚬ | ⚬ | ⚬ | ||||
TVRegion | 30 | Text | ⚬ | ⚬ | ● | ||||
MailsortCode | 5 | Numeric | ⚬ | ⚬ | ⚬ | ● | |||
SubCountry Name | 20 | Text | ⚬ | ⚬ | ● | ||||
Devolved Constituency Code | 9 | Text | ⚬ | ⚬ | ● | ||||
Devolved Constituency Name | 50 | Text | ⚬ | ⚬ | ⚬ | ||||
SOALower (Super Output Area Lower) | 9 | Text | ⚬ | ⚬ | |||||
SOAMiddle (Super Output Area Middle) | 9 | Text | ⚬ | ⚬ | |||||
UrbanRural Code | 2 | Text | ⚬ | ⚬ | ⚬ | ||||
UrbanRural Name | 60 | Text | ⚬ | ⚬ | ⚬ | ||||
EERCode (European Electoral Region Code) | 9 | Text | ⚬ | ⚬ | ● | ||||
EERName (European Electoral Region Name) | 40 | Text | ⚬ | ⚬ | ⚬ | ||||
GridE (Grid East) * | 10 | Numeric | ● | ● | ● | ● | |||
GridN (Grid North) * | 10 | Numeric | ● | ● | ● | ● | |||
GBGridE (Great Britain Grid East) ** | 10 | Numeric | ● | ● | ● | ⚬ | |||
GBGridN (Great Britain Grid North) ** | 10 | Numeric | ● | ● | ● | ⚬ | |||
NIGridE (Northern Ireland Grid East) ** | 10 | Numeric | ● | ● | ● | ● | |||
NIGridN (Northern Ireland Grid North) ** | 10 | Numeric | ● | ● | ● | ● | |||
Miles | 6 | Numeric | ● | ● | ● | ● | |||
Km | 6 | Numeric | ● | ● | ● | ● | |||
Latitude * | 10 | Numeric | ⚬ | ⚬ | ● | ● | ● | ||
Longitude * | 10 | Numeric | ⚬ | ⚬ | ● | ● | ● | ||
PostcodeType | 6 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
CensationCode | 10 | Text | ⚬ | ⚬ | ⚬ | ● | |||
CensationLabel | 24 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
Affluence | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
Lifestage | 100 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
Additional CensusInfo | 200 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
AddressType | 6 | Numeric | ⚬ | ⚬ | ⚬ | ● | |||
AddressType Description | 55 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
Occupancy | 6 | Numeric | ⚬ | ⚬ | ⚬ | ● | |||
Occupancy Description | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
Name | 120 | Text | ⚬ | ||||||
Residency | 6 | Numeric | ⚬ | ||||||
Household Composition | 106 | Text | ⚬ | ||||||
Business | 100 | Text | ⚬ | ● | |||||
Size | 6 | Text | ⚬ | ● | |||||
SICCode (Standard Industry Classification Code) | 10 | Numeric | ⚬ | ● | |||||
LocationType | 6 | Text | ⚬ | ● | |||||
BranchCount | 6 | Numeric | ⚬ | ● | |||||
GroupID | 6 | Numeric | ⚬ | ● | |||||
TurnOver | 15 | Numeric | ⚬ | ● | |||||
NationalSize | 6 | Text | ⚬ | ● | |||||
OnEditedRoll | 6 | Text | ⚬ | ||||||
Gender | 6 | Text | ● | ||||||
Forename | 30 | Text | ● | ||||||
MiddleInitial | 6 | Text | ● | ||||||
Surname | 30 | Text | ● | ||||||
DateOfBirth | 10 | Numeric | ⚬ | ||||||
Product | 40 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Country | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
UPRN (Unique Property Reference Number) ** | 12 | Numeric | ● | ● | |||||
USRN (Unique Street Reference Number) ** | 12 | Numeric | ⚬ | ⚬ | |||||
NUTS3Code (Nomenclature of Territorial Units for Statistics 3 Code) ** | 5 | Text | ⚬ | ⚬ | |||||
NUTS3Name (Nomenclature of Territorial Units for Statistics 3 Name) ** | 50 † | Text | ⚬ | ⚬ | |||||
Council TaxBand ** | 6 † | Text | ⚬ | ||||||
GridLevel ** | 1 | Numeric | ⚬ | ⚬ | |||||
POLAR3Young ** | 8 † | Numeric | ⚬ | ⚬ | |||||
POLAR3Adult ** | 8 † | Numeric | ⚬ | ⚬ | |||||
POLAR4 ** | 8 † | Numeric | ⚬ | ⚬ | |||||
Deprivation Rank ** | 8 † | Numeric | ⚬ | ⚬ | |||||
Deprivation Decile ** | 1 | Numeric | ⚬ | ⚬ | |||||
LEPCode (Local Enterprise Parnership Code) ** | 9 | Text | ⚬ | ⚬ | |||||
LEPName (Local Enterprise Parnership Name) ** | 50 † | Text | ⚬ | ⚬ | |||||
LEPCode2 (Local Enterprise Parnership Code 2) ** | 9 | Text | ⚬ | ⚬ | |||||
LEPName2 (Local Enterprise Parnership Name 2) ** | 50 † | Text | ⚬ | ⚬ | |||||
AEBArea (Adult Education Budget Area) ** | 50 † | Text | ⚬ | ⚬ | |||||
AEBSource (Adult Education Budget Source) ** | 3 | Numeric | ⚬ | ⚬ | |||||
AEB EffectiveFrom (Adult Education Budget Effective From) ** | 10 | Text | ⚬ | ⚬ | |||||
AEB EffectiveTo (Adult Education Budget Effective To) ** | 10 | Text | ⚬ | ⚬ | |||||
Multiple Residency Indicator ** | 1 | Text | ⚬ | ⚬ | |||||
NotYetBuilt ** | 1 | Text | ⚬ | ⚬ | |||||
Abase (AddressBase) ** | 1 | Text | ⚬ | ⚬ | |||||
DXNumber ** | 10 | Text | ● | ● | ● | ||||
DXExchange ** | 30 | Text | ● | ● | ● | ||||
Dependent Locality | 70 | Text | ● | ● | ● | ● | |||
Dependent Thoroughfare | 40 | Text | ● | ● | ● | ● | |||
Double Dependent Locality | 40 | Text | ● | ● | ● | ● | |||
Organisation Name | 50 | Text | ● | ● | ● | ● | |||
Incode | 5 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
Outcode | 5 | Text | ⚬ | ⚬ | ⚬ | ⚬ | |||
FlatFlag ** | 1 | Text | ⚬ | ⚬ | |||||
ParentUPRN ** | 12 | Text | ⚬ | ||||||
BLPUStatus ** | 1 | Text | ⚬ | ||||||
AbaseClassification ** | 6 | Text | ⚬ |
The AbaseClassification is made of up to 6 characters.
Character one represents the Primary Code, character two represents the secondary code, characters three & four represent the tertiary code and characters five & six, when shown, represent the quaternary code.
For more information, please see the OS Classification Scheme.
NOTE: FlatFlag functionality is currently not available on desktop versions. * GridE/GridN and Latitude/Longitude not included in Postcode (requires at least Plotter). (Optional: International Grids) ** This is an optional data field and requires a license to return † No fixed length, so safety margin is usedFormatted closer to how they appear on Raw PAF, useful if your database stores fields this way.
Fieldname | Field Length | Data Type | Postcode | Postcode Plus | Names & Numbers | ZipAddress | WorldAddress | Eircode Validation |
---|---|---|---|---|---|---|---|---|
Organisation Name | 60 | Text | ● | ⚬ | ⚬ | ⚬ | ⚬ | |
Department | 60 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ||
SubBuilding | 60 | Text | ● | ⚬ | ⚬ | ⚬ | ⚬ | |
Building | 60 | Text | ● | ⚬ | ⚬ | ⚬ | ⚬ | |
Number | 10 | Numeric | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | |
Dependant Thoroughfare | 60 | Text | ● | ● | ⚬ | ⚬ | ⚬ | |
Thoroughfare | 60 | Text | ● | ● | ⚬ | ● | ⚬ | ⚬ |
Double Dependant Locality | 35 | Text | ● | ● | ⚬ | ⚬ | ||
Dependant Locality | 35 | Text | ● | ● | ⚬ | ⚬ | ⚬ | ⚬ |
Town | 30 | Text | ● | ● | ⚬ | ● | ⚬ | ● |
Postcode | 10 | Text | ● | ● | ● | ● | ⚬ | ● |
Fields to help provide addresses which conform to BS 7666-5:2006.
Fieldname | Field Length | Data Type | Postcode | Postcode Plus | Names & Numbers | ZipAddress | WorldAddress | Eircode Validation |
---|---|---|---|---|---|---|---|---|
Identifier | 8 | Numeric | ● | ● | ⚬ | ⚬ | ||
BuildDate | 10 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Administrator | 20 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Language | 5 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Department | 60 | Text | ● | ⚬ | ⚬ | |||
Organization | 60 | Text | ● | ⚬ | ● | ⚬ | ⚬ | |
SubUnit | 60 | Text | ● | ⚬ | ⚬ | |||
BuildingName | 60 | Text | ● | ⚬ | ⚬ | ⚬ | ||
BuildingNumber | 10 | Numeric | ● | ⚬ | ⚬ | ⚬ | ⚬ | |
SubStreet | 60 | Text | ● | ⚬ | ⚬ | |||
DeliveryStreet | 60 | Text | ● | ● | ⚬ | ⚬ | ⚬ | ⚬ |
SubLocality | 60 | Text | ● | ● | ⚬ | ⚬ | ||
DeliveryLocality | 60 | Text | ● | ● | ⚬ | ⚬ | ⚬ | ⚬ |
DeliveryTown | 30 | Text | ● | ● | ⚬ | ⚬ | ⚬ | ⚬ |
Code | 10 | Text | ● | ● | ⚬ | ⚬ | ⚬ | ⚬ |
Fieldname | Field Length | Data Type | Postcode | Postcode Plus | Names & Numbers | ZipAddress | WorldAddress | Eircode Validation |
---|---|---|---|---|---|---|---|---|
ZipCode | 20 | Text | ● | |||||
Key | 8 | Numeric | ⚬ | |||||
List | 512 | Text | ⚬ | |||||
CountryISO | 3 | Text | ⚬ | |||||
Recipient | 120 | Text | ⚬ | |||||
Secondary | 120 | Text | ● | |||||
Primary | 120 | Text | ● | |||||
Urbanization | 60 | Text | ⚬ | |||||
City | 30 | Text | ● | |||||
State | 30 | Text | ● | |||||
RecordType | 30 | Text | ⚬ | |||||
CarrierRouteID | 4 | Text | ⚬ | |||||
LACSStatus | 2 | Text | ⚬ | |||||
FinanceNumber | 7 | Numeric | ⚬ | |||||
Congressional District | 3 | Numeric | ⚬ | |||||
CountyNumber | 4 | Numeric | ⚬ | |||||
CountyName | 26 | Text | ⚬ | |||||
City Abbreviation | 14 | Text | ⚬ | |||||
Product | 40 | Text | ⚬ | |||||
Country | 30 | Text | ⚬ | |||||
Congressional District | 40 | Text | ⚬ |
This is the recommended format for international addresses, although all other formats can be used.
Fieldname | Field Length | Data Type | Postcode | Postcode Plus | Names & Numbers | ZipAddress | WorldAddress | Eircode Validation |
---|---|---|---|---|---|---|---|---|
Postcode | 10 | Text | ● | ● | ● | ● | ● | ● |
PostcodeFrom | 10 | Text | ⚬ | ● | ● | ● | ||
List | 512 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Key | 8 | Numeric | ● | ● | ● | ● | ● | ● |
CountryISO | 3 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Address1 | 120 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Address2 | 120 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Address3 | 120 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Address4 | 120 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Address5 | 120 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Address6 | 120 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Address7 | 120 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Organisation Name | 60 | Text | ● | ⚬ | ⚬ | ⚬ | ⚬ | |
Department | 60 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ||
SubBuilding | 60 | Text | ● | ⚬ | ⚬ | ⚬ | ⚬ | |
Building | 60 | Text | ● | ⚬ | ⚬ | ⚬ | ⚬ | |
Number | 10 | Numeric | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | |
Dependant Thoroughfare | 60 | Text | ● | ● | ⚬ | ⚬ | ⚬ | |
Thoroughfare | 60 | Text | ● | ● | ⚬ | ● | ⚬ | ⚬ |
Town | 30 | Text | ● | ● | ⚬ | ● | ⚬ | ● |
Principality | 60 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Region | 60 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | |
Cedex | 60 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Country | 30 | Text | ⚬ | ⚬ | ⚬ | ⚬ | ⚬ |
Fieldname | Field Length | Data Type | Postcode | Postcode Plus | Names & Numbers | ZipAddress | WorldAddress | Eircode Validation |
---|---|---|---|---|---|---|---|---|
AliasLocalities | 4 | Text | ⚬ | ⚬ | ||||
CountryISO | 35 | Text | ⚬ | ⚬ |
Fieldname | Description | Code | Result | Result Description | Postcode Plus | Postcode Plus Business |
---|---|---|---|---|---|---|
LoneParent | Lone Parent | Derived | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
NumKids | Number of Children under 18 at property | Actual, imputed where unknown | 0 | 0 Children | ⚬ | ⚬ |
1 | 1 Child | ⚬ | ⚬ | |||
2 | 2 Children | ⚬ | ⚬ | |||
3 | 3+ Children | ⚬ | ⚬ | |||
Lifestage | Individual Lifestage | Derived | 1 | Young Adults Still At Home (18-24, living at home) | ⚬ | ⚬ |
2 | Starting Out (18-24, left home) | ⚬ | ⚬ | |||
3 | Young and Single (25-34, single) | ⚬ | ⚬ | |||
4 | Young Couple (25-34, no children) | ⚬ | ⚬ | |||
5 | Older and Single (35-44, single, no children) | ⚬ | ⚬ | |||
6 | Older Couple (35-44, no children) | ⚬ | ⚬ | |||
7 | Pre-School Family (25-44, youngest child 0-4) | ⚬ | ⚬ | |||
8 | Young Family (25-44, youngest child 5-7) | ⚬ | ⚬ | |||
9 | Developing Family (25-44, youngest child tends to be 8-10) | ⚬ | ⚬ | |||
10 | Established Family (35-44, youngest child 11+) | ⚬ | ⚬ | |||
11 | Mature Family (45-54, children tend to be 11-16) | ⚬ | ⚬ | |||
12 | Adult Family (45-64, grown up children still at home) | ⚬ | ⚬ | |||
13 | Middle Age and Single (45-54, single, no children) | ⚬ | ⚬ | |||
14 | Middle Age Couple (45-54, couple, no children at home) | ⚬ | ⚬ | |||
15 | Mature Single (55-64, no partner) | ⚬ | ⚬ | |||
16 | Working Empty Nesters (55-64, couple, not retired, no kids at home) | ⚬ | ⚬ | |||
17 | Retired Empty Nesters (55-64, couple, retired, no kids) | ⚬ | ⚬ | |||
18 | Working Pensioner (65-74, still working) | ⚬ | ⚬ | |||
19 | Retired Single (65-74, retired, no partner) | ⚬ | ⚬ | |||
20 | Retired Couple (65-74, retired, partner) | ⚬ | ⚬ | |||
21 | Elderly Single (75+, no partner) | ⚬ | ⚬ | |||
22 | Elderly Couple (75+, couple) | ⚬ | ⚬ | |||
HouseholdComposition | Summary Household Composition | Derived | A | Female Single | ⚬ | ⚬ |
B | Male/Gender Unknown Single | ⚬ | ⚬ | |||
C | Married Couple | ⚬ | ⚬ | |||
D | Cohabiting Couple | ⚬ | ⚬ | |||
E | Two Person Household | ⚬ | ⚬ | |||
F | Married Family – Grown-Up Children at Home | ⚬ | ⚬ | |||
G | Non-Married Family – Grown-Up Children at Home | ⚬ | ⚬ | |||
H | Married Couple and 1 Other Adult | ⚬ | ⚬ | |||
I | Married Couple and 2+ Other Adults | ⚬ | ⚬ | |||
J | Cohabiting Couple and 1+ Other Adults | ⚬ | ⚬ | |||
K | Mixed Household of 3+ Adults | ⚬ | ⚬ | |||
HouseholdSize | Household Size-number of adults in household | Derived/Modelled | 1 | 1 Adult in Household | ⚬ | ⚬ |
2 | 2 Adults in Household | ⚬ | ⚬ | |||
3 | 3 Adults in Household | ⚬ | ⚬ | |||
4 | 4 Adults in Household | ⚬ | ⚬ | |||
5 | 5+ Adults in Household | ⚬ | ⚬ | |||
HouseholdChild_0_4 | Has Child in household 0-4 years old | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
HouseholdChild_5_7 | Has Child in household 5-7 years old | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
HouseholdChild_8_10 | Has Child in household 8-10 years old | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
HouseholdChild_11_16 | Has Child in household 11-16 years old | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
HouseholdChild_17_21 | Has Child in household 17-21 years old | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
HomeOwnership | Home Ownership Status | Actual, imputed where unknown | 1 | Home Owner | ⚬ | ⚬ |
2 | Rent – Council | ⚬ | ⚬ | |||
3 | Rent – Private | ⚬ | ⚬ | |||
4 | Living with Parents | ⚬ | ⚬ | |||
HavePets | Has Pets (any undefined pet, including cat and/or dog)) | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
HaveCat | Has Cat (specifically) | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
HaveDog | Has Dog (specifically) | Actual, imputed where unknown | 0 | No | ⚬ | ⚬ |
1 | Yes | ⚬ | ⚬ | |||
RenewalMonthHome | Home Insurance Renewal Month (joint buildings and contents) | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthContents | Contents Insurance Renewal Month (just contents insurance renewal) | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthBuilding | Buildings Insurance Renewal Month (just buildings insurance renewal month, no contents) | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthMotor | Motor Insurance Renewal Month | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthCar | Car Insurance Renewal Month | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthVan | Van Insurance Renewal Month | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthPets | Pet Insurance Renewal Month | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthTravel | Travel Insurance Renewal Month | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
RenewalMonthBike | Motorbike Insurance Renewal Month | Actual | 1 | January | ⚬ | ⚬ |
2 | February | ⚬ | ⚬ | |||
3 | March | ⚬ | ⚬ | |||
4 | April | ⚬ | ⚬ | |||
5 | May | ⚬ | ⚬ | |||
6 | June | ⚬ | ⚬ | |||
7 | July | ⚬ | ⚬ | |||
8 | August | ⚬ | ⚬ | |||
9 | September | ⚬ | ⚬ | |||
10 | October | ⚬ | ⚬ | |||
11 | November | ⚬ | ⚬ | |||
12 | December | ⚬ | ⚬ | |||
ResType | Type of Residence | Actual | 1 | Terraced | ⚬ | ⚬ |
2 | Detached | ⚬ | ⚬ | |||
3 | Semi Detached | ⚬ | ⚬ | |||
4 | Flat/Maisonette | ⚬ | ⚬ | |||
5 | Bungalow | ⚬ | ⚬ | |||
6 | Chalet | ⚬ | ⚬ | |||
8 | Mobile Home | ⚬ | ⚬ | |||
9 | Caravan | ⚬ | ⚬ | |||
Bedrooms | The number of bedrooms in a property | 0 | 0 Bedrooms | ⚬ | ⚬ | |
1 | 1 Bedroom | ⚬ | ⚬ | |||
2 | 2 Bedrooms | ⚬ | ⚬ | |||
3 | 3 Bedrooms | ⚬ | ⚬ | |||
4 | 4 Bedrooms | ⚬ | ⚬ | |||
5 | 5 Bedrooms | ⚬ | ⚬ | |||
6 | 6 Bedrooms | ⚬ | ⚬ | |||
7 | 7+ Bedrooms | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
TotalRooms | The number of rooms within a property excluding bathrooms and kitchen | 1 | 1 Room | ⚬ | ⚬ | |
2 | 2 Rooms | ⚬ | ⚬ | |||
3 | 3 Rooms | ⚬ | ⚬ | |||
4 | 4 Rooms | ⚬ | ⚬ | |||
5 | 5 Rooms | ⚬ | ⚬ | |||
6 | 6 Rooms | ⚬ | ⚬ | |||
7 | 7 Rooms | ⚬ | ⚬ | |||
8 | 8 Rooms | ⚬ | ⚬ | |||
9 | 9 Rooms | ⚬ | ⚬ | |||
10 | 10 Rooms | ⚬ | ⚬ | |||
11 | 11 Rooms | ⚬ | ⚬ | |||
12 | 12 Rooms | ⚬ | ⚬ | |||
13 | 13 Rooms | ⚬ | ⚬ | |||
14 | 14 Rooms | ⚬ | ⚬ | |||
15 | 15 Rooms | ⚬ | ⚬ | |||
16 | 16+ Rooms | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
YearOfBuild | The year the property has been recorded as being built | Populated | Year Of Build Populated | ⚬ | ⚬ | |
NULL | ⚬ | ⚬ | ||||
CurrentPropValue | The current estimated value of the property, based on Land Registry data | Populated | Current Property Value Populated | ⚬ | ⚬ | |
NULL | ⚬ | ⚬ | ||||
CurrentListingStatus | The current listing status of the property, e.g. Available or Under Offer | 0 | Available | ⚬ | ⚬ | |
1 | Sold Subject to Contract | ⚬ | ⚬ | |||
2 | SSTCM (Scotland only) | ⚬ | ⚬ | |||
3 | Under Offer | ⚬ | ⚬ | |||
4 | Reserved (Renting only) | ⚬ | ⚬ | |||
5 | Let Agreed (Renting only) | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
LastTransactionDate | The date of the last transaction recorded by the Land Registry (data goes back to 1995, exclusions apply) | Populated | Last Transaction Date Populated | ⚬ | ⚬ | |
NULL | ⚬ | ⚬ | ||||
HouseValueBand | The estimated value of the property split into £100,000 bands for ease of selection | 1 | £0-£100,000 | ⚬ | ⚬ | |
2 | £100,000-£200,000 | ⚬ | ⚬ | |||
3 | £200,000-£300,000 | ⚬ | ⚬ | |||
4 | £300,000-£400,000 | ⚬ | ⚬ | |||
5 | £400,000-£500,000 | ⚬ | ⚬ | |||
6 | £500,000-£600,000 | ⚬ | ⚬ | |||
7 | £600,000-£700,000 | ⚬ | ⚬ | |||
8 | £700,000-£800,000 | ⚬ | ⚬ | |||
9 | £800,000-£900,000 | ⚬ | ⚬ | |||
10 | £900,000-£1,000,000 | ⚬ | ⚬ | |||
11 | £1,000,000-£1,100,000 | ⚬ | ⚬ | |||
12 | £1,100,000-£1,200,000 | ⚬ | ⚬ | |||
13 | £1,200,000-£1,300,000 | ⚬ | ⚬ | |||
14 | £1,300,000-£1,400,000 | ⚬ | ⚬ | |||
15 | £1,400,000-£1,500,000 | ⚬ | ⚬ | |||
16 | £1,500,000+ | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
Listed | Whether the property is listed by English Heritage, Cadw or Historic Scotland, and its category of listing | 0 | Not listed | ⚬ | ⚬ | |
1 | I or A | ⚬ | ⚬ | |||
2 | II* or B | ⚬ | ⚬ | |||
3 | II or C | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
Watercourse200M | Flag indicating whether there is a watercourse within 200 metres | 1 | Yes | ⚬ | ⚬ | |
0 | No watercourse within 200m | ⚬ | ⚬ | |||
DistanceToWatercourse | The distance (in metres) to a watercourse if it is within 200 metres | 1 | Distance To Watercourse within 200m Populated >0 | ⚬ | ⚬ | |
NULL | ⚬ | ⚬ | ||||
DistanceToRoad | The distance to the centre line of the nearest road, not necessarily accessible | Populated | Distance To Road Populated >0 | ⚬ | ⚬ | |
NULL | ⚬ | ⚬ | ||||
DistanceToTree | The distance from the nearest tree over 10 metres tall to the property geocode | Populated | Distance To Tree Populated >0 | ⚬ | ⚬ | |
0 | No relevant tree near | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
BurglaryRate | The number of burglaries per property per year averaged over a LSOA | Populated | Burglary Rate Populated >0 | ⚬ | ⚬ | |
0 | ⚬ | ⚬ | ||||
NULL | ⚬ | ⚬ | ||||
MainFuel | The main type of fuel used by the property’s heating system | 0 | Gas | ⚬ | ⚬ | |
1 | Electricity | ⚬ | ⚬ | |||
2 | Oil | ⚬ | ⚬ | |||
3 | Not known | ⚬ | ⚬ | |||
4 | Coal | ⚬ | ⚬ | |||
5 | LPG | ⚬ | ⚬ | |||
6 | Wood | ⚬ | ⚬ | |||
7 | None | ⚬ | ⚬ | |||
8 | B30K | ⚬ | ⚬ | |||
9 | Other | ⚬ | ⚬ | |||
10 | Biomass/Biogas | ⚬ | ⚬ | |||
11 | District heating | ⚬ | ⚬ | |||
12 | Waste heat | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
WallType | What walls the property contains, possible values cavity wall, solid brick, sandstone, granite, timber frame, system built and SAP05 | 0 | Cavity wall | ⚬ | ⚬ | |
1 | Solid brick | ⚬ | ⚬ | |||
2 | Sandstone | ⚬ | ⚬ | |||
3 | Timber frame | ⚬ | ⚬ | |||
4 | Granite | ⚬ | ⚬ | |||
5 | System built | ⚬ | ⚬ | |||
6 | SAP05 | ⚬ | ⚬ | |||
7 | Not known | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
HeatingType | The main method of which the property is heated | 1 | Air Source | ⚬ | ⚬ | |
2 | Boiler and Radiators | ⚬ | ⚬ | |||
3 | Boiler and Underfloor Heating | ⚬ | ⚬ | |||
4 | Community Scheme | ⚬ | ⚬ | |||
5 | Electric Underfloor Heating | ⚬ | ⚬ | |||
6 | Ground Source Heat Pump | ⚬ | ⚬ | |||
9 | Room Heaters – Electric | ⚬ | ⚬ | |||
10 | Room Heaters – Gas | ⚬ | ⚬ | |||
11 | Room Heaters – Solid Fuel | ⚬ | ⚬ | |||
12 | Room Heaters – Wood Fuel | ⚬ | ⚬ | |||
13 | Warm Air Heating | ⚬ | ⚬ | |||
14 | Water Source Heat Pump | ⚬ | ⚬ | |||
15 | Electric Storage Heater | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
RoofType | The type of roof a property has (Flat, Pitched, Thatched) and its level of insulation | 1 | Flat – Insulated | ⚬ | ⚬ | |
2 | Flat – Limited Insulation | ⚬ | ⚬ | |||
3 | Flat – No Insulation | ⚬ | ⚬ | |||
4 | Pitched – 100mm and under | ⚬ | ⚬ | |||
5 | Pitched – 101mm to 300mm | ⚬ | ⚬ | |||
6 | Pitched – 300mm+ | ⚬ | ⚬ | |||
7 | Pitched – Insulated | ⚬ | ⚬ | |||
8 | Pitched – Limited Insulation | ⚬ | ⚬ | |||
9 | Pitched – No Insulation | ⚬ | ⚬ | |||
10 | Thatched | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
AvgRoofSlope | The average slope of the property roof, can be used to identify properties with flat roofs | Populated | Average Roof Slope Populated | ⚬ | ⚬ | |
NULL | ⚬ | ⚬ | ||||
FlatRoofFraction | The estimated fraction of a property which has a flat roof | Populated | Flat Roof Fraction Populated | ⚬ | ⚬ | |
NULL | ⚬ | ⚬ | ||||
NumberOfBathrooms | 1 | 1 | ⚬ | ⚬ | ||
2 | 2 | ⚬ | ⚬ | |||
3 | 3 | ⚬ | ⚬ | |||
4 | 4 | ⚬ | ⚬ | |||
5 | 5+ | ⚬ | ⚬ | |||
Null | Null (assumed 1) | ⚬ | ⚬ | |||
HomeContentsCoverValue | null | null | ⚬ | ⚬ | ||
100k | 100k | ⚬ | ⚬ | |||
10k | 10k | ⚬ | ⚬ | |||
15k | 15k | ⚬ | ⚬ | |||
20k | 20k | ⚬ | ⚬ | |||
25k | 25k | ⚬ | ⚬ | |||
300k+ | 300k+ | ⚬ | ⚬ | |||
30k | 30k | ⚬ | ⚬ | |||
35k | 35k | ⚬ | ⚬ | |||
50k | 50k | ⚬ | ⚬ | |||
BuildingConstructionPeriod | Building Construction Period | 0 | -1719 (old) | ⚬ | ⚬ | |
1 | 1720-1839 (Georgian) | ⚬ | ⚬ | |||
2 | 1840-1919 (Victorian/Edwardian) | ⚬ | ⚬ | |||
3 | 1920-1945 (Inter-war) | ⚬ | ⚬ | |||
4 | 1946-1979 (Post war) | ⚬ | ⚬ | |||
5 | 1980 to date (Modern) | ⚬ | ⚬ | |||
Not known | ⚬ | ⚬ | ||||
Bungalow | Bungalow | 0 | No | ⚬ | ⚬ | |
1 | Yes | ⚬ | ⚬ | |||
Product | Name of AFD Product in use | ⚬ | ⚬ | |||
Country | the Country Name for the data returned | ⚬ | ⚬ | |||
Building Construction Period | 0 | -1719 (old) | ⚬ | ⚬ | ||
1 | 1720-1839 (Georgian) | ⚬ | ⚬ | |||
2 | 1840-1919 (Victorian/Edwardian) | ⚬ | ⚬ | |||
3 | 1920-1945 (Inter-war) | ⚬ | ⚬ | |||
4 | 1946-1979 (Post war) | ⚬ | ⚬ | |||
5 | 1980 to date (Modern) | ⚬ | ⚬ | |||
Not known | ⚬ | ⚬ | ||||
EstimatedPropertyValue | Actual, imputed where unknown | Populated | ⚬ | ⚬ | ||
NULL | ⚬ | ⚬ | ||||
PVLowerConfidenceLimit95 | Populated | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
PVUpperConfidenceLimit95 | Populated | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
EstimatedYearBuilt | Populated | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
EstimatedYearBuilt_UpperLimit | Populated | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ | ||||
EstimatedYearBuilt_LowerLimit | Populated | ⚬ | ⚬ | |||
NULL | ⚬ | ⚬ |
Fieldname | Field Length | Data Type | Postcode Plus | Postcode Plus Business |
---|---|---|---|---|
BuiltForm** | 40 | String | ⚬ | ⚬ |
CO2EmissionsCurrent** | 40 | String | ⚬ | ⚬ |
CO2EmissionsCurrent PerFloorArea** | 40 | String | ⚬ | ⚬ |
CO2EmissionsPotential** | 40 | String | ⚬ | ⚬ |
ConstructionAgeBand** | 40 | String | ⚬ | ⚬ |
CurrentEnergyRating** | 40 | String | ⚬ | ⚬ |
EnergyConsumptionCurrent** | 40 | String | ⚬ | ⚬ |
EnergyConsumptionPotential** | 40 | String | ⚬ | ⚬ |
EnergyTariff** | 40 | String | ⚬ | ⚬ |
EnvironmentalImpactCurrent** | 40 | String | ⚬ | ⚬ |
EnvironmentalImpactPotential** | 40 | String | ⚬ | ⚬ |
ExtensionCount** | 40 | Int | ⚬ | ⚬ |
FixedLightingOutletsCount** | 40 | String | ⚬ | ⚬ |
FlatStoreyCount** | 40 | Int | ⚬ | ⚬ |
FlatTopStorey** | 40 | String | ⚬ | ⚬ |
FloorDescription** | 40 | String | ⚬ | ⚬ |
FloorEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
FloorEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
FloorHeight** | 40 | String | ⚬ | ⚬ |
FloorLevel** | 40 | String | ⚬ | ⚬ |
GlazedArea** | 40 | String | ⚬ | ⚬ |
GlazedType** | 40 | String | ⚬ | ⚬ |
HeatLossCorridor** | 40 | String | ⚬ | ⚬ |
HeatingCostCurrent** | 40 | String | ⚬ | ⚬ |
HeatingCostPotential** | 40 | String | ⚬ | ⚬ |
HotWaterCostCurrent** | 40 | String | ⚬ | ⚬ |
HotWaterCostPotential** | 40 | String | ⚬ | ⚬ |
HotWaterDescription** | 40 | String | ⚬ | ⚬ |
HotWaterEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
HotWaterEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
InspectionDate** | 40 | String | ⚬ | ⚬ |
LightingCostCurrent** | 40 | String | ⚬ | ⚬ |
LightingCostPotential** | 40 | String | ⚬ | ⚬ |
LightingDescription** | 40 | String | ⚬ | ⚬ |
LightingEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
LightingEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
LowEnergyFixedLightCount** | 40 | String | ⚬ | ⚬ |
LowEnergyLighting** | 40 | String | ⚬ | ⚬ |
MainFuel** | 40 | String | ⚬ | ⚬ |
MainHeatControlsDescription** | 40 | String | ⚬ | ⚬ |
MainHeatControlsEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
MainHeatControlsEnvironmental Efficiency** | 40 | String | ⚬ | ⚬ |
MainHeatDescription** | 40 | String | ⚬ | ⚬ |
MainHeatEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
MainHeatEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
MainHeatingControls** | 40 | String | ⚬ | ⚬ |
MainsGasFlag** | 40 | String | ⚬ | ⚬ |
MechanicalVentilation** | 40 | String | ⚬ | ⚬ |
MultiGlazeProportion** | 40 | String | ⚬ | ⚬ |
NumberHabitableRooms** | 40 | String | ⚬ | ⚬ |
NumberHeatedRooms** | 40 | Int | ⚬ | ⚬ |
NumberOpenFireplaces** | 40 | Int | ⚬ | ⚬ |
NumberStoreys** | 40 | Int | ⚬ | ⚬ |
PossibleIssues** | 40 | String | ⚬ | ⚬ |
PotentialEnergyRating** | 40 | String | ⚬ | ⚬ |
PropertyType** | 40 | String | ⚬ | ⚬ |
RenewableHeatIncentive** | 40 | String | ⚬ | ⚬ |
RoofDescription** | 40 | String | ⚬ | ⚬ |
RoofEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
RoofEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
TotalFloorArea** | 40 | Int | ⚬ | ⚬ |
TransactionType** | 40 | String | ⚬ | ⚬ |
WallDescription** | 40 | String | ⚬ | ⚬ |
WallEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
WallEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
WaterDescription** | 40 | String | ⚬ | ⚬ |
WaterEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
WaterEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
WindowsDescription** | 40 | String | ⚬ | ⚬ |
WindowsEnergyEfficiency** | 40 | String | ⚬ | ⚬ |
WindowsEnvironmentalEfficiency** | 40 | String | ⚬ | ⚬ |
Fieldname | Field Length | Data Type | Postcode Plus | Postcode Plus Business |
---|---|---|---|---|
AssetRating** | 40 | Text | ⚬ | ⚬ |
PropertyType** | 40 | String | ⚬ | ⚬ |
InspectionDate** | 40 | Date | ⚬ | ⚬ |
TransactionType** | 40 | Text | ⚬ | ⚬ |
NewBuildBenchmark** | 40 | String | ⚬ | ⚬ |
ExistingStockBenchmark** | 40 | String | ⚬ | ⚬ |
BuildingLevel** | 40 | Int | ⚬ | ⚬ |
MainHeatingFuel** | 40 | Text | ⚬ | ⚬ |
OtherFuelDescription** | 40 | String | ⚬ | ⚬ |
SpecialEnergyUses** | 40 | String | ⚬ | ⚬ |
RenewableSources** | 40 | String | ⚬ | ⚬ |
FloorArea** | 40 | String | ⚬ | ⚬ |
StandardEmissions** | 40 | String | ⚬ | ⚬ |
TargetEmissions** | 40 | String | ⚬ | ⚬ |
TypicalEmissions** | 40 | String | ⚬ | ⚬ |
BuildingEmissions** | 40 | String | ⚬ | ⚬ |
AirconPresent** | 40 | Text | ⚬ | ⚬ |
AirconKWRating** | 40 | String | ⚬ | ⚬ |
EstimatedAirconKWRating** | 40 | Int | ⚬ | ⚬ |
AcInspectionCommissioned** | 40 | Int | ⚬ | ⚬ |
BuildingEnvironment** | 40 | Text | ⚬ | ⚬ |
PrimaryEnergyValue** | 40 | String | ⚬ | ⚬ |
The below table describes the possible result codes and error messages:
Result | Description |
---|---|
1 | Success |
-1 | Invalid Field spec |
-2 | No Results Found |
-4 | Error Loading Data Files |
-7 | Data License Error |
For the correct data option to use, please see the Data Selector section (see Section 4).
{
"Result": "1",
"ErrorText": "",
"Item": [
{
@value: "1",
"Postcode": "B6 4AA",
"PostcodeFrom": "",
"List": "B6 4AA Royal Mail, Birmingham Mail Centre, St Stephens Street, BIRMINGHAM",
"Key": "3388990",
"CountryISO": "GBR"
}
]
}
Lookup Tasks are a group of different calls that each accepts only one search parameter, specified using a Lookup
string.
FastFindV4 optimises the Fast Find task for TypeAhead situations.
It is necessary to specify a Unique ID (for example, the Session ID) for each individual customer session. That ID should remain the same for a single search for an address regardless of how many keystrokes are used. It is specified using the &uniqueID=
parameter in a GET request. This allows our billing system to make sure that each keypress is not being charged separately. We also recommend setting the Max Quantity parameter (&maxquantity=
) to a number between 5 and 7 as this will increase the responsiveness of your TypeAhead control. Note that all prebuilt plugins with typeahead integrations set these parameters automatically.
Description | Example |
---|---|
UK Postcode | B11 |
House No. and Postcode | 276,B111AA |
Organisation | Royal Mail |
This task allows a single text string containing search terms to be entered and is used to provide typeahead functionality (“search as you type”).
We also recommend setting the &maxquantity
to a number between 5 and 7 as this will increase the responsiveness of your TypeAhead control.
The addition of the &allpc=1
parameter means that the default max quantity for typeahead with be ignored when a postcode is entered.
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&CountryISO=GBR&task=fastfindv4&fields=list&format=json&lookup=ROYAL&maxquantity=1&allpc=1
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Postcode: "AB10 1BD",
PostcodeFrom: "",
List: "AB10 1BD The Royal British Legion, 46a Union Street, ABERDEEN",
Key: "105",
CountryISO: "GBR"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&CountryISO=GBR&task=fastfindv4&fields=list&format=xml&lookup=ROYAL&maxquantity=1
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText></ErrorText>
<Item value="1">
<Postcode>AB10 1BD</Postcode>
<PostcodeFrom></PostcodeFrom>
<List>AB10 1BD The Royal British Legion, 46a Union Street, ABERDEEN</List>
<Key>105</Key>
<CountryISO>GBR</CountryISO>
</Item>
</AFDPostcodeEverywhere>
To lookup matching addresses quickly from search criteria such as Commercial Street, Birmingham
.
The Fast Find task accepts a single string as input, and if successful returns one or more records. The input can be a postcode, or an address element, or a combination of these separated by a comma.
Description | Example |
---|---|
UDPRN | 00338899 |
Organisation and Town | Royal Mail, Birmingham |
Street and Town | Commercial Street, Birmingham |
Organisation and Postcode | Royal Mail, B6 4AA |
This task is highly flexible as it allows a single text string containing search terms to be entered.
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=fastfind&fields=list&format=json&lookup=Royal%20Mail,B6%204AA&maxquantity=5
{
"Result": "1",
"ErrorText": "",
"Item": [
{
@value: "1",
"Postcode": "B6 4AA",
"PostcodeFrom": "",
"List": "B6 4AA Royal Mail, Birmingham Mail Centre, St Stephens Street, BIRMINGHAM",
"Key": "3388990",
"CountryISO": "GBR"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=fastfind&fields=list&format=xml&lookup=Royal%20Mail,B6%204AA&maxquantity=5
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText></ErrorText>
<Item value="1">
<Postcode>B6 4AA</Postcode>
<PostcodeFrom></PostcodeFrom>
<List>B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM</List>
<Key>338899</Key>
<CountryISO>GBR</CountryISO>
</Item>
</AFDPostcodeEverywhere>
To lookup matching addresses quickly from a postcode, e.g., B11 1AA
. Only a full postcode without any property information included will yield results.
By entering a single string, the user can find the results matching their lookup criteria.
Description | Example |
---|---|
UK Postcode | B6 4AA |
This task should be used if you only ever intend to send a postcode as input, as it will not attempt to search for invalid input.
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=Lookup&fields=list&format=json&lookup=B6%204AA
{
"Result": "1",
"ErrorText": "",
"Item": [
{
@value: "1",
"Postcode": "B6 4AA",
"PostcodeFrom": "",
"List": "B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM",
"Key": "3388990",
"CountryISO": "GBR"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=Lookup&fields=list&format=xml&lookup=B6%204AA
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText></ErrorText>
<Item value="1">
<Postcode>B6 4AA</Postcode>
<PostcodeFrom></PostcodeFrom>
<List>B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM</List>
<Key>338899</Key>
<CountryISO>GBR</CountryISO>
</Item>
</AFDPostcodeEverywhere>
To lookup matching addresses quickly from a postcode, which may optionally include property information to find a match, e.g., 276, B11 1AA
.
Description | Example |
---|---|
House No. and Postcode | 276,B111AA |
Property and Postcode | Flat 2,B11 1AA |
This task is useful if using input that always includes a full postcode but may also include a property or street number.
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=PropertyLookup&fields=list&format=json&lookup=280,B11%201AA
{
"Result": "1",
"ErrorText": "",
"Item": [
{
@value: "1",
"Postcode": "B11 1AA",
"PostcodeFrom": "",
"List": "B11 1AA 280 Stratford Road, Sparkhill, BIRMINGHAM",
"Key": "379670",
"CountryISO": "GBR"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=PropertyLookup&fields=list&format=xml&lookup=280,B11%201AA
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Postcode>B11 1AA</Postcode>
<PostcodeFrom/>
<List>B11 1AA 280 Stratford Road, Sparkhill, BIRMINGHAM</List>
<Key>379670</Key>
<CountryISO>GBR</CountryISO>
</Item>
</AFDPostcodeEverywhere>
The search function allows records to be located by searching using specific fields rather than a general lookup string. Any Available Fields (see Section 6.1) are supported as the input, and if successful it returns one or more records.
For the correct data option to use, please see the Data Selector section (see Section 4).
Descriptions | Example |
---|---|
Searchable Field | &Street=280%20Stratford%20Road&Town=Birmingham |
This task should be used if the input fields conform to a rigid mapping.
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=search&fields=list&format=json&Street=280%20Stratford%20Road&Town=Birmingham
{
<Result>: "1",
<ErrorText>: "",
<Item>: [
{
<@value>: "1",
<Postcode>: "B11 1AA",
<PostcodeFrom>: "",
<List>: "B11 1AA 280 Stratford Road, Sparkhill, BIRMINGHAM",
<Key>: "379670",
<CountryISO>: "GBR"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=search&fields=list&format=xml&Street=280%20Stratford%20Road&Town=Birmingham
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Postcode>B11 1AA</Postcode>
<PostcodeFrom/>
<List>B11 1AA 280 Stratford Road, Sparkhill, BIRMINGHAM</List>
<Key>379670</Key>
<CountryISO>GBR</CountryISO>
</Item>
</AFDPostcodeEverywhere>
Only one item will ever be returned from a Retrieve Task as you are requesting a single item, by its key, which was earlier returned in a list.
To retrieve the record selected, you should use the key
Field which will have been returned with each result.
For the correct data option to use, please see the Data Selector section (see Section 4).
Description | Example |
---|---|
Key | 379670 |
This task should be used with the specified key to retrieve the address.
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=retrieve&fields=list&format=json&key=379670
{
<Result>: "1",
<ErrorText>: "",
<Item>: [
{
<@value>: "1",
<Postcode>: "B11 1AA",
<PostcodeFrom>: "",
<List>: "B11 1AA 280 Stratford Road, Sparkhill, BIRMINGHAM",
<Key>: "379670",
<CountryISO>: "GBR"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&CountryISO=GBR&task=retrieve&fields=list&format=xml&key=379670
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Postcode>B11 1AA</Postcode>
<PostcodeFrom/>
<List>B11 1AA 280 Stratford Road, Sparkhill, BIRMINGHAM</List>
<Key>379670</Key>
<CountryISO>GBR</CountryISO>
</Item>
</AFDPostcodeEverywhere>
This functionality is available with an optional high-resolution license which will return the nearby addresses in the correct order.
This works in the same way as FastFindV4 (see Section 6.2); however, uses a special field preset of geolist
to return location data.
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&CountryISO=GBR&task=fastfindgeo&fields=geolist&lookup=280%20Stratford%20Road,Birmingham&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Postcode: "B11 1AA",
PostcodeFrom: "",
List: "280 Stratford Road, Sparkhill, BIRMINGHAM, B11 1AA",
Key: "379670",
CountryISO: "GBR",
GridE: "408834",
GridN: "284629",
Latitude: "52.4596",
Longitude: "-1.8714"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&CountryISO=GBR&task=fastfindgeo&fields=geolist&lookup=280%20Stratford%20Road,Birmingham&format=xml
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Postcode: "B11 1AA",
PostcodeFrom: "",
List: "280 Stratford Road, Sparkhill, BIRMINGHAM, B11 1AA",
Key: "379670",
CountryISO: "GBR",
GridE: "408834",
GridN: "284629",
Latitude: "52.4596",
Longitude: "-1.8714"
}
]
}
This accepts Latitude/Longitude coordinates as input and returns nearby addresses to the supplied location. This feature is most useful on mobile devices, such as mobile phones or other devices equipped with GPS.
http://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&fields=geolist&CountryISO=GBR&task=nearest&maxquantity=5&longitude=-1.8714&latitude=52.4596&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Postcode: "B11 1AA",
PostcodeFrom: "",
List: "S A Furniture, 292-294 Stratford Road, Sparkhill, BIRMINGHAM, B11 1AA",
Key: "379667",
CountryISO: "GBR",
GridE: "408836",
GridN: "284626",
Latitude: "52.4596",
Longitude: "-1.8714"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&fields=geolist&CountryISO=GBR&task=nearest&maxquantity=5&longitude=-1.8714&latitude=52.4596&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Postcode>B11 1AA</Postcode>
<PostcodeFrom/>
<List>S A Furniture, 292-294 Stratford Road, Sparkhill, BIRMINGHAM, B11 1AA</List>
<Key>379667</Key>
<CountryISO>GBR</CountryISO>
<GridE>408836</GridE>
<GridN>284626</GridN>
<Latitude>52.4596</Latitude>
<Longitude>-1.8714</Longitude>
</Item>
</AFDPostcodeEverywhere>
This functionality is available with an additional license, in Postcode Plus and Postcode Plus Business and is offered only as a Hosted solution.
AFD’s Typeahead functionality has been expanded to offer the use of What3Words. When you enter an address, the typeahead call will respond as normal regardless of what w3wMode you select. When you type in a What3words into typeahead, addresses nearest that location will be returned. What3words are recognized by typeahead due to their characteristics of three words separated with dots i.e ///word.word.word
or word.word.word
.
The API returns a W3W item at the start of the XML or JSON that provides the W3W looked up, this is useful for knowing where the result has come from. The API will accept input with or without the leading forward slashes.
AFDs What3Word functionality has two modes; These modes are enabled using the parameter &w3wMode=
Mode Number | Mode Value | Description | Example Parameter |
---|---|---|---|
0 | Auto | Used for compatibility testing. Returns the exact or first suggestion auto-lookup and is the default mode if omitted. | &w3wMode=0 or &w3wMode=Auto |
1 (Recommended) | Choices | Similar to AFDs address typeahead this mode offers auto-suggest, returning a list of suggested What3Words. From this list, the key can then be used to “retrieve” in a second call the nearest addresses for the chosen suggestion. | &w3wMode=1 or &w3wMode=Choices |
w3wmode=0
This example below will return the nearest addresses to ///almost.footsteps.flopping
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&format=json&data=address&task=fastfindv4&fields=list&uniqueid=000&lookup=almost.footsteps.flopping
{
"Result": "1",
"ErrorText": "",
"W3W": "///almost.footsteps.flopping",
"Item": [
{
"@value": "1",
"Postcode": "CA11 8SG",
"PostcodeFrom": "",
"List": "CA11 8SG Penrith Golf Club, Salkeld Road, Maidenhill, PENRITH",
"Key": "3893654",
"CountryISO": "GBR"
},
{
"@value": "2",
"Postcode": "CA11 8SF",
"PostcodeFrom": "",
"List": "CA11 8SF The Spinney, Green Lane, Greengill, PENRITH",
"Key": "3893653",
"CountryISO": "GBR"
}
]
}
w3wmode=1
This example has returned a list of suggested What3Words. This mode will not return any addresses and will return a list of suggestions even if an exact What3Words is entered. Once the What3Word has been selected a retrieve call can be made to return the nearest addresses, once you have drilled down to the addresses the key corresponding to the address can be used in a further retrieve to bring back additional address information relating to that address.
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&format=json&data=address&fields=list&task=fastfindv4&uniqueid=000&lookup=radio.pizza.bank&w3wmode=1
{
"Result": "1",
"ErrorText": "",
"Suggestion": "What3Words",
"Item": [
{
"@value": "1",
"List": "///radio.pizza.bank",
"Near": "Upminster, London",
"Key": "radio.pizza.bank"
},
{
"@value": "2",
"List": "///radio.pizza.sank",
"Near": "Queensferry, Edinburgh",
"Key": "radio.pizza.sank"
},
{
"@value": "3",
"List": "///radio.pizza.backs",
"Near": "Ingatestone, Essex",
"Key": "radio.pizza.backs"
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&format=json&Format=json&data=address&fields=list&task=retrieve&uniqueid=000&key=radio.pizza.bank&w3wmode=1
{
"Result": "1",
"ErrorText": "",
"W3W": "///radio.pizza.bank",
"Item": [
{
"@value": "1",
"Postcode": "RM14 2LX",
"PostcodeFrom": "",
"List": "RM14 2LX 21 Bridge Avenue, UPMINSTER",
"Key": "20449483///radio.pizza.bank",
"CountryISO": "GBR"
},
{
"@value": "2",
"Postcode": "RM14 2LX",
"PostcodeFrom": "",
"List": "RM14 2LX 19 Bridge Avenue, UPMINSTER",
"Key": "20449481///radio.pizza.bank",
"CountryISO": "GBR"
}
]
}...
There is an additional focus option that gives weight to What3Words nearer specified Latitude and Longitude values. This option is recommended where the end user is at the location you wish to capture, you can pass the location of the device in the latitude and longitude parameters. This call also returns the distance from the input latitude and longitude in miles and kilometres.
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&format=json&data=address&fields=list&task=fastfindv4&uniqueid=test&lookup=squad.follow.jol&w3wmode=1&longitude=-3.188267&latitude=55.953251
{
"Result": "1",
"ErrorText": "",
"Suggestion": "What3Words",
"Item": [
{
"@value": "1",
"List": "///squad.following.pull",
"Near": "Whitburn, West Lothian",
"Key": "squad.following.pull",
"Miles": "20.93",
"Km": "33.68"
},
{
"@value": "2",
"List": "///squad.follow.pools",
"Near": "Eaglesham, East Renfrewshire",
"Key": "squad.follow.pools",
"Miles": "46.18",
"Km": "74.33"
},
{
"@value": "3",
"List": "///squad.follow.kilt",
"Near": "Stranraer, Dumfries & Galloway",
"Key": "squad.follow.kilt",
"Miles": "96.70",
"Km": "155.63"
}
]
}
These are parameters that you can specify for additional functionality. The detail below outlines the parameter function and the default value if the parameter is not specified.
&noAlias
– the service returns alias localities as default.
Option | Description |
---|---|
0 | Returns Alias Localities |
1 | Returns no Alias Localities |
&useAlias
– the service returns alias properties only when specified using this parameter.
Option | Description |
---|---|
0 | Returns no Alias Properties |
1 | Returns Alias Properties |
&flatSubBuild
– the service places Flats, Units etc. in the SubBuilding field even where there is no building.
Option | Description |
---|---|
0 | Default Response |
1 | Puts flats and units in the Sub building field |
&skip
– the service does not skip any results as default.
Field Value | Description |
---|---|
None (or blank) | Returns all records matching the lookup or search criteria specified. |
Address | Only the first record per address (e.g. first listed resident) is returned. Only has any effect in Names & Numbers. |
Postcode | Only the first record per postcode is returned. |
Sector | Only the first record in each postcode sector is returned. (A postcode sector is the portion of the postcode before the space plus the first digit after it, e.g. B11 1 is a sector). |
Outcode | Only the first record per Outcode is returned. The Outcode is the portion of the postcode before the space, e.g. B11. |
Town | Only the first record per Post Town, e.g. Birmingham is returned. |
Area | Only the first record per Postcode Area is returned. A Postcode Area is the letters at the start of the postcode, e.g. B11 1AA is in Postcode Area B, IM8 is in Postcode Area IM. |
&NoSort
– this sort option is for Names & Numbers
only.
Option | Description |
---|---|
0 | Returns in number sorted order |
1 | Returns sorted by DPS |
&ApproxGrids
– works with Address Management Products Containing Grid References only.
Option | Description |
---|---|
0 | No approximations |
1 | Returns an approximate grid reference for the postal town or locality of a postcode where no postcode level grid reference exists in the data. |
2 | Returns an approximate address level grid reference where available. *Additional License Required. |
3 | Returns both approximate address and postcode level grid references where available. *Additional License Required. |
&Postzon
Option | Description |
---|---|
0 | Standard Grids returned |
1 | Return Royal Mail Postzon grid references in preference to DataTalk GeoRef grids. |
&crownISO
– this option is for Postcode Plus
only.
Option | Description |
---|---|
0 | Default Country ISO returned for Crown Dependencies (GBR) |
1 | Crown Dependancy ISO returned (IMN,JSY,GGY) |
&uprnOnly
– this option is for Postcode Plus
& Postcode Plus Business
. *Additional License Required.
Option | Description |
---|---|
0 | All addresses returned. |
1 | Returns only addresses with a UPRN. |
&SubCountryName=
– this option is for Postcode Plus
only.
Option | Description |
---|---|
England | Limits results to England only. |
Scotland | Limits results to Scotland only. |
Wales | Limits results to Wales only. |
Northern Ireland | Limits results to Northern Ireland only. |
Isle of Man | Limits results to Isle of Man only. |
Jersey | Limits results to Jersey only. |
Guernsey | Limits results to Guernsey only. |
This allows you to specify field lengths and a fixed town field as well as to optionally include the county which allows for more control over squeezing fields.
Example: addr1:60@addr2:60@addr3:60
squeezes the address fields except the postcode (property, street, locality, town) into 3 fields, concatenating fields as required to do so.
The below table gives optional fields that may help in squeezing fields:
Parameter | Description |
fixtown=(n) | Fix the town to the (n) address field |
upper(field)=1 | Sets the field to upper case. Eg uppertown=1 sets town to upper case |
includeCounty=Y | Includes the county if a dedicated county field has not already been specified |
includeCounty=S | The county is included if there is space |
includeOrg=Y | Includes the Organisation in the line squeeze |
DX is available in our Postcode Plus and Names & Numbers product
DX enables you to look up and search for DX addresses just as you can do with Royal Mail postal addresses. Uniquely, the API also allows you to easily identify DX addresses associated with a PAF address to route your mail through a DX member’s box wherever possible resulting in savings over Royal Mail.
Postcode Evolution will automatically return a DXNumber
and DXExchange
field in the XML if you have the DX data enabled.
When results are returned following any lookup or search if the address is also a DX Member the DXNumber
, DXExchange
, and DXProfession
fields will also be returned to indicate this. You can format a DX address as follows for printing:
Label | Address |
---|---|
Organisation | Gateley LLP |
DXNumber | DX 14317 |
DXExchange | MANCHESTER |
WorldAddress works similarly to our other address products. The difference in normal operation is the need to specify the Country or CountryISO code (as parameters in the GET request) of the country you wish to use in all lookup, search, and record retrieval operations. Furthermore, for a WorldAddress lookup, the initial request must contain the fields=list
parameter.
In the retrieve request, if you have opted to use Standard
, Raw PAF
, or BS7666
fields the data will be returned in the same fields as those for the UK (including the county in some cases) which you can use to store the data in your database in the same format as you do for UK addresses.
However, when it comes to generating an address label, you should note that the formatting rules for addresses vary from country to country (for example in many Western European countries the post/zip code comes before the town on the same line). Unless you have your own printing or formatting routines for the country in question, you may therefore actually prefer to use our International address format which provides both the consistent address fields (broadly the same as Raw PAF fields but also adding the Principality, Region, and Cedex which is relevant to some international addresses) as well as address label formatted fields (address1 through to address7). This enables you to both have a structure ideal for data storage and for label formatting.
If you need to store addresses in a more UK based format, but then need to format them for printing you can easily do so by carrying out a search operation specifying the address data with the International field type to obtain the address for printing at the time that you wish to generate an address label.
You can populate a drop-down list of countries in your application for the user to choose from. If you wish to have a complete list, you can do so programmatically by calling the Country List function.
&lookup=
parameter will return a full list of all countries. However, including the &lookup=
parameter returns only relevant countries. For example, &lookup=alan
will return the Aland Islands.https://pce.afd.co.uk/afddata.pce?data=address&task=ListCountries&fields=list&serial=333333&password=pwd&CountryISO=FRA&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"iso": "AFG",
"name": "Afghanistan"
},
{
"@value": "2",
"iso": "ALA",
"name": "Aland Islands"
},
{
"@value": "3",
"iso": "ALB",
"name": "Albania"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&task=ListCountries&fields=list&serial=333333&password=pwd&CountryISO=FRA&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<iso>AFG</<iso>
<name>Afghanistan</<name>
<Item>
<Item value="2">
<iso>ALA</<iso>
<name>Aland Islands</<name>
<Item>
<Item value="3">
<iso>ALB</<iso>
<name>Albania</<name>
<Item>
<AFDPostcodeEverywhere>
https://pce.afd.co.uk/afddata.pce?data=address&task=ListCountry&fields=list&serial=333333&password=pwd&CountryISO=FRA&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"iso": "AFG",
"name": "Afghanistan"
},
{
"@value": "2",
"iso": "ALA",
"name": "Aland Islands"
},
{
"@value": "3",
"iso": "ALB",
"name": "Albania"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&task=ListCountry&fields=list&serial=333333&password=pwd&CountryISO=FRA&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<iso>AFG</<iso>
<name>Afghanistan</<name>
<Item>
<Item value="2">
<iso>ALA</<iso>
<name>Aland Islands</<name>
<Item>
<Item value="3">
<iso>ALB</<iso>
<name>Albania</<name>
<Item>
<AFDPostcodeEverywhere>
https://pce.afd.co.uk/afddata.pce?data=address&task=ListCountryISO&fields=list&serial=333333&password=pwd&CountryISO=FRA&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"iso": "AFG",
},
{
"@value": "2",
"iso": "ALA",
},
{
"@value": "3",
"iso": "ALB",
}
]
}
https://pce.afd.co.uk/afddata.pce?data=address&task=ListCountryISO&fields=list&serial=333333&password=pwd&CountryISO=FRA&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<iso>AFG</<iso>
<Item>
<Item value="2">
<iso>ALA</<iso>
<Item>
<Item value="3">
<iso>ALB</<iso>
<Item>
<AFDPostcodeEverywhere>
This function requires a Names & Numbers installed license.
http://localhost:81/afddata.pce?data=list&task=ListOrganisation&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Royal%20Parks&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "ROYAL PARKS"
},
{
"@value": "2",
"List": "ROYAL PARKS AGENCY"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListOrganisation&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Royal%20Parks&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>ROYAL PARKS</List>
</Item>
<Item value="2">
<List>ROYAL PARKS AGENCY</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListProperty&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Stratford%20park&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "STRATFORD PARK"
},
{
"@value": "2",
"List": "STRATFORD PARK LEISURE CENTRE"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListProperty&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Stratford%20park&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>STRATFORD PARK</List>
</Item>
<Item value="2">
<List>STRATFORD PARK LEISURE CENTRE</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListStreet&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Stratford%20park&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "STRATFORD PARK"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListStreet&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Stratford%20park&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>STRATFORD PARK</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?
data=list&task=ListLocality&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Lee%20bank&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "LEE BANK"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListLocality&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Lee%20bank&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>LEE BANK</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListTown&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Birmingham&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "BIRMINGHAM"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListTown&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Birmingham&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>BIRMINGHAM</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListCounty&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Westminster&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "WESTMINSTER"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListCounty&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Westminster&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>WESTMINSTER</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListMailsortCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=34439&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "34439"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListMailsortCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=34439&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>34439</List>
</Item>
</AFDPostcodeEverywhere>
This function requires a Names & Numbers installed license.
http://localhost:81/afddata.pce?data=list&task=ListForename&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Joe&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "JOE"
},
{
"@value": "2",
"List": "JOE A"
},
{
"@value": "3",
"List": "JOE DAVID"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListForename&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Joe&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>JOE</List>
</Item>
<Item value="2">
<List>JOE A</List>
</Item>
<Item value="3">
<List>JOE DAVID</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListSurname&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Bloggs&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "BLOGGS"
},
{
"@value": "2",
"List": "BLOGGSY"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListSurname&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Bloggs&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>BLOGGS</List>
</Item>
<Item value="2">
<List>BLOGGSY</List>
</Item>
</AFDPostcodeEverywhere>
The Censation fields provide coding and descriptors based on Census information. The following List tasks will return all possible values returned within the Censation fields.
Censation classifies each postcode into one of 52 ‘segments’ each with its own 4 character Censation segment code.
The first letter indicates how rich or poor people living in a postcode are likely to be. Are your customers wealthy, prosperous, comfortable, striving or struggling?
The second letter in a Censation code indicates the life-stage of your customers. Young singles, young families, older families, families with children who have left home (empty nesters), or seniors.
The last two digits of a Censation code highlight distinctive characteristics drawn from the underlying Census, Residential or Commercial data or from research, residential, and transaction data. A short additional description is put in descending order with the strongest or most likely attribute first. Finally, a detailed supporting table with over 30 different characteristics is provided.
Further ‘unclassified’ codes are allocated to postcodes for which census data is unavailable. These mainly describe the make-up of commercial areas.
http://localhost:81/afddata.pce?data=list&task=ListCensationCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=AY0&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "AY04"
},
{
"@value": "2",
"List": "AY08"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListCensationCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=AY0&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>AY04</List>
</Item>
<Item value="2">
<List>AY08</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListAffluence&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=B&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "B, Prosperous"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListAffluence&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=B&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>B, Prosperous</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListLifestage&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=X&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "X, Older families"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListLifestage&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=X&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>X, Older families</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListAdditionalCensusInfo&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=11&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "11, High incomes, with many Christians, employed in finance and business services"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListAdditionalCensusInfo&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=11&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>11, High incomes, with many Christians, employed in finance and business services</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListBusiness&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Dry&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "DRY CLEANERS"
},
{
"@value": "2",
"List": "DRY CLEANING AND LAUNDRY SERVICES"
},
{
"@value": "3",
"List": "DRYSTONE WALLING"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListBusiness&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Dry&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>DRY CLEANERS</List>
</Item>
<Item value="2">
<List>DRY CLEANING AND LAUNDRY SERVICES</List>
</Item>
<Item value="3">
<List>DRYSTONE WALLING</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListSize&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=I&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "I: 501+"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListSize&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=I&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>I: 501+</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListSIC&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=841&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "84110"
},
{
"@value": "2",
"List": "84120"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListSIC&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=841&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>84110</List>
</Item>
<Item value="2">
<List>84120</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListUrbanRuralCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=A1&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "A1"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListUrbanRuralCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=A1&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>A1</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListUrbanRuralName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Urban&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "URBAN CITY AND TOWN"
},
{
"@value": "2",
"List": "URBAN MAJOR CONURBATION"
},
{
"@value": "3",
"List": "URBAN MINOR CONURBATION"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListUrbanRuralName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Urban&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>URBAN CITY AND TOWN</List>
</Item>
<Item value="2">
<List>URBAN MAJOR CONURBATION</List>
</Item>
<Item value="3">
<List>URBAN MINOR CONURBATION</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListTVRegion&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Midlands&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "MIDLANDS"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListTVRegion&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Midlands&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>MIDLANDS</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListNHSCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=7A&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "7A1"
},
{
"@value": "2",
"List": "7A2"
},
{
"@value": "3",
"List": "7A3"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListNHSCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=7A&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>7A1</List>
</Item>
<Item value="2">
<List>7A2</List>
</Item>
<Item value="3">
<List>7A3</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListNHSName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=borders&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "BORDERS"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListNHSName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=borders&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>BORDERS</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListNHSRegionCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Y2&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "Y21"
},
{
"@value": "2",
"List": "Y22"
},
{
"@value": "3",
"List": "Y23"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListNHSRegionCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Y2&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>Y21</List>
</Item>
<Item value="2">
<List>Y22</List>
</Item>
<Item value="3">
<List>Y23</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListNHSRegionName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Midlands&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "MIDLANDS AND EASTERN"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListNHSRegionName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Midlands&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>MIDLANDS AND EASTERN</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListPCTCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E3800000&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "E38000004"
},
{
"@value": "2",
"List": "E38000006"
},
{
"@value": "3",
"List": "E38000007"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListPCTCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E3800000&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>E38000004</List>
</Item>
<Item value="2">
<List>E38000006</List>
</Item>
<Item value="3">
<List>E38000007</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListPCTName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=EAST%20AND%20NORTH&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "EAST AND NORTH HERTFORDSHIRE"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListPCTName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=EAST%20AND%20NORTH&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>EAST AND NORTH HERTFORDSHIRE</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListWardCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E0500002&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "E05000026"
},
{
"@value": "2",
"List": "E05000027"
},
{
"@value": "3",
"List": "E05000028"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListWardCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E0500002&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>E05000026</List>
</Item>
<Item value="2">
<List>E05000027</List>
</Item>
<Item value="3">
<List>E05000028</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListWardName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Westhill&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "WESTHILL AND DISTRICT"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListWardName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Westhill&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>WESTHILL AND DISTRICT</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListEERCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E15&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "E15000001"
},
{
"@value": "2",
"List": "E15000002"
},
{
"@value": "3",
"List": "E15000003"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListEERCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E15&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>E15000001</List>
</Item>
<Item value="2">
<List>E15000002</List>
</Item>
<Item value="3">
<List>E15000003</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListEERName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=West%20Midlands&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "WEST MIDLANDS"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListEERName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=West%20Midlands&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>WEST MIDLANDS</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListAuthorityCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E0800000&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "E08000001"
},
{
"@value": "2",
"List": "E08000002"
},
{
"@value": "3",
"List": "E08000003"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListAuthorityCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E0800000&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>E08000001</List>
</Item>
<Item value="2">
<List>E08000002</List>
</Item>
<Item value="3">
<List>E08000003</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListAuthority&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=birmingham&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "BIRMINGHAM"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListAuthority&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=birmingham&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>BIRMINGHAM</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListLEACode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=330&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "330"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListLEACode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=330&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>330</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListLEAName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=birmingham&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "BIRMINGHAM"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListLEAName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=birmingham&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>BIRMINGHAM</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListConstituencyCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E1400053&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "E14000530"
},
{
"@value": "2",
"List": "E14000531"
},
{
"@value": "3",
"List": "E14000532"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListConstituencyCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=E1400053&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>E14000530</List>
</Item>
<Item value="2">
<List>E14000531</List>
</Item>
<Item value="3">
<List>E14000532</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListConstituency&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Birmingham&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "BIRMINGHAM, EDGBASTON"
},
{
"@value": "2",
"List": "BIRMINGHAM, ERDINGTON"
},
{
"@value": "3",
"List": "BIRMINGHAM, HALL GREEN"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListConstituency&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Birmingham&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>BIRMINGHAM, EDGBASTON</List>
</Item>
<Item value="2">
<List>BIRMINGHAM, ERDINGTON</List>
</Item>
<Item value="3">
<List>BIRMINGHAM, HALL GREEN</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=listress&task=ListDevolvedConstituencyCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=S16&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "S16000074"
},
{
"@value": "2",
"List": "S16000075"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListDevolvedConstituencyCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=S16&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>S16000074</List>
</Item>
<Item value="2">
<List>S16000075</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=ListDevolvedConstituencyName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Aberd&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "ABERDEEN CENTRAL"
},
{
"@value": "2",
"List": "ABERDEEN DONSIDE"
}
]
}
http://localhost:81/afddata.pce?data=list=address&task=ListDevolvedConstituencyName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Aberd&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>ABERDEEN CENTRAL</List>
</Item>
<Item value="2">
<List>ABERDEEN DONSIDE</List>
</Item>
</AFDPostcodeEverywhere>
http://localhost:81/afddata.pce?data=list&task=listproducts&fields=list&serial=333333&password=pwd&CountryISO=GBR&format=json
{
"Result": 1,
"ErrorText": "",
"AccountDetails": {
"Serial": "333333",
"Status": "Enabled"
},
"Products": {
"Product": [
{
"Name": "Postcode Plus",
"Data": "address"
},
{
"Name": "BankFinder",
"Data": "bank"
},
{
"Name": "Email Validation",
"Data": "email"
},
{
"Name": "Phone Validation",
"Data": "phone"
}
]
}
}
http://localhost:81/afddata.pce?data=list&task=listproducts&fields=list&serial=333333&password=pwd&CountryISO=GBR&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<AccountDetails>
<Serial>333333</Serial>
<Status>Enabled</Status>
</AccountDetails>
<Products>
<Product>
<Name>Postcode Plus</Name>
<Data>address</Data>
</Product>
<Product>
<Name>BankFinder</Name>
<Data>bank</Data>
</Product>
<Product>
<Name>Email Validation</Name>
<Data>email</Data>
</Product>
<Product>
<Name>Phone Validation</Name>
<Data>phone</Data>
</Product>
</Products>
</AFDPostcodeEverywhere>
This Task is a per postcode lookup. This will not supply a list of Alias Localities in the UK.
http://localhost:81/afddata.pce?data=list&task=ListAliasLocality&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=B13%200AA&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"List": "Alcester Lane's End"
},
{
"@value": "2",
"List": "Billesley Common"
},
{
"@value": "3",
"List": "Springfield"
}
]
}
http://localhost:81/afddata.pce?data=list&task=ListAliasLocality&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=B13%200AA&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<List>Alcester Lane's End</List>
</Item>
<Item value="2">
<List>Billesley Common</List>
</Item>
<Item value="3">
<List>Springfield</List>
</Item>
</AFDPostcodeEverywhere>
This section applies to all UK address products
These functions are used to carry out operations related to grid references and latitude and longitude values. You can convert between GB and Irish based grid references and also convert to and from latitude and longitude values. The facility to convert a value in kilometers to miles and vice-versa, return an approximate grid reference for a location and also calculate the distance between two geographical locations is also included.
To carry out a grid operation you would pass the grid or latitude and longitude to the afddata.pce?
URL on the Postcode Evolution server as described above.
Parameters | Description |
---|---|
&srcpostcode | Source Postcode – your starting point. |
&srclat | Source Latitude – your starting point. |
&srclng | Source Longitude – your starting point. |
&postcode(n) | A list of Postcodes to be provided e.g., &postcode1=&postcode2=&postcode3… |
&lat(n) | A list of Latitudes to be provided e.g., &latitude1=&latitude2=&latitude3… |
&lng(n) | A list of Longitudes to be provided e.g., &longitude1=&longitude2=&longitude3… |
&sort | You can sort by Distance or Time. |
The nearest function in the grid product can take a source postcode and then any number up to 20 additional postcodes. It will then return based on your sort, either in distance order or drivetime order, the Distance in Km and Miles, the drivetime, latitude, longitude and postcode.
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&data=grid&task=nearest&fields=standard&srcpostcode=yo11aa&postcode1=b111aa&postcode2=ka203le&sort=distance&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"Km": "216.87",
"Miles": "134.79",
"Time": "155",
"Latitude": "52.4596",
"Longitude": "-1.8714",
"Postcode": "B11 1AA",
"Key": "1"
},
{
"@value": "2",
"Km": "364.33",
"Miles": "226.43",
"Time": "269",
"Latitude": "55.6337",
"Longitude": "-4.7479",
"Postcode": "KA20 3LE",
"Key": "2"
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&data=grid&task=nearest&fields=standard&srcpostcode=yo11aa&postcode1=b111aa&postcode2=ka203le&sort=distance
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Km>216.87</Km>
<Miles>134.79</Miles>
<Time>155</Time>
<Latitude>52.4596</Latitude>
<Longitude>-1.8714</Longitude>
<Postcode>B11 1AA</Postcode>
<Key>1</Key>
</Item>
<Item value="2">
<Km>364.33</Km>
<Miles>226.43</Miles>
<Time>269</Time>
<Latitude>55.6337</Latitude>
<Longitude>-4.7479</Longitude>
<Postcode>KA20 3LE</Postcode>
<Key>2</Key>
</Item>
</AFDPostcodeEverywhere>
Parameters | Description |
---|---|
&GBGridE , &GBGridN Or&NIGridE , &NIGridN Or&Latitude , &Longitude Or&TextualLatitude , &TextualLongitude And/Or&Miles /&Km | Converts a GB or NI based grid reference, or latitude and longitude value to all other grid reference types and latitude and longitude values. |
The Convert1m
function returns grids to a 1m resolution (6-digit), whereas Convert
returns 5-digit grids. |
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=Grid&Task=Convert&Fields=Standard&GBGridE=40660&GBGridN=28650&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Lookup: "",
GBGridE: "40660",
GBGridN: "28650",
NIGridE: "61409",
NIGridN: "15357",
Latitude: "52.4764",
Longitude: "-1.9043",
TextualLatitude: "N 52°, 28' 35\"",
TextualLongitude: "W 1°, 54' 15\"",
Km: "0.0",
Miles: "0.0",
GBGridEFrom: "",
GBGridNFrom: "",
NIGridEFrom: "",
NIGridNFrom: "",
LatitudeFrom: "",
LongitudeFrom: "",
TextualLatitudeFrom: "",
TextualLongitudeFrom: ""
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=Grid&Task=Convert&Fields=Standard&GBGridE=40660&GBGridN=28650&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Lookup/>
<GBGridE>40660</GBGridE>
<GBGridN>28650</GBGridN>
<NIGridE>61409</NIGridE>
<NIGridN>15357</NIGridN>
<Latitude>52.4764</Latitude>
<Longitude>-1.9043</Longitude>
<TextualLatitude>N 52° 28' 35"</TextualLatitude>
<TextualLongitude>W 1° 54' 15"</TextualLongitude>
<Km>0.0</Km>
<Miles>0.0</Miles>
<GBGridEFrom/>
<GBGridNFrom/>
<NIGridEFrom/>
<NIGridNFrom/>
<LatitudeFrom/>
<LongitudeFrom/>
<TextualLatitudeFrom/>
<TextualLongitudeFrom/>
</Item>
</AFDPostcodeEverywhere>
Parameters | Description |
---|---|
Lookup | Looks up a town, locality, or partial postcode specified in the Lookup field and provides an approximate grid reference and latitude and longitude values for the location if a match is found. Multiple matches may be returned if the location is ambiguous. |
The LookupLocation1m
function returns grids to a 1m resolution (6-digit), whereas LookupLocation
returns 5-digit grids. |
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=Grid&Task=LookupLocation&Fields=Standard&Lookup=Isle%20of%20man&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Lookup: "Isle of Man, IM",
GBGridE: "23770",
GBGridN: "47560",
NIGridE: "42961",
NIGridN: "32811",
Latitude: "54.1505",
Longitude: "-4.4866",
TextualLatitude: "N 54°, 9' 1\"",
TextualLongitude: "W 4°, 29' 11\"",
Km: "",
Miles: "",
GBGridEFrom: "",
GBGridNFrom: "",
NIGridEFrom: "",
NIGridNFrom: "",
LatitudeFrom: "",
LongitudeFrom: "",
TextualLatitudeFrom: "",
TextualLongitudeFrom: ""
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=Grid&Task=LookupLocation&Fields=Standard&Lookup=Isle%20of%20man&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Lookup>Isle of Man, IM</Lookup>
<GBGridE>23770</GBGridE>
<GBGridN>47560</GBGridN>
<NIGridE>42961</NIGridE>
<NIGridN>32811</NIGridN>
<Latitude>54.1505</Latitude>
<Longitude>-4.4866</Longitude>
<TextualLatitude>N 54° 9' 1"</TextualLatitude>
<TextualLongitude>W 4° 29' 11"</TextualLongitude>
<Km/>
<Miles/>
<GBGridEFrom/>
<GBGridNFrom/>
<NIGridEFrom/>
<NIGridNFrom/>
<LatitudeFrom/>
<LongitudeFrom/>
<TextualLatitudeFrom/>
<TextualLongitudeFrom/>
</Item>
</AFDPostcodeEverywhere>
Parameters | Description |
---|---|
lat1 , lng1 and lat2 , lng2 , etc. | Addition of multiple way points |
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=grid&Task=distancemulti&fields=standard&lat1=57.1496&lng1=-2.0969&lat2=55.7433&lng2=-4.1996&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Km: "248.47",
Miles: "154.42",
Time: "179"
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=grid&Task=distancemulti&fields=standard&lat1=57.1496&lng1=-2.0969&lat2=55.7433&lng2=-4.1996&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Km>248.47</Km>
<Miles>154.42</Miles>
<Time>179</Time>
</Item>
</AFDPostcodeEverywhere>
Parameters | Description |
---|---|
&GBGridE , &GBGridN Or &NIGridE , &NIGridN Or &Latitude , &Longitude AND: &GBGridEFrom , &GBGridNFrom Or &NIGridEFrom , &NIGridNFrom Or &LatitudeFrom , &LongitudeFrom | Calculates the distance between a pair of grid references or latitude and longitude values specified. You will need to set a grid or latitude and longitude value in both the normal fields and those prefixed with “From” to find the distance in both Miles and Km. The |
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=Grid&Task=Distance&Fields=Standard&GBGridEFrom=40650&GBGridNFrom=28550&GBGridE=40660&GBGridN=28650&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Lookup: "",
GBGridE: "40660",
GBGridN: "28650",
NIGridE: "61409",
NIGridN: "15357",
Latitude: "52.4764",
Longitude: "-1.9043",
TextualLatitude: "N 52°, 28' 35\"",
TextualLongitude: "W 1°, 54' 15\"",
Km: "1.0",
Miles: "0.6",
Time: "",
GBGridEFrom: "40650",
GBGridNFrom: "28550",
NIGridEFrom: "61407",
NIGridNFrom: "15257",
LatitudeFrom: "52.4674",
LongitudeFrom: "-1.9057",
TextualLatitudeFrom: "N 52°, 28' 2\"",
TextualLongitudeFrom: "W 1°, 54' 20\""
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&UserID=MyApp&Data=Grid&Task=Distance&Fields=Standard&GBGridEFrom=40650&GBGridNFrom=28550&GBGridE=40660&GBGridN=28650&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Lookup/>
<GBGridE>40660</GBGridE>
<GBGridN>28650</GBGridN>
<NIGridE>61409</NIGridE>
<NIGridN>15357</NIGridN>
<Latitude>52.4764</Latitude>
<Longitude>-1.9043</Longitude>
<TextualLatitude>N 52° 28' 35"</TextualLatitude>
<TextualLongitude>W 1° 54' 15"</TextualLongitude>
<Km>1.0</Km>
<Miles>0.6</Miles>
<Time/>
<GBGridEFrom>40650</GBGridEFrom>
<GBGridNFrom>28550</GBGridNFrom>
<NIGridEFrom>61407</NIGridEFrom>
<NIGridNFrom>15257</NIGridNFrom>
<LatitudeFrom>52.4674</LatitudeFrom>
<LongitudeFrom>-1.9057</LongitudeFrom>
<TextualLatitudeFrom>N 52° 28' 2"</TextualLatitudeFrom>
<TextualLongitudeFrom>W 1° 54' 20"</TextualLongitudeFrom>
</Item>
</AFDPostcodeEverywhere>
AFD BankFinder® provides a simple way to get full information about a Banks details including the Postal address, and for banks on the UK clearing system the BACS (Bankers Automated Clearing Service), CHAPS (Clearing Houses Automated Payment System), FPS (Faster Payments Service) and C&CCC (Cheque and Credit Clearing Company) information. BankFinder also provides verification of Account Numbers and Debit / Credit Card Numbers and the transcribing of non-standard account numbers to help eliminate errors when capturing users’ payment details.
In addition to this BankFinder Plus provides a solution for CoP (Confirmation of Payee), CoP allows a payer to check that the name (including whether that name is associated with a personal or business account) they give for a new payee is the same as the account name and type held by the payee’s payment service provider. Please note payment service providers have different validation criteria.
● = Field returned by this product and fully searchable
⚬ = Field returned by this product, but not searchable
Please note that the Field Lengths are only guidelines and are not limits.
Field Name | Field Length | Data Type | Description | BankFinder |
---|---|---|---|---|
Key | 40 | Numeric | Unique Identifier of this record | ● |
List | 512 | Text | Provides a list item formatted to be added to a list box for this record | ⚬ |
SortCode | 6 | Numeric | Bank’s Sort code | ● |
BankBIC | 8 | Text | Bank BIC Code | ● |
BranchBIC | 3 | Text | Branch BIC Code | ● |
SubBranchSuffix | 2 | Numeric | Allows a branch to be uniquely identified where there is a cluster of branches sharing the same Sort Code | ⚬ |
ShortBranchTitle | 27 | Text | The official title of the branch | ● |
CentralBankCountryCode | 2 | Numeric | The ISO Country code for beneficiary banks in other countries | ⚬ |
CentralBankCountryName | 20 | Text | The country name corresponding to the ISO code given | ⚬ |
SupervisoryBodyCode | 1 | Numeric | Indicates the supervisory body for an institution that is an agency in any of the clearings | ⚬ |
SupervisoryBodyName | 50 | Text | The name of the supervisory body | ⚬ |
DeletedDate | 10 | Text | Specifies the date the branch was closed if it is not active | ⚬ |
BranchType | 20 | Text | The branch type – Main Branch, Sub or NAB Branch, Linked Branch | ⚬ |
BranchName | 35 | Text | Defines the actual name or place of the branch | ⚬ |
FullBranchTitle | 105 | Text | Extended title for the institution | ⚬ |
Location | 60 | Text | Where present, this field indicates the physical location of the branch | ● |
AlternativeBranchName | 35 | Text | An alternative name or place for the branch where applicable | ● |
MainBranchSortCode | 6 | Numeric | Set for linked branches in a cluster. It identifies the main branch for the cluster. For IPSO records this is set to the branch that would handle transactions for this sort code when the branch has been amalgamated with another | ⚬ |
BuildingSocietyName | 70 | Text | For building society accounts requiring a roll number this will contain the name of the receiving building society as this sometimes differs from the bank branch that the payment passes through | ⚬ |
OwnerBankShortName | 20 | Text | Short version of the name of the Owning Bank | ● |
OwnerBankFullName | 70 | Text | Full version of the name of the Owning Bank | ● |
OwnerBankCode | 4 | Numeric | The four-digit bank code of the Owning Bank | ⚬ |
Organisation | 120 | Text | Owner Bank Full Name | ● |
Property | 65 | Text | Bank Postal Address: Property (Building) | ⚬ |
Street | 60 | Text | Bank Postal Address: Street | ⚬ |
Locality | 60 | Text | Bank Postal Address: Locality | ⚬ |
Town | 30 | Text | Bank Postal Address: Town | ● |
County | 30 | Text | Bank Postal Address: County (Optional) | ⚬ |
Postcode | 8 | Text | The Royal Mail Postcode for this address | ● |
Phone | 20 | Numeric | Phone Number for this bank | ● |
Phone2 | 20 | Numeric | Additional Phone Number for this bank | ● |
Fax | 20 | Numeric | Fax Number for this bank (IPSO only) | ⚬ |
ClearingSystem | 25 | Text | Clearing system for this record | ⚬ |
BACSStatus | 5 | Text | Indicates the BACS Clearing Status | ⚬ |
BACSStatusDescription | 60 | Text | Date on which BACS data was last amended | ⚬ |
BACSClosedClearing | 10 | Text | Indicates the date the branch was closed in BACS clearing if applicable | ⚬ |
BACSRedirectedFromFlag | 1 | Numeric | Set to R if other branches are redirected to this sort code | ⚬ |
BACSRedirectedToSortCode | 6 | Numeric | This specifies the sort code to which BACS should redirect payments addressed to this sort code if applicable | ⚬ |
BACSSettlementBankCode | 4 | Numeric | BACS Bank Code of the bank that will settle payments for this branch | ⚬ |
BACSSettlementBankShortName | 20 | Text | Short form name of the settlement bank | ⚬ |
BACSSettlementBankFullName | 70 | Text | Full form name of the settlement bank | ⚬ |
BACSSettlementBankSection | 2 | Numeric | Numeric data required for BACS to perform it’s settlement | ⚬ |
BACSSettlementBankSubSection | 2 | Numeric | Numeric data required for BACS to perform it’s settlement | ⚬ |
BACSHandlingBankCode | 4 | Numeric | BACS Bank Code of the member that will take BACS output from this branch | ⚬ |
BACSHandlingBankShortName | 20 | Text | Short form name of the handling bank | ⚬ |
BACSHandlingBankFullName | 70 | Text | Full form name of the handling bank | ⚬ |
BACSHandlingBankStream | 2 | Numeric | Numeric code defining the stream of output within the Handling Bank that will be used or payments to this branch | ⚬ |
BACSAccountNumbered | 1 | Numeric | Set to 1 if numbered bank accounts are used | ⚬ |
BACSDDIVoucher | 1 | Numeric | Set to 1 if Paper Vouchers have to be printed for Direct Debit Instructions | ⚬ |
BACSDirectDebits | 1 | Numeric | Set to 1 if branch accepts Direct Debits | ⚬ |
BACSBankGiroCredits | 1 | Numeric | Set to 1 if branch accepts Bank Giro Credits | ⚬ |
BACSBuildingSocietyCredits | 1 | Numeric | Set to 1 if branch accepts Building Society Credits | ⚬ |
BACSDividendInterestPayments | 1 | Numeric | Set to 1 if branch accepts Dividend Interest Payments | ⚬ |
BACSDirectDebitInstructions | 1 | Numeric | Set to 1 if branch accepts Direct Debit Instructions | ⚬ |
BACSUnpaidChequeClaims | 1 | Numeric | Set to 1 if branch accepts Unpaid Cheque Claims | ⚬ |
CHAPSPStatus | 1 | Numeric | Indicates the CHAPS Sterling clearing Status | ⚬ |
CHAPSPStatusDescription | 80 | Text | Provides a description for the status | ⚬ |
CHAPSPLastChange | 10 | Text | Date on which CHAPS Sterling data was last amended | ⚬ |
CHAPSPClosedClearing | 10 | Text | Indicates the date the branch is closed in CHAPS Sterling clearing if applicable | ⚬ |
CHAPSPSettlementBankCode | 3 | Numeric | CHAPS ID of the bank that will settle payments for this branch | ⚬ |
CHAPSPSettlementBankShortName | 20 | Text | Short form of the name of the settlement bank | ⚬ |
CHAPSPSettlementBankFullName | 70 | Text | Full form of the name of the settlement bank | ⚬ |
CCCCStatus | 1 | Numeric | Indicates the C&CCC clearing Status | ⚬ |
CCCCStatusDescription | 40 | Text | Provides a description for the status | ⚬ |
CCCCLastChange | 6 | Numeric | Date on which C&CCC data was last amended | ⚬ |
CCCCClosedClearing | 30 | Text | Indicates the date the branch is closed in C&CCC clearing if applicable | ⚬ |
CCCCSettlementBankCode | 3 | Numeric | BACS generated code of the bank that will settle payments for this branch | ⚬ |
CCCCSettlementBankShortName | 20 | Text | Short form of the name of the settlement bank | ⚬ |
CCCCSettlementBankFullName | 70 | Text | Full form of the name of the settlement bank | ⚬ |
CCCCDebitAgencySortCode | 50 | Numeric | When the Status field is set to ‘D’ this specifies where cheque clearing is handled for this branch | ⚬ |
CCCCReturnIndicator | 6 | Numeric | Set if this is the branch that other banks should return paper to. It will only be set for a sort code of a Member | ⚬ |
CCCCGBNIIndicator | 1 | Text | Indicates for C&CCC purposes if the office is in mainland Great Britain (GB) or Northern Ireland (NI) | ⚬ |
FPSStatus | 1 | Text | Indicates if the branch can accept FPS payments and whether or not it is an agency | ⚬ |
FPSStatusDescription | 60 | Text | The description for the FPStatus field | ⚬ |
FPSLastChange | 10 | Text | The date on which FPS data for this record was last amended | ⚬ |
FPSClosedClearing | 10 | Text | The date when the status of the branch was set to ‘N’ (does not accept FPS payments) if applicable | ⚬ |
FPSRedirectedFromFlag | 1 | Text | If the branch is set as the redirection sort code for one or more bank offices this will be indicated here | ⚬ |
FPSRedirectToSortCode | 6 | Numeric | If output destined for this sort code has been redirected the sort code to redirect payment too will be displayed here | ⚬ |
FPSSettlementBankCode | 4 | Numeric | The Bank code of the FPS member that settles the FPS output for this sort code | ⚬ |
FPSSettlementBankShortName | 20 | Text | The short name that goes with the above code | ⚬ |
FPSSettlementBankFullName | 70 | Text | The full name that goes with the above code | ⚬ |
FPSSettlementBankConnection | 2 | Numeric | Two-digit connectivity code for settlement | ⚬ |
FPSHandlingBankCode | 4 | Numeric | The Bank code of the FPS member that handles the FPS output for this sort code | ⚬ |
FPSHandlingBankShortName | 20 | Text | The short name that goes with the above code | ⚬ |
FPSHandlingBankFullName | 70 | Text | The full name that goes with the above code | ⚬ |
FPSHandlingBankConnection | 2 | Numeric | Two-digit connectivity code for handling | ⚬ |
FPSAccountNumberedFlag | 1 | Numeric | Set to Y is bank office has transferrable account numbers. N if it does not | ⚬ |
FPSAgencyType | 1 | Text | Indicates if the Bank office is a direct agency (D) or an indirect agency (I) | ⚬ |
FPSAgencyTypeDescription | 60 | Text | The description for the above code, i.e., the code field has D/I that has a human-readable text version | ⚬ |
Field Name | Field Length | Data Type | Description | BankFinder |
---|---|---|---|---|
ResultText* | 255 | string | Status description of the validation | ⚬ |
CustomerName | 138 | string | Name provided for validation | ⚬ |
Sortcode | 6 | string | Validated Sort code | ⚬ |
AccountNumber | 8 | string | Validated Account Number | ⚬ |
IBAN | string | Validated IBAN | ⚬ | |
RollNumber | string | Validated Roll Number | ⚬ | |
TypeOfAccount | string | Single digit value required for submission to BACS for some account numbers | ⚬ | |
ClearingSystem | string | Indicates which clearing system(s) the account on | ⚬ | |
ReturnedCustomerName | 150 | string | Corrected customer name for close matches | ⚬ |
NameMatchResult | 11 | string | Indicates whether the customer name is a full, close or no match | ⚬ |
AccountTypeResult** | 5 | boolean | Indicates if the account type is correct | ⚬ |
ReasonCode* | 7 | string | Response code of the validation | ⚬ |
*see ‘Bank Finder Plus Reason Code & Description’ table for available responses
**The Account Type Result is only confirmed where the name is a match
ReasonCode | Result Text |
---|---|
MATC | The account name provided is a match. |
ANNM | The account name provided is not the same as the name held on the Account. |
MBAM | The account name provided is not the same as the name held on the Account. It’s a close match. |
BANM | The account name provided is a match but the account is a Business Account not a Personal one. |
PANM | The account name provided is a match but the account is a Personal Account not a Business one. |
BAMM | This is a Business Account not a Personal one. The account name provided is not the same, it’s a close match. |
PAMM | This is a Personal Account not a Business one. The account name provided is not the same, it’s a close match. |
IVCR | The secondary reference details supplied were not found. Please check details with recipient. |
ACNS | Unable to check the name as the type of account is not supported for CoP checks. This response is also received if the account expects a secondary reference but one was not included. |
OPTO | Unable to check the name as the account holder has opted out of the CoP scheme. |
CASS | The Account has been switched, please contact the recipient for updated Account details. |
SCNS | The request has been routed to a responder who does not own the sort code. This would only normally happen due to an issue with the CoP directory, not anything in the request message. This is also the message we return if we cannot find the sort code in the directory to route the request to the right responder. |
SECMISS | The account details provided require a Secondary Reference value before the name can be checked. Please check with recipient. |
FOURHUN | 400 Error Occurred – Unable to check the name, try again later. |
HTTPERR | HTTP Error occurred Unable to check the name, try again later. |
TOOMANY | Too Many Requests to Partner Banks – Please try again later. |
NOROUTE | Unable to find a Participant Bank to handle this request. |
The table below describes the possible result codes and error messages when using the bank
data product:
Result Code | Description |
---|---|
2 | Validation Not Available |
1 | Successful |
-7 | Data License Error |
-12 | Sort Code Not Found |
-13 | Invalid Sort Code |
-14 | Invalid Account Number |
-15 | Invalid Expiry Date |
-16 | Card Expired |
-18 | Invalid Card Number |
-19 | Visa ATM Only |
-20 | Unrecognised Card Type |
-21 | Invalid Roll Number |
-22 | Invalid IBAN |
-23 | Unrecognised Country |
-24 | IBAN Mismatch |
Result Code | Description |
---|---|
1 | Full Match |
2 | Correct bank details, name corrected or not matched |
-12 | Sort Code Not Found |
-13 | Invalid Sort Code |
-14 | Invalid Account Number |
-22 | Invalid IBAN |
-25 | One or more validation errors occurred (e.g. Account Type field is blank) |
Lookup Tasks are a group of different calls that each accepts only one search parameter, specified using a Lookup
string.
Description | Example |
---|---|
GBR Sort Code | 401101 |
IRL Sort Code | 930008 |
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=lookup&clearing=all&fields=list&lookup=401101&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Key: "4011010",
List: "401101 Solihull, HSBC UK Bank PLC, Birmingham"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=lookup&clearing=all&fields=list&lookup=401101&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Key>4011010</Key>
<List>401101 Solihull, HSBC UK Bank PLC, Birmingham</List>
</Item>
</AFDPostcodeEverywhere>
Description | Example |
---|---|
BranchName, SortCode | Pudsey,560036 |
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=propertyLookup&clearing=all&fields=list&lookup=Pudsey,560036&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Key: "5600366",
List: "560036 Pudsey, Nat West Bank PLC, Bradford"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=propertyLookup&clearing=all&fields=list&lookup=Pudsey,560036&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Key>5600366</Key>
<List>560036 Pudsey, Nat West Bank PLC, Bradford</List>
</Item>
</AFDPostcodeEverywhere>
Used to lookup bank data from a lookup string, for example, a sort code or bank and branch name, e.g. 560036
.
The Search task accepts multiple strings as input, and if successful returns one or more records. The input can be a postcode, or an address element, or a combination of these separated by a comma.
Description | Example |
---|---|
Organisation | HSBC Bank PLC |
Organisation, Town | HSBC, BIRMINGHAM |
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=fastfind&clearing=all&fields=list&lookup=HSBC,%20BIRMINGHAM&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Key: "4011010",
List: "401101 Solihull, HSBC UK Bank PLC, Birmingham"
},
{
@value: "2",
Key: "4011020",
List: "401102 Birmingham, New Street, HSBC UK Bank PLC, Birmingham"
},
]
}
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=fastfind&clearing=all&fields=list&lookup=HSBC,%20BIRMINGHAM&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Key>4011010</Key>
<List>401101 Solihull, HSBC UK Bank PLC, Birmingham</List>
</Item>
<Item value="2">
<Key>4011020</Key>
<List>401102 Birmingham, New Street, HSBC UK Bank PLC, Birmingham</List>
</Item>
</AFDPostcodeEverywhere>
Search
string. It searches for matching bank records based on specific search criteria.
The Search task accepts multiple strings as input, and if successful returns one or more records. The input can be a postcode, or an address element, or a combination of these separated by a comma.
Another way to do searches is to use any of the fields when using &fields=standard
.
Descriptions | Example |
---|---|
Searchable Field | &Organisation=RBS&Town=Birmingham |
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=search&clearing=all&fields=list&organisation=RBS&town=Birmingham&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Key: "413590",
List: "041359 Optimus Cards UK Limited, Optimus Cards, Birmingham"
},
{
@value: "2",
Key: "502460",
List: "050246 Yorkshire Bank Bft 2, Yorkshire Bank"
},
]
}
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=search&clearing=all&fields=list&organisation=RBS&town=Birmingham&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Key>413590</Key>
<List>041359 Optimus Cards UK Limited, Optimus Cards, Birmingham</List>
</Item>
<Item value="2">
<Key>502460</Key>
<List>050246 Yorkshire Bank Bft 2, Yorkshire Bank</List>
</Item>
</AFDPostcodeEverywhere>
A retrieve is a call that returns individual address information specified using the key
value, for example, when selected from a list.
Description | Example |
---|---|
Solihull, HSBC UK Bank PLC, Birmingham | 4011010 |
International Banking Services | 93000890 |
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=retrieve&clearing=all&fields=list&key=4011010&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Key: "4011010",
List: "401101 Solihull, HSBC UK Bank PLC, Birmingham"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=retrieve&clearing=all&fields=list&key=4011010&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Key>4011010</Key>
<List>401101 Solihull, HSBC UK Bank PLC, Birmingham</List>
</Item>
</AFDPostcodeEverywhere>
This task provides the ability to validate a sort code and account number. It checks that the account number is valid for the branch of the bank to which the sort code belongs.
This does not guarantee that the account number exists or sufficient funds exist for any transaction but greatly cuts down on errors due to incorrectly entered numbers.
The Task will also translate any non-standard account numbers (e.g. a 10-digit account number).
You can also supply a Roll Number in the case of crediting some building society accounts which require one which will also be checked.
If the account number is invalid, the Result field returned will be set to a value less than zero and the ErrorText will contain a corresponding error message.
Assuming no error occurred, you can assume the account number is valid but should read the SortCode
, AccountNumber
, IBAN
, and RollNumber
(if required) and TypeOfAccount
parameters in-case the number has been translated.
If the return value is 1
then the account number has been validated, if the return value is 2
then account numbers on this sort code cannot be validated and so the number should still be treated as valid. This return code is provided so you can carry out an additional check on the account number, e.g. asking a customer on the phone to repeat it, checking it has been entered from a paper form correctly, etc. if you wish to do so.
Note that the only Field type valid for validating account numbers is Standard as the result contains no address. Only a single result will ever be returned so there is no need to list results.
Should you also wish to check the branch details match those that the customer has supplied, check the transaction types allowed at this branch, or obtain the address to use for this branch (may not be the branch physical location) then you can carry out a lookup for the sort code to obtain the branch information.
Description | Example |
---|---|
SortCode, Account | 774814, 24782346 |
IBAN | GB58 TSBS 7748 1424 7823 46 |
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=account&clearing=all&fields=account&sortcode=774814&accountnumber=24782346&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"@value": "1",
"SortCode": "774814",
"AccountNumber": "24782346",
"RollNumber": "",
"TypeOfAccount": "0",
"ClearingSystem": "United Kingdom (BACS)",
"IBAN": "GB58 TSBS 7748 1424 7823 46"
}
]
}
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=account&clearing=all&fields=account&sortcode=774814&accountnumber=24782346&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<SortCode>774814</SortCode>
<AccountNumber>24782346</AccountNumber>
<RollNumber/>
<TypeOfAccount>0</TypeOfAccount>
<ClearingSystem>United Kingdom (BACS)</ClearingSystem>
<IBAN>GB58 TSBS 7748 1424 7823 46</IBAN>
</Item>
</AFDPostcodeEverywhere>
This Task provides the ability to validate a card number, and optionally check that an expiry date indicates that the card is in-date. It checks that the card number is a valid one for the type of card and can indicate the card type. This does not guarantee that the card exists or that a transaction will be authorized, but greatly cuts down on errors due to incorrectly entered numbers.
If the card number is invalid, the Result
field returned will be set to a value less than zero and the ErrorText
will contain a corresponding error message.
Assuming no error occurred, you can assume the card number is valid. If you wish to determine the card type, the CardType
field will hold this information.
Description | Example |
---|---|
Card Number | 4903005748392742 |
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=card&clearing=all&fields=card&cardnumber=4903%200057%204839%202742&expirydate=01/25&format=json
{
Result: "-19",
ErrorText: "Visa ATM Card Only"
}
https://pce.afd.co.uk/afddata.pce?data=bank&serial=333333&password=pwd&task=card&clearing=all&fields=card&cardnumber=4903%200057%204839%202742&expirydate=01/25&format=xml
<AFDPostcodeEverywhere>
<Result>-19</Result>
<ErrorText>Visa ATM Card Only</ErrorText>
</AFDPostcodeEverywhere>
The Payee Task performs a CoP check on the Account Type, Supplied Name, Sortcode, and Account Number for UK bank accounts.
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&Data=Bank&Task=payee&Fields=Account&Clearing=all&CustomerName=Joe%20Bloggs&AccountType=Personal&Sortcode=123456&AccountNumber=12345678&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"ResultText": "The account name provided is a match.",
"@value": "1",
"CustomerName": "Joe Bloggs",
"Sortcode": "123456",
"AccountNumber": "12345678",
"IBAN": "GBXX XXXX 1234 5612 3456 78",
"RollNumber": "",
"TypeOfAccount": "0",
"ClearingSystem": "United Kingdom (BACS)",
"ReturnedCustomerName": "",
"NameMatchResult": "Full",
"AccountTypeResult": "true",
"ReasonCode": "MATC"
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&Data=Bank&Task=payee&Fields=Account&Clearing=all&CustomerName=Joe%20Bloggs&AccountType=Personal&Sortcode=123456&AccountNumber=12345678&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText />
<ResultText>The account name provided is a match.</ResultText>
<value>1</value>
<CustomerName>Joe Bloggs</CustomerName>
<Sortcode>123456</Sortcode>
<AccountNumber>12345678</AccountNumber>
<RollNumber />
<TypeofAccount>0</TypeofAccount>
<ClearingSystem>United Kingdom (BACS)</ClearingSystem>
<IBAN>GBXX XXXX 1234 5612 3456 78</IBAN>
<ReturnedCustomerName />
<NameMatchResult>Full</NameMatchResult>
<AccountTypeResult>true</AccountTypeResult>
<ReasonCode>MATC</ReasonCode>
</AFDPostcodeEverywhere>
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&Data=Bank&Task=payee&Fields=Account&Clearing=all&CustomerName=Joe%20Bloggs&AccountType=Personal&IBAN=GBXXXXXX12345612345678&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
"ResultText": "The account name provided is a match.",
"@value": "1",
"CustomerName": "Joe Bloggs",
"Sortcode": "123456",
"AccountNumber": "12345678",
"IBAN": "GBXX XXXX 1234 5612 3456 78",
"RollNumber": "",
"TypeOfAccount": "0",
"ClearingSystem": "United Kingdom (BACS)",
"ReturnedCustomerName": "",
"NameMatchResult": "Full",
"AccountTypeResult": "true",
"ReasonCode": "MATC"
}
]
}
https://pce.afd.co.uk/afddata.pce?serial=333333&password=pwd&Data=Bank&Task=payee&Fields=Account&Clearing=all&CustomerName=Joe%20Bloggs&AccountType=Personal&IBAN=GBXXXXXX12345612345678&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText />
<ResultText>The account name provided is a match.</ResultText>
<value>1</value>
<CustomerName>Joe Bloggs</CustomerName>
<Sortcode>123456</Sortcode>
<AccountNumber>12345678</AccountNumber>
<RollNumber />
<TypeofAccount>0</TypeofAccount>
<ClearingSystem>United Kingdom (BACS)</ClearingSystem>
<IBAN>GBXX XXXX 1234 5612 3456 78</IBAN>
<ReturnedCustomerName />
<NameMatchResult>Full</NameMatchResult>
<AccountTypeResult>true</AccountTypeResult>
<ReasonCode>MATC</ReasonCode>
</AFDPostcodeEverywhere>
This section describes the Refiner product tasks for cleansing address information.
This product requires a Refiner API
license.
You will need to set address fields in your structure to specify the address to be cleaned. These do not need to match up to the actual fields. For example, if you have Address Line 1, Address Line 2, Address Line 3, and Postcode in your database you could set these to Property, Street, Locality, and Postcode fields in the structure and they will be cleaned and returned in the correct named fields when matched. Note that if you set any non-address fields they will be ignored (please see Input and Output table for the list of fields that Refiner will use).
The request will return a negative value (less than zero) in the case where an address cannot be fully matched. This could be because the address was unmatchable, a non-UK address, or an ambiguous result was found (see Result Codes). An address will still be returned as this will include the address with Field Placement correction, which you can use if you desire.
Where the function returns a positive value (greater than zero) this means that the address has been uniquely matched. You may still like to examine the return value as this will give details as to the level to which the address was matched (see Result Codes). Many other fields are also available with additional non-address data, which you may require.
In the case of an ambiguous or suggested result (see Result Codes), the first address returned from the function will be the original address with field placement. For non-batch processes, you may wish to present a list of addresses for the user to choose from and in this case, you can continue to call the request as above repeatedly with the same operation code as before.
Refiner will take address field input in the following format:
Input Fields | Description |
---|---|
Address(n) | (where n is 1 to 10) which allows address data to be sent in |
UDPRN | which specifies a UDPRN number of a record |
UPRN | which specifies an OS UPRN number (optional dataset available) |
Other Fields | Fields which specify a list of fields to output |
Refiner will output the following fields:
Output Fields | Description |
---|---|
Result Code | Indicates the status of the match (see Result Codes) |
Closeness | Indicates how close the original address is to the PAF Matched address on a percentage scale |
Other Fields | Fields specified in the preset which include all fields supported by Postcode Plus with the addition of Address(n) (where n is 1 to 10) as the address data output (each line in a separate field) |
The possible field string, which determines what data is output in addition to the fields above:
Organisation@Property@Street@Locality@Town@PostalCounty@Postcode
Organisation@addr1:60@addr2:60@addr3:60@addr4:60@Postcode
The below table describes the possible result codes and error messages:
Result Code | Description |
---|---|
100 | Complete Match – Full Address matches identically. |
200 | Corrected Match – Address verified from the Postcode and matches a record with some correction. |
201 | Changed Postcode Match – Address verified from a postcode that was change due to a Royal Mail recoding and now matches. |
202 | Assume Postcode Correct – Property Match assuming the postcode is correct. |
203 | Assume Changed Postcode Correct – Property Match with Changed Postcode assuming the original postcode is correct. |
204 | Postcode Match (non-matched property added in). |
205 | Postcode Match (postcode changed and non-matched property added in). |
300 | Full DPS Match (Different postcode returned) – Address verified with some correction, looking wider than just the specified Postcode. |
301 | Full DPS Match – Address verified. Multiple PAF delivery point records exist for this address and the organisation could not be matched. As a result the specific DPS/UDPRN could not be returned. |
400* | Street Match – Address verified to Street Level, i.e. the property was not matched, but a unique match to the street was identified on a single postcode. *When no street is present, the address is verified to Locality Level, i.e. rural areas like villages, etc. |
-1 | No Match Found – Refiner has been unable to match this record. |
-2 | Ambiguous Postcode – Refiner has matched this record to Street Level but cannot determine which is the correct Postcode. |
-3 | Suggested Record – Refiner has found a unique possible match for this record but there is not enough address data to reliably match it. |
-4 | Ambiguous Address – Refiner has given several possibilities that this address could match to. |
-5 | International Address – This address was detected as being an International Address and therefore cannot be cleaned as data is only present for cleaning UK, Channel Isles and Isle of Man addresses. |
-6 | No Address Data Supplied – No record data was supplied. Refiner cannot clean this address as no address data was given. |
-7 | Data License Error |
http://localhost:81/v1/refiner/GBR/clean?serial=333333&password=pwd&fields=organisation@property@street@locality@town@county@postcode@list&address1=AFD%20Software%20Ltd&address2=&address3=Lezayre,%20Ramsey&address4=&address5=Isle%20of%20Man&address6=&address7=IM7%202DZ
{
ResultCode: 200,
Closeness: 66,
organisation: "A F D Software Ltd",
property: "Mountain View Innovation Centre",
street: "Jurby Road",
locality: "Lezayre, Ramsey",
town: "Isle of Man",
county: "",
postcode: "IM7 2DZ",
list: "IM7 2DZ A F D Software Ltd, Mountain View Innovation Centre, Jurby Road, Lezayre, Ramsey, ISLE OF MAN",
udprn: "53708644"
}
http://localhost:81/v1/refiner/GBR/clean?serial=333333&password=pwd&fields=organisation@property@street@locality@town@county@postcode@list&address1=AFD%20Software%20Ltd&address2=&address3=Lezayre,%20Ramsey&address4=&address5=Isle%20of%20Man&address6=&address7=IM7%202DZ&format=XML
<AFDPostcodeEverywhere>
<Result>200</Result>
<ErrorText>Postcode Match</ErrorText>
<Item value="1">
<Closeness>66</Closeness>
<organisation>A F D Software Ltd</organisation>
<property>Mountain View Innovation Centre</property>
<street>Jurby Road</street>
<locality>Lezayre, Ramsey</locality>
<town>Isle of Man</town>
<county/>
<postcode>IM7 2DZ</postcode>
<list>IM7 2DZ A F D Software Ltd, Mountain View Innovation Centre, Jurby Road, Lezayre, Ramsey, ISLE OF MAN</list>
<udprn>53708644</udprn>
</Item>
</AFDPostcodeEverywhere>
Parameter | Description |
---|---|
FieldName(n)=(value) | (where n is 1 to 10) which allows the field name to be specified (when known) for the data, valid values are Organisation, Property, HouseNumber, Street, Locality, Town, County, and Postcode. |
AttachMode=1 | Used to simply attach data based on the postcode, doesn’t verify the address. |
PostcodeOnly=1 | If it can, it will verify an address purely using the postcode (returning only 100/200 result codes). |
FullMatch=1 | Only returns full PAF matches, i.e. if the property is not on PAF, a street-level match will not be offered. |
Speed=1 | Skips slower portions of processing (lowers match rate but improves performance). |
Interactive=1 | Specifies the address is being returned to a user interactively to check. (For example, when a user has entered an address manually and the suggested address is displayed). Allows an automated low confidence match to be returned for manual/interactive review. |
Ambiguous=1 | This allows ambiguous matches the user can choose from. |
FormatNonMatched=1 | This provides a formatted result for non-matched addresses (by default only the result code is returned unless using compatibility (non-path based) calls). |
POBoxLast=1 | Means Refiner attempts to match to a street address in preference to PO Box when both are present in the source address. |
RetainAlias=1 | Means that Refiner will retain Alias Localities if present in the source address. |
NoDefaultDPS=1 | For non-DPS matches (e.g. 400) Refiner will use a default DPS value of 9Z as that is acceptable for mailing purposes. This option means the field will instead be blank in such cases. |
NoOrgFill=1 | This means un-matched data will not be moved to the organisation from the source address. This is useful if the customer doesn’t map back an organisation field. |
PostcodeCorrect=1 | When this is specified, Refiner will assume the source postcode is correct and therefore match records with otherwise lower confidence on the same postcode. This should only be used where there is a very high confidence level about the postcode or in manual matching. |
RetainExtra=1 | This feature allows you to specify fields to return the non-PAF information that we have retained after your address has been cleansed. We allow different parts of the non-PAF organisation and building data to be retained. The fields that would need to be specified are: retainedOrg1 retainedOrg2 retainedOrg3 retainedBuilding retainedData |
extraCloseness=1 | Indicates how close the output address is to the PAF Matched Address. This is available for Organisation, Property, Street and Locality fields. Additional parameters will need to be used. Parameters:
|
includeOrg=Y | Includes the Organisation in the line squeeze |
Fields | Description |
---|---|
matchKm | Calculates the distance between the input and output postcode in kilometres |
matchMiles | Calculates the distance between the input and output postcode in miles |
The deduplication process is completed in 2 stages.
Input Parameters
To use deduplication when deduplicating the database the following options are used:
&dedupe=1 | Turns on deduplication data generation |
---|---|
DedupeFields=... | List of fields to deduplicate on – (options are): |
Postcode | |
UDPRN | |
Property | |
Street | |
Name | |
Organisation | |
Surname | |
Phone | |
Any fields may be used in combination and configuration as to if both address and phone/email have to match is determined later. However, if wanting to do deduplication purely passed on email/phone, that should be done as a database query rather than run through Refiner. It is normally expected to use at least the postcode in deduplication (given this runs on the matched data), however with larger datasets additional fields such as property and surname would be advisable to reduce the “amount of noise”. UDPRN is advisable with Name and Organisation when seeking to automate duplicate identification as while it may miss some addresses that can’t be fully PAF matched it reduces the chance of two different addresses being matched, especially in conjunction with the name.
When returning the cleaned address Refiner will include two additional fields for each record:
dedupStatic – This contains data which should be identical for all records that are duplicates with each other. Depending on deduplication fields used this could include: –
dedupAdditional – This contains data that may need approximate matching, differing formats taken into account etc. to determine a duplicate for a record with the same dedupStatic value as another:-
These records should be stored in the database or file temporarily to aid identification of duplicates. Note as most of this data is not consistent across data updates and matches are not stored it is not intended that this data is permanently stored as it won’t be useful for a new run.
Example query:
http://localhost:81/v1/refiner/GBR/clean?fields=street@locality@postcode&serial=xxxxxx&password=pwd&address1=Jurby Road&address2=lezayre&address3=IM7 2DZ&dedupefields=postcode@property&dedupe=1
{
"ResultCode": 400,
"Closeness": 44,
"street": "Jurby Road",
"locality": "Lezayre, Ramsey",
"postcode": "IM7 2DZ",
"DedupStatic": "04544314",
"DedupAdditional": ""
}
After running all records through Refiner and obtaining cleaned addresses and recording the dedupStatic and dedupAdditional values a second pass should be used to identify duplicates.
This is done by grouping all records with the same dedupStatic values together and passing them to the “dedup” task of Refiner. Note if identifying duplicates purely based on a “static” field such as postcode this won’t be necessary and will be obvious by all dedupAdditional values being blank – in that scenario all records with the same dedupStatic value are duplicates. (However for consistency of operation it doesn’t matter if you pass them back in all with dedupAdditional blank – they will correctly be identified as duplicates).
Input Parameters – The dedup task has the following parameters:
dedupStatic – This is the common dedupStatic field for each of these records.
dedup1..n – This is a set of parameters that contains the additional data (was returned in the dedupAdditional) for each record with the common dedupStatic value.
additionalData (optional) – Set to AND to mean that the address field specified and the additional data items (e.g. phone number and/or email address) need to match. By default static items, such as Postcode would still need to match but if a field like Property and Phone were used either could match to be flagged as a duplicate. When this is set to AND both have to match.
dataItems (optional) – Specifies how many items have to match. If omitted (or zero) then all items specified (address, email and phone have to match). If set to 1 then only one item has to match, 2 two items have to match etc.
phoneApprox (optional) – When omitted (or zero) phone number has to be an exact match. When > 0 specifies the edit distance (how much it can differ) to still match. This should be set to a low number when wanting to allow a minor deviation in the phone number.
emailApprox (optional) – When omitted (or zero) email address has to be an exact match. When > 0 specifies the edit distance (how much it can differ) to still match. This should be set to a low number when wanting to allow a minor deviation in the email address.
In the below example query, the &dedupstatic= variable uses the DedupStatic value returned from a previous query, and the multiple &dedup#= parameters use the DedupAdditional values. This shows there are 3 dedup values, 2 identical and 1 different from the others. As a result, the response shows that 2 and 3 are duplicates.
http://localhost:81/v1/refiner/GBR/dedup?serial=xxxxxx&password=pwd&dedupstatic=02217227&dedup1=P173&dedup2=P172&dedup3=P172&dataItems=2
{
"Duplicates": [
[
1
],
[
2,
3
]
]
}
Alternatively the dedupStatic and dedup1…n data can be supplied in a POST body with multiple records containing a set of groups:
dedupstatic~dedup1~...~dedupn
Refiner will return a group of records (in JSON format) that group together each input record into those that are identified as duplicates. Any group with only one record is not a duplicate. These can then be presented to the user for review.
Please note full backups should be taken prior to any database work and that Refiner does not delete any records itself, it provides the information for the user to do so.
This allows you to specify field lengths and a fixed town field as well as to optionally include the county which allows for more control over squeezing fields.
Example: addr1:60@addr2:60@addr3:60
squeezes the address fields except the postcode (property, street, locality, town) into 3 fields, concatenating fields as required to do so.
The below table gives optional fields that may help in squeezing fields. Within each line the fields should be separated using tildes as shown below and all additional parameters should be specified within the URL. To allow greater performance, batch requests are also handled by the system. Up to 100 records can be submitted at once for processing. These will be returned within a pre-set time out (default 60 seconds, URL parameter &maxTime=
can reduce this). Batch requests sent to our Hosted solution should be no more than 50 records at once for processing. The MaxPOSTRecs
and MaxPOSTTime
settings in the pceConfig.xml
file allow these limits to be tweaked. The format of the return will provide the number of records processed (as may be less than supplied if maximum time interval exceeded – those records not processed should be re-posted to the service).
Each item returned represents a single record processed.
An example POST request would be:
http://localhost:81/v1/refiner/GBR/clean?serial=333333&password=pwd&fields=Organisation@Property@Street@Locality@Town@PostalCounty@Postcode@
With POST data:
172 Hereson Road~ramsgate~Ct117el
AFD software~mountain view~isle of man~im72dz
33 cannan avenue~kirk michael~isle of man~im61hg
Parameter | Description |
---|---|
fixtown=(n) | Fix the town to the (n) address field |
upper(field)=1 | Sets the field to upper case. Eg uppertown=1 sets town to upper case |
includeCounty=Y | Includes the county if a dedicated county field has not already been specified |
includeCounty=S | The county is included if there is space |
includeTown=N | Excludes the town from the @address1@address2@address(n) fields, preventing its duplication if the town is already specified separately |
A compatibility layer is provided that aliases old-style requests to new ones and provides any omitted functionality so that existing API users can migrate to the new API without any issues. All functionality, as documented in the current evolution API, should function with this in-place.
For clarity, the cleaning options from the older style relate to the following new style options:
Previous Implementation Code | New Refiner Parameter |
---|---|
0 | Standard cleaning (no additional options unless specified) |
1 | &postcodeonly=1 |
2 | &fullmatch=1 |
3 | &attachmode=1 |
T | &ambiguous=1 |
S | &interactive=1 |
P | &poboxlast=1 |
L | &retainalias=1 |
W | &nodefaultdps=1 |
O | &noorgfill=1 |
U | &postcodecorrect=1 |
F | no equivalent but is taken account of |
Compatibility Codes | New Refiner Code | Description |
---|---|---|
302 | 301 | Full DPS Match Limited |
-101 | -1 | No Match Found |
-102 | -2 | Ambiguous Postcode |
-103 | -3 | Suggest Record |
-104 | -4 | Ambiguous Match |
-105 | -5 | International Address |
-106 | -6 | No Record Data |
http://localhost:81/afddata.pce?serial=333333&password=pwd&Data=Address&task=Clean&format=json&fields=organisation@property@street@locality@town@county@postcode@list@udprn&address1=AFD%20Software%20Ltd&address2=&address3=Lezayre,%20Ramsey&address4=&address5=ISLE%20OF%20MAN&address6=&address7=IM7%202DZ
http://localhost:81/afddata.pce?serial=333333&password=pwd&Data=Address&task=Clean&fields=organisation@property@street@locality@town@county@postcode@list@udprn&address1=AFD%20Software%20Ltd&address2=&address3=Lezayre,%20Ramsey&address4=&address5=ISLE%20OF%20MAN&address6=&address7=IM7%202DZ
http://localhost:81/v1/refiner/GBR/clean?serial=333333&password=pwd&fields=Organisation@Property@Street@Locality@Town@PostalCounty@Postcode@
This section describes the Refiner Business product tasks for cleansing organisation’s address information and appending business data, where available.
Note: This is only an installed product.
This product requires a special Refiner API license.
You will need to set address fields in your structure to specify the address to be cleaned. These do not need to match up to the actual fields. For example, if you have Organisation, Address Line 1, Address Line 2, Address Line 3, and Postcode in your database you could set these to Organisation, Property, Street, Town and Postcode fields in the structure and they will be cleaned and returned in the correct named fields when matched. Note that if you set any non-address fields they will be ignored (please see Input and Output table for the list of fields that Refiner will use).
The request will return a negative value (less than zero) in the case where an address cannot be matched. This could be because the address was unmatchable, a non-UK address, or an ambiguous result was found (see Result Codes). An address will still be returned as this will include the address with Field Placement correction, which you can use if you desire.
Where the function returns a positive value (greater than zero) this means that the address has been uniquely matched. You may still like to examine the return value as this will give details as to the level to which the address was matched (see Result Codes). Many other fields are also available with additional non-address data, which you may require.
In the case of an ambiguous or suggested result (see Result Codes), the first address returned from the function will be the original address with field placement. For non-batch processes, you may wish to present a list of addresses for the user to choose from and in this case, you can continue to call the request as above repeatedly with the same operation code as before.
Refiner will take address field input in the following format:
Input Fields | Description |
Address(n) (where n is 1 to 10) | Allows address data to be sent in |
UDPRN | Specifies a UDPRN number of a record |
UPRN | Specifies an OS UPRN number (optional dataset available) |
Other Fields | Fields which specify a list of fields to output |
Refiner will output the following fields:
Output Fields | Description |
Result Code | Indicates the status of the match (see Result Codes) |
Closeness | Indicates how close the original address is to the PAF Matched address on a percentage scale |
Business Result | Indicates whether the address has been matched to a business (Business Matched = 1, No Business Matched = -1) |
Other Fields | Fields specified in the pre-set, which include all fields supported by Postcode Plus Business with the addition of Address(n) (where n is 1 to 10) as the address data output (each line in a separate field) |
The possible field string, which determines what data is output in addition to the fields above:
The below table describes the possible result codes and error messages:
Result Code | Description |
100 | Complete Match – Full Address matches identically. |
200 | Corrected Match – Address verified from the Postcode and matches a record with some correction. |
201 | Changed Postcode Match – Address verified from a postcode that was changed due to a Royal Mail recoding and now matches. |
202 | Assume Postcode Correct – Property Match assuming the postcode is correct. |
203 | Assume Changed Postcode Correct – Property Match with Changed Postcode assuming the original postcode is correct. |
204 | Postcode Match (non-matched property added in). |
205 | Postcode Match (postcode changed and non-matched property added in). |
300 | Full DPS Match (Different postcode returned) – Address verified with some correction, looking wider than just the specified Postcode. |
301 | Full DPS Match – Address verified. Multiple PAF delivery point records exist for this address and the organisation could not be matched. As a result the specific DPS/UDPRN could not be returned. |
400 | Street Match – Address verified to Street Level, i.e. the property was not matched, but a unique match to the street was identified on a single postcode. |
-1 | No Match Found – Refiner has been unable to match this record. |
-2 | Ambiguous Postcode – Refiner has matched this record to Street Level but cannot determine which is the correct Postcode. |
-3 | Suggested Record – Refiner has found a unique possible match for this record but there is not enough address data to reliably match it. |
-4 | Ambiguous Address – Refiner has given several possibilities that this address could match to. |
-5 | International Address – This address was detected as being an International Address and therefore cannot be cleaned as data is only present for cleaning UK, Channel Isles and Isle of Man addresses. |
-6 | No Address Data Supplied – No record data was supplied. Refiner cannot clean this address as no address data was given. |
-7 | Data License Error |
http://localhost:81/v1/busrefiner/GBR/clean?serial=333333&password=pwd&fields=organisation@property@street@locality@town@county@postcode@business@size@nationalSize@locationType@SICCode@branchCode@groupId@turnover@phone@list&address1=AFD Software Ltd&address2=&address3=Lezayre, Ramsey&address4=&address5=Isle of Man&address6=&address7=IM7 2DZ
{
"ResultCode": 200,
"Closeness": 66,
"organisation": "A F D Software Ltd",
"property": "Mountain View Innovation Centre",
"street": "Jurby Road",
"locality": "Lezayre, Ramsey",
"town": "Isle of Man",
"county": "",
"postcode": "IM7 2DZ",
"GridE": "243661",
"GridN": "495386",
"business": "Computer Software (Development)",
"size": "E",
"nationalSize": "C",
"locationType": "S",
"SICCode": "62012",
"branchCode": "",
"groupId": "",
"turnover": "",
"phone": "01624811711",
"list": "IM7 2DZ A F D Software Ltd, Mountain View Innovation Centre, Jurby Road, Lezayre, Ramsey, ISLE OF MAN"
}
Or the following type of request:
http://localhost:81/afddata.pce?serial=333333&password=pwd&data=busrefiner&task=clean&format=json&fields=organisation@property@street@locality@town@county@postcode@GridE@GridN@business@size@nationalSize@locationType@SICCode@branchCode@groupId@turnover@phone@list&address1=AFD%20Software%20Ltd&address2=&address3=Lezayre,%20Ramsey&address4=&address5=ISLE%20OF%20MAN&address6=&address7=IM7%202DZ
{
"ResultCode": 200,
"Closeness": 66,
"organisation": "A F D Software Ltd",
"property": "Mountain View Innovation Centre",
"street": "Jurby Road",
"locality": "Lezayre, Ramsey",
"town": "Isle of Man",
"county": "",
"postcode": "IM7 2DZ",
"GridE": "243661",
"GridN": "495386",
"business": "Computer Software (Development)",
"size": "E",
"nationalSize": "C",
"locationType": "S",
"SICCode": "62012",
"branchCode": "",
"groupId": "",
"turnover": "",
"phone": "01624811711",
"list": "IM7 2DZ A F D Software Ltd, Mountain View Innovation Centre, Jurby Road, Lezayre, Ramsey, ISLE OF MAN"
}
http://localhost:81/afddata.pce?serial=333333&password=pwd&data=busrefiner&task=clean&fields=organisation@property@street@locality@town@county@postcode@GridE@GridN@business@size@nationalSize@locationType@SICCode@branchCode@groupId@turnover@phone@list&address1=AFD%20Software%20Ltd&address2=&address3=Lezayre,%20Ramsey&address4=&address5=ISLE%20OF%20MAN&address6=&address7=IM7%202DZ
<AFDPostcodeEverywhere>
<Result>200</Result>
<ErrorText>Postcode Match</ErrorText>
<Item value="1">
<Closeness>66</Closeness>
<organisation>A F D Software Ltd</organisation>
<property>Mountain View Innovation Centre</property>
<street>Jurby Road</street>
<locality>Lezayre, Ramsey</locality>
<town>Isle of Man</town>
<county/>
<postcode>IM7 2DZ</postcode>
<GridE>243661</GridE>
<GridN>495386</GridN>
<business>Computer Software (Development)</business>
<size>E</size>
<nationalSize>C</nationalSize>
<locationType>S</locationType>
<SICCode>62012</SICCode>
<branchCode></branchCode>
<groupId></groupId>
<turnover></turnover>
<phone>01624811711</phone>
<list>IM7 2DZ A F D Software Ltd, Mountain View Innovation Centre, Jurby Road, Lezayre, Ramsey, ISLE OF MAN</list>
</Item>
</AFDPostcodeEverywhere>
To allow greater performance, batch requests are also handled by the system. Up to 100 records can be submitted at once for processing. These will be returned within a pre-set time out (default 60 seconds). Batch requests sent to our Hosted solution should be no more than 50 records at once for processing.
The MaxPOSTRecs and MaxPOSTTime settings in the pceConfig.xml file allow these limits to be tweaked. After making these changes the AFD Postcode Evolution Service need to be restarted.
The format of the return will provide the number of records processed (as may be less than supplied if maximum time interval exceeded – those records not processed should be re-posted to the service).
Each item returned represents a single record processed.
http://localhost:81/v1/busrefiner/GBR/clean?serial=333333&password=psw&fields=organisation@property@street@locality@town@county@postcode@business@size@nationalSize@locationType@SICCode@branchCode@groupId@turnover@phone
http://localhost:81/afddata.pce?serial=333333&password=pwd&data=busrefiner&task=clean&fields=organisation@property@street@locality@town@county@postcode@GridE@GridN@business@size@nationalSize@locationType@SICCode@branchCode@groupId@turnover@phone
With POST data:
AB10 6BR~Pizza Hut (UK) Ltd~53 Holburn Street~ABERDEEN
AFD software~mountain view~isle of man~im72dz
Your Housing Group Ltd~Eaves Brook House~Navigation Way~PR2 2YP
Note: Batch requests sent to our Hosted solution should be no more than 50 records at once for processing.
Parameter | Description |
PostcodeCorrect=1 | When this is specified, Refiner will assume the source postcode is correct and therefore match records with otherwise lower confidence on the same postcode. This should only be used where there is a very high confidence level about the postcode or in manual matching. |
FieldName(n)=(value) | (where n is 1 to 10) which allows the field name to be specified (when known) for the data, valid values are Organisation, Property, HouseNumber, Street, Locality, Town, County, and Postcode. |
AttachMode=1 | Used to simply attach data based on the postcode, doesn’t verify the address. |
PostcodeOnly=1 | If it can, it will verify an address purely using the postcode (returning only 100/200 result codes). |
FullMatch=1 | Only returns full PAF matches, i.e. if the property is not on PAF, a street-level match will not be offered. |
Speed=1 | Skips slower portions of processing (lowers match rate but improves performance). |
Interactive=1 | Specifies the address is being returned to a user interactively to check. (For example, when a user has entered an address manually and the suggested address is displayed). Allows an automated low confidence match to be returned for manual/interactive review. |
Ambiguous=1* | This allows ambiguous matches the user can choose from. |
Dedupe=1 ** | Enables deduplication. |
DedupeFields= ** | List of fields, separated by @ to dedupe on (e.g. Postcode|UDPRN|Name). |
FormatNonMatched=1 | This provides a formatted result for non-matched addresses (by default only the result code is returned unless using compatibility (non-path based) calls). |
POBoxLast=1 | Means Refiner attempts to match to a street address in preference to PO Box when both are present in the source address. |
RetainAlias=1 | Means that Refiner will retain Alias Localities if present in the source address. |
NoDefaultDPS=1 | For non-DPS matches (e.g. 400) Refiner will use a default DPS value of 9Z as that is acceptable for mailing purposes. This option means the field will instead be blank in such cases. |
NoOrgFill=1 | This means un-matched data will not be moved to the organisation from the source address. This is useful if the customer doesn’t map back an organisation field. |
RetainExtra=1 | This feature allows you to specify fields to return the non-PAF information that we have retained after your address has been cleansed. We allow different parts of the non-PAF organisation and building data to be retained. The fields that would need to be specified are: retainedOrg1 retainedOrg2 retainedOrg3 retainedBuilding retainedData |
extraCloseness=1 | Indicates how close the output address is to the PAF Matched Address. This is available for Organisation, Property, Street and Locality fields. Additional parameters will need to be used. Parameters:
|
* When Ambiguous=1 option is used an additional field is returned: ambigRecs, which lists the ambiguous matches for this input record.
** Dedup and DedupFields are meant to be used together. When these options are used additional field is returned: DedupStatic – a number, which will be the same for the duplicates.
Fields | Description |
---|---|
matchKm | Calculates the distance between the input and output postcode in kilometres |
matchMiles | Calculates the distance between the input and output postcode in miles |
This allows you to specify field lengths and a fixed town field as well as to optionally include the county which allows for more control over squeezing fields.
Example: addr1:60@addr2:60@addr3:60
squeezes the address fields except the postcode (property, street, locality, town) into 3 fields, concatenating fields as required to do so.
The below table gives optional fields that may help in squeezing fields:
Parameter | Description |
fixtown=(n) | Fix the town to the (n) address field |
upper(field)=1 | Sets the field to upper case. Eg uppertown=1 sets town to upper case |
includeCounty=Y | Includes the county if a dedicated county field has not already been specified |
includeCounty=S | The county is included if there is space |
includeTown=N | Excludes the town from the @address1@address2@address(n) fields, preventing its duplication if the town is already specified separately |
A compatibility layer is provided that aliases old-style requests to API v1 and provides any omitted functionality so that existing API users can migrate to the new API without any issues. All functionality, as documented in the current evolution API, should function with this in-place.
For clarity, the cleaning options from the older style relate to the following API v1 options:
Previous Implementation Code | New Refiner Parameter |
0 | Standard cleaning (no additional options unless specified) |
1 | &postcodeonly=1 |
2 | &fullmatch=1 |
3 | &attachmode=1 |
T | &ambiguous=1 |
S | &interactive=1 |
P | &poboxlast=1 |
L | &retainalias=1 |
W | &nodefaultdps=1 |
O | &noorgfill=1 |
U | &postcodecorrect=1 |
F | no equivalent but is taken account of |
Compatibility Codes | New Refiner Code | Description |
---|---|---|
302 | 301 | Full DPS Match Limited |
-101 | -1 | No Match Found |
-102 | -2 | Ambiguous Postcode |
-103 | -3 | Suggest Record |
-104 | -4 | Ambiguous Match |
-105 | -5 | International Address |
-106 | -6 | No Record Data |
Note: This is an installed product only.
This data parameter is used to find the Nearest in your database to a specified postcode or location.
When using Nearest you will also need to specify the following parameter to specify the database to use (this is connected too on the server-side):
Parameter | Description |
---|---|
DBConnect | The name of the database to connect to as defined by a name section in nearest.xml |
As a security precaution, only databases specified in nearest.xml
can be connected to and the settings which are used are specified in that .xml
file. The nearest.xml
file will already be located in your PCE install location and has a section called name
where DBname
is the name used in the DBConnect
parameter for PCE calls.
All of the below settings can be added and amended in the Nearest XML located in the install location.
This set of sections specify each Nearest database table in use, most customers will only have one but an infinite number is supported. The settings for each database are as follows:
name | The name used for the database via the dbconnect URL parameter. |
type | The type of database: CSV, DBASE and MYSQL are supported on Linux. |
fileName | For CSV and DBASE Only: Specifies the path to the database file. |
server | For MySQL Only: Specifies the server name or IP address of the MySQL server. |
database | For MySQL Only: Specifies the database to connect to. |
sql | For MySQL Only: Query String to return the data, e.g. SELECT * FROM table. |
uid | For MySQL Only: Provides username to connect to the MySQL instance with. |
pwd | For MySQL Only: Provides password to connect to the MySQL instance with. |
noHeadings | For CSV Only: Set to 1 if the table has no field headings (field’s must be referred to by their column number in this case). |
gridE | Specifies the name of the Grid Easting field (or column number if numeric). |
gridN | Specifies the name of the Grid Northing field (or column number if numeric). |
oldGrids | If set to 1 specifies that grid fields contain 5 digit grids (as used by front-end and older databases). |
listFields | A comma separated list of database fields to output for the item when returning a Nearest record (or column numbers if numeric). |
outputFields | A comma separated list of database fields to return when standard fields are used (or column numbers if numeric). |
updateFreq | Specifies the frequency in seconds to re-load the database. For example 300 would update the data every 5 minutes, 3600 would update it hourly. |
<?xml version="1.0"?>
<NearestConfig>
<updateFreq>5</updateFreq>
<database>
<name>Nandos</name>
<type>CSV</type>
<fileName>.\data\util\nandos.csv</fileName>
<noHeadings>0</noHeadings>
<gridE>GridE</gridE>
<gridN>GridN</gridN>
<oldGrids>1</oldGrids>
<listFields>Title</listFields>
<outputFields>RecordNo,Postcode,Organisation,Property,Street,Locality,Town,County,Phone,Fax</outputFields>
</database>
</NearestConfig>
http://localhost:81/afddata.pce?serial=333333&password=pwd&Data=nearest&task=lookup&fields=standard&maxquantity=1&dbconnect=nandos&lookup=TW18+3JD&Miles=1
&approxDist
Option | Description |
---|---|
0 | OSRM (default when enabled) |
1 | Straight line (default when OSRM is not enabled) |
2 | Obstacle |
The below table describes the possible result codes and error messages when using the phone
data product.
Result Code | Description |
---|---|
1 | Live Number |
-2 | Number not valid |
-4 | Error contacting service |
-7 | Data License Error |
Live checks are performed on all UK Landline and Mobile numbers excluding 03 and 08 business numbers which are format verified. We live validate for a large number of international networks, where the live validation isn’t available for an international network we fall back to format verified.
Please note: you must update the CountryISO=
value to be the country in which the phone number originates from.
https://pce.afd.co.uk/afddata.pce?data=phone&serial=333333&password=pwd&task=full&CountryISO=GBR&fields=standard&phone=01624%20811711&format=json
{
"Result": "1",
"ErrorText": ""
}
https://pce.afd.co.uk/afddata.pce?data=phone&serial=333333&password=pwd&task=full&CountryISO=GBR&fields=standard&phone=01624%20811711&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
</AFDPostcodeEverywhere>
A simple mistake in typing an email address makes it impossible for an email to reach the right recipient.
1
Description |
---|
Format Verified |
Domain and Format Verified |
Format Verified, Unable to make DNS Request |
Format Correct, Unable to Open Connection |
Format Correct, Mail Server Refused Connection |
Format Correct, Mail Server Timeout |
Format Correct, Mail Server Refused Server |
Format Correct, Mail Server Refused Sender |
Format Correct, Mail Server Refused IP |
Format Correct, Mail Server Temporarily Unavailable |
Format Correct, Mail Server Invalid |
Email Address Live Verified |
Email Address Verified |
-2
Description |
---|
Format Invalid |
Unknown Top Level Domain |
Domain-Specific Format Invalid |
Invalid Email, Mail Server Not Found |
Mail Server Rejected Email Address |
Invalid Email Address. Contains whitespace. |
LocalChecked
Boolean value that indicates if the local part of the address has been checked (1
) or not (0
).
AcceptsAll
Boolean value that indicates if the actual address is verified if applicable (0
) or if it accepts all emails (1
).
FormatVerified
This helps add confidence for corporate email addresses where the server accepts all fields or refused the validation request.
It attempts to verify if the format is in-line with those used.
Value | Description |
---|---|
Present | The email address is present on the website – therefore as good as a live validation. In this case, we will also update the other values to reflect this and give a full positive response. |
Format | The email address is in the format of those present on the website (e.g. if other emails are firstname.lastname@afd.co.uk this will return “true” for others in the same format). |
Fail | The email address differs from other formats found. |
(blank) | This field is blank if the check is unnecessary (e.g. full live verification occurred), or not possible (e.g. there is no website configured for the domain or none or too few email addresses found to verify). |
Note: This is only done on email addresses that AcceptsAll=1
.
Suggested
Regardless of if the email address validates this provides the suggested email address if it contains a misspelled domain name (for example gmai.com
instead of gmail.com
), or misformatted address, e.g. jon.@gmailcom
becomes john@gmail.com
gmail.com
.Spelling
Boolean value that indicates if there is no spelling error detected (0
) or if a spelling error is likely (1
).
NonStandard
Boolean value that indicates if no non-standard characters are present (0
) or if there are non-standard characters present in the email address (1
).
Example email address: john!??{@afd.co.uk
. This is a valid email address but would seem unusual.
Note: This is only for valid email addresses.
Reachable
Boolean value that indicates if the mail server is non-reachable (0
) or if it is reachable (1
).
Dummy
Boolean value that indicates if the address is not detected as a dummy address (0
) or if it is likely to be a dummy/test email address (1
).
Throwaway
These are known domains that allow accounts to be created that self-destruct after a certain time, intended for sign-ups, etc.
Boolean value that indicates if the address is not a known throwaway domain (0
) or if it is (1
).
Generic
Boolean value that indicates if the address is not a known generic email (0
) or if it is (1
).
Example email addresses: support@afd.co.uk
, accounts@afd.co.uk
, etc.
task=full does full checks on the format of the email address, a DNS lookup for the MX record.
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=full&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Email: "support@afd.co.uk",
Status: "Email Address Verified",
LocalChecked: 0,
AcceptsAll: 0,
FormatVerified: "",
Suggested: "",
Spelling: 0,
NonStandard: 0,
Reachable: 0,
Dummy: 0,
Throwaway: 0,
Generic: 1
}
]
}
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=full&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Email>support@afd.co.uk</Email>
<Status>Email Address Verified</Status>
<LocalChecked>0</LocalChecked>
<AcceptsAll>0</AcceptsAll>
<FormatVerified/>
<Suggested/>
<Spelling>0</Spelling>
<NonStandard>0</NonStandard>
<Reachable>0</Reachable>
<Dummy>0</Dummy>
<Throwaway>0</Throwaway>
<Generic>1</Generic>
</Item>
</AFDPostcodeEverywhere>
Validate email format, top-level domain, and server response for the full email address (if enabled on the server) – task=live does the same as task=full but also does a live validation by connecting to the registered email server and testing to see if the email is accepted for that address, where the destination server allows that.
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=live&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Email: "support@afd.co.uk",
Status: "Email Address Live Verified",
LocalChecked: 1,
AcceptsAll: 1,
FormatVerified: "Present",
Suggested: "",
Spelling: 0,
NonStandard: 0,
Reachable: 1,
Dummy: 0,
Throwaway: 0,
Generic: 1
}
]
}
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=live&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Email>support@afd.co.uk</Email>
<Status>Email Address Live Verified</Status>
<LocalChecked>1</LocalChecked>
<AcceptsAll>1</AcceptsAll>
<FormatVerified/>
<Suggested/>
<Spelling>0</Spelling>
<NonStandard>0</NonStandard>
<Reachable>1</Reachable>
<Dummy>0</Dummy>
<Throwaway>0</Throwaway>
<Generic>1</Generic>
</Item>
</AFDPostcodeEverywhere>
Validate email format is correct and the top-level domain exists.
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=tld&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Email: "support@afd.co.uk",
Status: "Format Verified",
LocalChecked: 0,
AcceptsAll: 0,
FormatVerified: "",
Suggested: "",
Spelling: 0,
NonStandard: 0,
Reachable: 0,
Dummy: 0,
Throwaway: 0,
Generic: 1
}
]
}
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=tld&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Email>support@afd.co.uk</Email>
<Status>Format Verified</Status>
<LocalChecked>0</LocalChecked>
<AcceptsAll>0</AcceptsAll>
<FormatVerified/>
<Suggested/>
<Spelling>0</Spelling>
<NonStandard>0</NonStandard>
<Reachable>0</Reachable>
<Dummy>0</Dummy>
<Throwaway>0</Throwaway>
<Generic>1</Generic>
</Item>
</AFDPostcodeEverywhere>
Validates if the email address format is correct only.
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=format&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=json
{
Result: "1",
ErrorText: "",
Item: [
{
@value: "1",
Email: "support@afd.co.uk",
Status: "Format Verified",
LocalChecked: 0,
AcceptsAll: 0,
FormatVerified: "",
Suggested: "",
Spelling: 0,
NonStandard: 0,
Reachable: 0,
Dummy: 0,
Throwaway: 0,
Generic: 1
}
]
}
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=format&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Email>support@afd.co.uk</Email>
<Status>Format Verified</Status>
<LocalChecked>0</LocalChecked>
<AcceptsAll>0</AcceptsAll>
<FormatVerified/>
<Suggested/>
<Spelling>0</Spelling>
<NonStandard>0</NonStandard>
<Reachable>0</Reachable>
<Dummy>0</Dummy>
<Throwaway>0</Throwaway>
<Generic>0</Generic>
</Item>
</AFDPostcodeEverywhere>
Validate email format, top-level domain and for well-known domains carry out additional checks of the local portion of the address.
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=local&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=json
{
"Result": "1",
"ErrorText": "",
"Item": [
{
@value: "1",
"Email": "support@afd.co.uk",
"Status": "Domain and Format Verified",
"LocalChecked": 0,
"AcceptsAll": 0,
"FormatVerified": "",
"Suggested": "",
"Spelling": 0,
"NonStandard": 0,
"Reachable": 0,
"Dummy": 0,
"Throwaway": 0,
"Generic": 1
}
]
}
https://pce.afd.co.uk/afddata.pce?data=email&serial=333333&password=pwd&task=local&CountryISO=GBR&fields=standard&email=support@afd.co.uk&format=xml
<AFDPostcodeEverywhere>
<Result>1</Result>
<ErrorText/>
<Item value="1">
<Email>support@afd.co.uk</Email>
<Status>Domain and Format Verified</Status>
<LocalChecked>0</LocalChecked>
<AcceptsAll>0</AcceptsAll>
<FormatVerified/>
<Suggested/>
<Spelling>0</Spelling>
<NonStandard>0</NonStandard>
<Reachable>0</Reachable>
<Dummy>0</Dummy>
<Throwaway>0</Throwaway>
<Generic>1</Generic>
</Item>
</AFDPostcodeEverywhere>
There is no one-size-fits-all approach for email validation as depending on the use of the data or the interface presented may impact decisions over design. This guide is designed to help outline best practices when using email validation.
For the vast majority of users, a simple valid or not is all that is required and if it is invalid, the user needs to check/re-enter it.
AFD only returns a -2 invalid response when we can guarantee an invalid address, any uncertainty is returned as valid. This uncertainty can be caused by a number of reasons such as temporarily being unable to connect to the server.
Depending on your individual needs you may wish to be stricter with what you do and don’t allow. In this case, we suggest that you base your validation rules not only on the Result but also on the Status. Anything more can over-complicate a system or interface.
In most cases, best practice with email validation on a website is to call the validation routines when a user enters an address. If it fails validation, then the user will be prompted to correct it. If not already doing so, it may be useful to prompt the user to double-check or re-enter the email address if the validation times out or live validation is not possible, so the address can be double checked. You may also like to reject or prompt if an address is indicated to be a dummy address (normally a test address rather than a genuine account).
If you wish to have direct contacts rather than generic addresses (e.g., not things like sales@, support@ etc.), you might want to request an alternative if that flag is set. However, outright rejection needs to be carefully considered as, for example, a small company may have that as their only business email and a single person is receiving those emails.
While systems do not always allow you to do so, it is useful to store if an email address has been fully live validated or not. This can then allow records to be manually reviewed later if feasible. For example, if an email address was not live validated or timed out, you know there is a higher chance it might be incorrect, and you might want to check it manually or if the customer calls in, etc.
Due to the complexities of email addresses, it must always be remembered that some (particularly personal email addresses) can be quite unusual but still be valid. Only if an email address is returned as invalid is it definitely invalid, and if it’s a live validation that can change at any point in time (e.g., email address is created, re-enabled, etc.).
Suggestions may want to be used to help the end user/operator see what the address might be intended to be if it fails validation or if the email address has been mistyped. However, it is important to check the suggestion with the user to ensure it is not being mis-corrected. Remember, suggestions are simply that – suggestions of what may be more likely, not corrections. The full status may be useful but depending on the level of understanding of the operator, a simple pass/failure/unable to live validate may be easier to work with.
Throwaways are temporary email addresses. If it’s for an email newsletter, then you may want to request a permanent address. However, if it’s for an online order you may decide to still accept it so you can get the order, even though you know the email address will cease to exist later – though you may want to insist on something permanent. In some systems, it may act more as a fraud flag – i.e., you don’t want to reject it at the point of entry, but you want to flag it (for example, applying for a loan with a throwaway email might be considered suspicious – perhaps the person is hoping to become un-contactable later etc.).
Please note that we do offer a service for batch email validation. If this is a service you would be interested in, please contact your AFD Account Manager who can provide details and further information.
DXNumber
and DXExchange
field in the XML if you have the DX data enabled.
Fast-find functionality works with DX data as well as postal data. For example, as well as looking up a postcode you can also carry out a fast-find for a DX number and searching for an organisaiton name with fast-find will search both postal and DX data. This allows you to easily combine your lookup’s. When searching you can either search the standard postal fields or specify the DX Number, organisation, exchange or profession to search theDX data instead. (If you only want to specify one set of search fields in your application then placing DX followed by the DX number in the normal street field will work too – town can then be used to specify the exchange if desired).
When results are returned following any lookup or search if the address is also a DX Member the DXNumber
, DXExchange
and DXProfession
fields will also be returned to indicate this. You can format a DX address as follows for printing:
Label | Address |
---|---|
Organisation | Gateley LLP |
DXNumber | DX 14317 |
DXExchange | MANCHESTER |
DXProfession | Solicitor |