Introduction

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 allowing 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 http://www.afd.co.uk/support or contact us below:

Contact Phone Email
Sales +44 1624 811711 postcode@afd.co.uk
Support +44 1624 811712 support@afd.co.uk

Getting Started

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.

Calling the Postcode Evolution Server

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.

Building a PCE Request URL

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.

Example PCE Request

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:

JSON Format

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"
    }
  ]
}

XML Format

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/>
  <Item value="1">
    <Postcode>B6 4AA</Postcode>
    <PostcodeFrom/>
    <List>B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM</List>
    <Key>338899</Key>
    <CountryISO>GBR</CountryISO>
  </Item>
</AFDPostcodeEverywhere>

Data Selector

The 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

🛈

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 email GBR Provides access to Email validations (see Section 13)
Phone phone ALL Provides access to Phone validations (see Section 12)
Refiner refiner GBR Provides access to Refiner (see Section 10)
Nearest nearest GBR Provides access to Nearest (see Section 11)
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.

Field Presets

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 11) 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 Address (see Section 6) Returns fields in the format used in the USA, most useful when used with ZipAddress for looking up US addresses. However, this format will also work with UK addresses just as the UK formats will work with 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 11), 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

Address Products

PostcodePlus, 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).

Available Fields

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.

The following shows addressing fields:

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

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

JustBuilt 🛈

10 Numeric

Phone 🛈

20 Text

PostalCounty 🛈

30 Text

AbbreviatedPostalCounty 🛈

30 Text

OptionalCounty 🛈

30 Text

AbbreviatedOptionalCounty 🛈

30 Text

TraditionalCounty 🛈

30 Text

AdministrativeCounty 🛈

30 Text

NHSCode (National Health Service Code) 🛈

6 Text

NHSName (National Health Service Name) 🛈

50 Text

NHSRegionCode (National Health Service Region Code) 🛈

3 Text

NHSRegionName (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

ConstituencyCode 🛈

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

SubCountryName 🛈

20 Text

DevolvedConstituencyCode 🛈

9 Text

DevolvedConstituencyName 🛈

50 Text

SOALower (Super Output Area Lower) 🛈

9 Text

SOAMiddle (Super Output Area Middle) 🛈

9 Text

UrbanRuralCode 🛈

2 Text

UrbanRuralName 🛈

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

AdditionalCensusInfo 🛈

200 Text

AddressType 🛈

6 Numeric

AddressTypeDescription 🛈

55 Text

Occupancy 🛈

6 Numeric

OccupancyDescription 🛈

30 Text

Name 🛈

120 Text

Residency 🛈

6 Numeric

HouseholdComposition 🛈

106 Text

Business 🛈

100 Text

Size 🛈

6 Text

SICCode (Standard Industry Classification Code) 🛈

10 Numeric

LocationType 🛈

6 Text

BranchCount 🛈

6 Numeric

GroupID 🛈

6 Numeric

ModelledTurnover 🛈

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

CouncilTaxBand ** 🛈

6 Text

GridLevel ** 🛈

1 Numeric

POLAR3Young ** 🛈

8 Numeric

POLAR3Adult ** 🛈

8 Numeric

POLAR4 ** 🛈

8 Numeric

DeprivationRank ** 🛈

8 Numeric

DeprivationDecile ** 🛈

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

AEBEffectiveFrom (Adult Education Budget Effective From) ** 🛈

10 Text

AEBEffectiveTo (Adult Education Budget Effective To) ** 🛈

10 Text

MultipleResidencyIndicator ** 🛈

1 Text

NotYetBuilt ** 🛈

1 Text

Abase (AddressBase) ** 🛈

1 Text

DXNumber ** 🛈

10 Text

DXExchange ** 🛈

30 Text

DXOrganisation ** 🛈

120 Text

DXProfession ** 🛈

30 Text

Outcode 🛈

4 Text

Incode 🛈

3 Text

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

Raw PAF Fields (Formatted 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

OrganisationName 🛈

60 Text

DepartmentName 🛈

60 Text

SubBuilding 🛈

60 Text

Building 🛈

60 Text

Number 🛈

10 Numeric

DependantThoroughfare 🛈

60 Text

Thoroughfare 🛈

60 Text

DoubleDependantLocality 🛈

35 Text

DependantLocality 🛈

35 Text

Town 🛈

30 Text

Postcode 🛈

10 Text

BS7666 Fields (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

USA Address Fields

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

CongressionalDistrict 🛈

3 Numeric

CountyNumber 🛈

4 Numeric

CountyName 🛈

26 Text

CityAbbreviation 🛈

14 Text

Product 🛈

40 Text

Country 🛈

30 Text

International Address Fields These are additional fields supplied with the standard field list

Fieldname Field Length Data Type Postcode Postcode Plus Names & Numbers ZipAddress WorldAddress Eircode Validation

Address1...7 🛈

120 Text

Principality 🛈

60 Text

Region 🛈

60 Text

Cedex 🛈

60 Text

Country 🛈

30 Text

CountryISO 🛈

3 Text

Alias Localities (Non-postally required Localities)

Fieldname Field Length Data Type Postcode Postcode Plus Names & Numbers ZipAddress WorldAddress Eircode Validation

AliasLocalities 🛈

4 Text

CountryISO 🛈

35 Text

Result Codes

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

Lookup Tasks

Lookup Tasks are a group of different calls that each accepts only one search parameter, specified using a Lookup string.

FastFindV4

FastFindV4 optimises the Fast Find task for TypeAhead situations.

It is necessary to specify a &uniqueID that should remain the same for a single search. This allows our billing system to make sure that each keypress is not being charged separately. We also recommend setting the &maxquantity to a number between 5 and 7 as this will increase the responsiveness of your TypeAhead control.

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.

JSON Format

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

{
  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"
    }
  ]
}
XML Format

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/>
  <Item value="1">
    <Postcode>AB10 1BD</Postcode>
    <PostcodeFrom/>
    <List>AB10 1BD The Royal British Legion, 46a Union Street, ABERDEEN</List>
    <Key>105</Key>
    <CountryISO>GBR</CountryISO>
  </Item>
</AFDPostcodeEverywhere>

Fast Find

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.

JSON Format

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: "338899",
      CountryISO: "GBR"
    }
  ]
}
XML Format

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/>
  <Item value="1">
    <Postcode>B6 4AA</Postcode>
    <PostcodeFrom/>
    <List>B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM</List>
    <Key>338899</Key>
    <CountryISO>GBR</CountryISO>
  </Item>
</AFDPostcodeEverywhere>

Lookup

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.

  • This task should be used when the full postcode is always known.

  • It will only accept a full postcode.

  • Including a space in the postcode is optional.

  • It can return one or more results (including multiple streets when a postcode is on a multiple locality record).

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.

JSON Format

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: "338899",
      CountryISO: "GBR"
    }
  ]
}
XML Format

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/>
  <Item value="1">
    <Postcode>B6 4AA</Postcode>
    <PostcodeFrom/>
    <List>B6 4AA Royal Mail, Birmingham Mail Centre, St. Stephens Street, BIRMINGHAM</List>
    <Key>338899</Key>
    <CountryISO>GBR</CountryISO>
  </Item>
</AFDPostcodeEverywhere>

Property Lookup

To lookup matching addresses quickly from a postcode, which may optionally include property information to find a match, e.g., 276, B11 1AA.

  • The Property Lookup task can accept either a postcode or a postcode and property name or number.

  • It can return one or more results.

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.

JSON Format

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"
    }
  ]
}
XML Format

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.

JSON Format

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"
    }
  ]
}
XML Format

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>

Retrieve

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

JSON Format

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"
    }
  ]
}
XML Format

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>

Geolocation

This functionality is available with an optional high-resolution license which will return the nearby addresses in the correct order.

FastFindGeo

This works in the same way as FastFindV4 (see Section 6.2); however, uses a special field preset of geolist to return location data.

JSON Format

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"
    }
  ]
}
XML Format

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

<AFDPostcodeEverywhere>
  <Result>1</Result>
  <ErrorText/>
  <Item value="1">
    <Postcode>B11 1AA</Postcode>
    <PostcodeFrom/>
    <List>280 Stratford Road, Sparkhill, BIRMINGHAM, B11 1AA</List>
    <Key>379670</Key>
    <CountryISO>GBR</CountryISO>
    <GridE>408834</GridE>
    <GridN>284629</GridN>
    <Latitude>52.4596</Latitude>
    <Longitude>-1.8714</Longitude>
  </Item>
</AFDPostcodeEverywhere>

Nearest

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.

JSON Format

http://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&fields=list&CountryISO=GBR&task=nearest&maxquantity=5&longitude=-1.6787&latitude=53.8507&format=json

{
  Result: "1",
  ErrorText: "",
  Item: [
    {
      @value: "1",
      Postcode: "LS19 6ET",
      PostcodeFrom: "",
      List: "LS19 6ET    Welbeck House, Over Lane, Rawdon, LEEDS",
      Key: "14057846",
      CountryISO: "GBR"
    }

XML Format

http://pce.afd.co.uk/afddata.pce?data=address&serial=333333&password=pwd&uniqueID=abcd123&fields=list&CountryISO=GBR&task=nearest&maxquantity=5&longitude=-1.6787&latitude=53.8507&format=xml

<AFDPostcodeEverywhere>
  <Result>1</Result>
  <ErrorText/>
  <Item value="1">
    <Postcode>LS19 6ET</Postcode>
    <PostcodeFrom/>
    <List>LS19 6ET Welbeck House, Over Lane, Rawdon, LEEDS</List>
    <Key>14057846</Key>
    <CountryISO>GBR</CountryISO>
  </Item>
</AFDPostcodeEverywhere>

Additional Parameters

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

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

&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)

DX Data

🛈 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

International Data

World address works the same as all our address products. The only difference in normal operation is the need to specify the Country or CountryISO code (as parameters in the GET request) of the country that you wish to use in all lookup, search and record retrieval operations.

Making use of the data returned

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.

Utilities

List

List Countries

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.

  • Use this Task to list the Alpha-3 Country ISO Codes.
  • Any license will show these CountryISO's.
JSON Format

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"
		}
	]
}
XML Format

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>

List Country

JSON Format

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",
			List: "Afghanistan"
		},
		{
			@value: "2",
			List: "Aland Islands"
		},
		{
			@value: "3",
			List: "Albania"
		}
    ]
}
XML Format

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">
        <List>Afghanistan</List>
    </Item>
    <Item value="2">
        <List>Aland Islands</List>
    </Item>
    <Item value="3">
        <List>Albania</List>
    </Item>
</AFDPostcodeEverywhere>

List CountryISO

JSON Format

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",
            List: "AFG"
        },
        {
            @value: "2",
            List: "ALA"
        },
        {
            @value: "3",
            List: "ALB"
        }
    ]
}
XML Format

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">
        <List>AFG</List>
    </Item>
    <Item value="2">
        <List>ALA</List>
    </Item>
    <Item value="3">
        <List>ALB</List>
    </Item>
<AFDPostcodeEverywhere>

List Address

List Organisation

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Property

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>
JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListStreet&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Stratford%20park&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "STRATFIELD PARK"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Locality

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListLocality&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Lee%20bank&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "LEE BANK"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Town

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListTown&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Birmingham&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "BIRMINGHAM"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List County

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListCounty&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Westminster&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "WESTMINSTER"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Mailsort Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListMailsortCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=34439&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "34439"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Names

This function requires a Names & Numbers license.

List Forename

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Surname

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Council Tax Band

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListCouncilTaxBand&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=A&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "A"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListCouncilTaxBand&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=A&format=xml

<AFDPostcodeEverywhere>
    <Result>1</Result>
    <ErrorText/>
    <Item value="1">
        <List>A</List>
    </Item>
</AFDPostcodeEverywhere>

List Censation

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.

List Censation Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Affluence

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListAffluence&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=B&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "B, Prosperous"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Lifestage

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListLifestage&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=X&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "X, Older families"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Additional Census Info

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Business

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Size

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListSize&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=I&format=json

{
    Result: "1",
    ErrorText: "",
    Item": [
        {
            @value: "1",
            List: "I: 501+"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List SIC

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Geographical

List Urban Rural Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListUrbanRuralCode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=A1&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "A1"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Urban Rural Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List TV Region

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListTVRegion&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Midlands&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "MIDLANDS"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Health

List NHS Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List NHS Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListNHSName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=borders&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "BORDERS"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List NHS Region Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List NHS Region Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListNHSRegionName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Midlands&format=json

{
    "Result": "1",
    "ErrorText": "",
    "Item": [
        {
            "@value": "1",
            "List": "MIDLANDS AND EASTERN"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List CCG Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List CCG Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Administrative

List Ward Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Ward Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListWardName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=Westhill&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "WESTHILL AND DISTRICT"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List EER Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List EER Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListEERName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=West%20Midlands&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "WEST MIDLANDS"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Authority Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Authority

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListAuthority&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=birmingham&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "BIRMINGHAM"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List LEA Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListLEACode&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=330&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "330"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List LEA Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&task=ListLEAName&fields=list&serial=333333&password=pwd&CountryISO=GBR&lookup=birmingham&format=json

{
    Result: "1",
    ErrorText: "",
    Item: [
        {
            @value: "1",
            List: "BIRMINGHAM"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Constituency Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Constituency Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Devolved Constituency Code

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Devolved Constituency Name

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=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>

List Products

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
            }
        ]
    }
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

List Alias Locality

This Task is a per postcode lookup. This will not supply a list of Alias Localities in the UK.

JSON Format

https://pce.afd.co.uk/afddata.pce?data=address&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"
        }
    ]
}
XML Format

https://pce.afd.co.uk/afddata.pce?data=address&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>

Grid

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.

Convert and Convert1m

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

JSON Format

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: ""
        }
    ]
}

XML Format

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>

LookupLocation and LookupLocation1m

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

JSON Format

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: ""
      }
   ]
}

XML Format

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>

DistanceMulti

Parameters Description
lat1, lng1 and lat2, lng2, etc. Addition of multiple way points

JSON Format

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"
    }
  ]
}

XML Format

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>

Distance and Distance1m

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 Distance1m function returns grids to a 1m resolution (6-digit), whereas Distance returns 5-digit grids.

JSON Format

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\""
      }
   ]
}

XML Format

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>

Bank Finder

An application programming interface to access the BankFinder data. Please see the BankFinder Manual for more information.

Available Bank Fields

● = 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.

The following shows the banking fields.

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

Bank Result Codes

The below table 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

Bank Lookup Tasks

Lookup Tasks are a group of different calls that each accepts only one search parameter, specified using a Lookup string.

Bank Lookup

  • This task should be used when the full postcode/sort code is always known.

  • It will only accept a full postcode/sort code.

  • Including a space or hyphens in the sort code are optional.

  • It can return one or more results (including multiple streets when a postcode is on a multi locality record).

Description Example
GBR Sort Code 401101
IRL Sort Code 930008
JSON Format

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"
    }
  ]
}
XML Format

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>

Bank Property Lookup

Description Example
BranchName, SortCode Pudsey,560036
JSON Format

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"
    }
  ]
}
XML Format

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>

Bank Fast Find

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
JSON Format

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"
    }
  ]
}
XML Format

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 Tasks are a group of different calls that each accepts multiple search parameters, specified using a 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

🛈 Any field can be searched.

JSON Format

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"
    }
  ]
}
XML Format

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>

Bank Retrieve

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
JSON Format

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"
    }
  ]
}
XML Format

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>

Account Number Validation

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
JSON Format

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"
    }
  ]
}
XML Format

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>

Credit Card Validation

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
JSON Format

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"
}
XML Format

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>

Refiner

This section describes the Refiner product tasks for cleansing address information.

Note: This is only an installed product.

Clean

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.

Input

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

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 one output 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)

Fields Parameter

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
  • standard
  • list
  • raw
  • bs7666
  • simple

Refiner Result Codes

The below table describes the possible result codes and error messages:

Result Code Description
100 Complete PAF Match
200 Postcode Match
201 Postcode Match (Postcode changed)
202 Assume Postcode Correct
203 Assume Changed Postcode 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)
301 Full DPS Match (Ambiguous Organisation omitted)
400 Non-DPS Match (Street level)
-1 No Match Found
-2 Ambiguous Postcode
-3 Suggested Record
-4 Ambiguous Address
-5 International Address
-6 No Address Data Supplied
-7 Data License Error

Example

JSON Format

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

{
  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"
}
XML Format

http://localhost:81/afddata.pce?serial=333333&password=pwd&Data=Address&task=Clean&format=xml&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

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

Refiner Additional Options

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). This allows results to be returned with low confidence for an automated match
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
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

Line Squeezing

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.

For example: addr1:60@addr2@60:addr3:60 squeezes the address fields (minus the postcode) 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

Batch of POST Requests

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

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/afddata.pce?data=refiner&task=clean&serial=333333&password=pwd&fields=organisation@property@street@locality@town@county@postcode@list@udprn

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

Compatibility Information

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

Nearest Installed

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.

Database Parameters for Nearest

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 Nearest: section in afddata.ini

As a security precaution, only databases specified in afddata.ini can be connected to and the settings which are used are specified in that .ini file. You need to ensure the afddata.ini file is in your windows folder (e.g. c:\windows folder) and has a section called Nearest: where DBname is the name used in the DBConnect parameter for PCE calls.

This section requires the following settings to connect to the database:

Parameter Description
Type The Database Type – ODBC, Access, Paradox, or XBase.
Name The name of the DSN to connect to in the case of an ODBC database, or the filename in the case of Access, Paradox, or XBase databases.
UID The username if required for an ODBC Connection (can be omitted if not required).
PWD The password if required for an ODBC Connection (can be omitted if not required).
SQL The SQL String to use to Query your database (e.g. SELECT * FROM TABLE). Not required for Paradox or XBase.
Primary The name of the Primary Key Field in your Nearest database.
GridE The name of the field containing the Grid Easting values in your database. If your database does not contain grid references you will need to add a GridE and GridN field and use the product front-end or AFD Refiner to populate these fields with the grid references which Nearest requires to function.
GridN The name of the field containing the Grid Northing values in your database.
List Specifies the fields (comma separated) to use to construct the List. It is recommended that this contains either the Miles or Km field provided by PostcodeEverywhere to provide the distance followed by some of your database fields to identify the record to the user. The list item is often presented in order of distance to allow the user to select the required record. Even if you are going to construct your own list or not use a list it is recommended to configure this correctly for testing purposes.
[Nearest: phones4u]
Type=ODBC
Name=Phones4U
UID=username
PWD=password
SQL=SELECT * FROM NEAREST
Primary=Postcode
GridE=GridE
GridN=GridN
List=Miles,Postcode,Title

Nearest Example

JSON Format

http://localhost:81/afddata.pce?Data=Nearest&serial=333333&password=pwd&Task=fastfind&Fields=standard&DBConnect=Phones4u&miles=50&lookup=b111aa&maxquantity=1&format=json

{
  Result: "1",
  ErrorText: "",
  Item: [
    {
      @value: "1",
      Key: "202000170000",
      List: "Birmingham City Football Club",
      Miles: "1.1",
      Km: "1.8",
      Time: "",
      GBGridE: "409000",
      GBGridN: "286400",
      NIGridE: "616492",
      NIGridN: "153673",
      Latitude: "52.4755",
      Longitude: "-1.8689",
      TextualLatitude: "N 52° 28' 31\"",
      TextualLongitude: "W 1° 52' 8\"",
      Postcode: "B9 4NH",
      Organisation: "Phones 4u",
      Property: "",
      Street: "St Andrews Road",
      Locality: "",
      Town: "Birmingham",
      County: "",
      Phone: "0121 773 5781",
      Fax: "0121 773 4263"
    }
  ]
}

XML Format

http://localhost:81/afddata.pce?Data=Nearest&serial=333333&password=pwd&Task=fastfind&Fields=standard&DBConnect=Phones4u&miles=50&lookup=b111aa&maxquantity=1&format=xml

<AFDPostcodeEverywhere>
  <Result>1</Result>
  <ErrorText/>
  <Item value="1">
    <Key>202000170000</Key>
    <List>Birmingham City Football Club</List>
    <Miles>1.1</Miles>
    <Km>1.8</Km>
    <Time/>
    <GBGridE>409000</GBGridE>
    <GBGridN>286400</GBGridN>
    <NIGridE>616492</NIGridE>
    <NIGridN>153673</NIGridN>
    <Latitude>52.4755</Latitude>
    <Longitude>-1.8689</Longitude>
    <TextualLatitude>N 52° 28' 31"</TextualLatitude>
    <TextualLongitude>W 1° 52' 8"</TextualLongitude>
    <Postcode>B9 4NH</Postcode>
    <Organisation>Phones 4u</Organisation>
    <Property/>
    <Street>St Andrews Road</Street>
    <Locality/>
    <Town>Birmingham</Town>
    <County/>
    <Phone>0121 773 5781</Phone>
    <Fax>0121 773 4263</Fax>
  </Item>
</AFDPostcodeEverywhere>

Phone Validation

Phone Result Codes

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.

Phone Example

JSON Format

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: ""
}

XML Format

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>

Email Validation

A simple mistake in typing an email address makes it impossible for an email to reach the right recipient.

Email Result Codes

Result code 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

Result Code -2

Description
Format Invalid
Unknown Top Level Domain
Domain-Specific Format Invalid
Invalid Email, Mail Server Not Found
Mail Server Rejected Email Address

Additional Functionality for Email

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

  • The data file will contain a list of known variants for large well-known domains such as gmail.com.
  • For other domains if the validation fails it will try possible single character variants to suggest an alternative and provides it if it passes validation itself.
  • If the domain is fine but the first part of the address fails and contains a possibly misspelled name it will try the corrected variant.
  • Additionally if it contains a duplicated character (e.g. two dots), or unexpected punctuation or characters it will try without those and substituting any obvious ones (e.g. characters above numbers).

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.

Validation Types

Full Example

JSON Format

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
    }
  ]
}

XML Format

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>

Live Example

Validate email format, top-level domain, and server response for the full email address (if enabled on the server)

JSON Format

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
    }
  ]
}

XML Format

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>Present</FormatVerified>
    <Suggested/>
    <Spelling>0</Spelling>
    <NonStandard>0</NonStandard>
    <Reachable>1</Reachable>
    <Dummy>0</Dummy>
    <Throwaway>0</Throwaway>
    <Generic>1</Generic>
  </Item>
</AFDPostcodeEverywhere>

TLD Example

Validate email format is correct and the top-level domain exists.

JSON Format

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
    }
  ]
}

XML Format

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>

Format Example

Validates if the email address format is correct only.

JSON Example

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
    }
  ]
}

XML Example

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>

Local Example

Validate email format, top-level domain and for well-known domains carry out additional checks of the local portion of the address.

JSON Format

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
    }
  ]
}

XML Example

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>

Other Features

Determining the Product in Use

When integrating with Address Management products the same code will work with any of our Address Management products (AFD Postcode, AFD Postcode Plotter, AFD Postcode Plus and AFD Names & Numbers).

It is not normally necessary to determine which product has been used as you can integrate with one, e.g. Names & Numbers and the user can use any of our address management products – they will just have less data returned depending on the product they have. However, if for any reason, such as disabling/enabling features of your product - you can use the Product field if you wish to determine which product the user has and that has been used by the Service.

The Product field will contain one of the following values depending on the product being used:

  • AFD Postcode
  • AFD Postcode Plotter
  • AFD Postcode Plus
  • AFD Names & Numbers

Note that when carrying out a BankFinder operation AFD BankFinder will always be the product name returned.

DX Member Data

DX Members can have access to DX data from within Postcode Plus, Names & Numbers and the API. This enables you to lookup 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.

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

International Data

Customers signed up to use our International data service can lookup and search for international addresses in exactly the same way as you do for UK based addresses. The only difference in normal operation is the need to specify the Country or CountryISO code (as parameters in the GET request) of the country that you wish to use in all lookup, search and record retrieval operations.

Making use of the data returned

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

Notes regarding International addressing

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 which are available. For example while one country may have full address data from Organisation down, another may only be at street or even locality level. So you must accommodate for different levels of data coming back and therefore differing amounts of manual entry which may be required by users of your software to provide a complete address.