Data8 Logo

Back

Find API Migration

This guide describes how to migrate from the GetAddress Find API to the Data8 AddressCapture API.

Both services let you retrieve every address for a UK postcode using a single request.

Due to the Data8 API using the Royal Mail PAF file, a license type must be declared as part of the request.

Key Differences

Feature GetAddress Data8
Endpoint /find/{postcode} /AddressCapture/GetFullAddress.json
Authentication ?api-key=your_api_key key=your_api_key
Response Root addresses array in response Results array in response

As well as API Keys, we also offer authentication via Username and Password, and JWT.

Please see the AddressCapture documentation page for more details.

Compatibility Layer

We have added some temporary endpoints, to offer a smooth transition from GetAddress to Data8. Where noted below, these endpoints offer a like-for-like service to GetAddress, using their mappings. These endpoints should only be used during the migration process, as they will be removed in the future. Warning will be given prior to removal.

To use the temporary endpoints, simply add webservices.data-8.co.uk/ as the top-layer domain within the URL.

Feature GetAddress Data8
Base URL https://getaddress.io/ https://webservices.data-8.co.uk/getaddress.io/
Find Endpoint /find/{postcode}?api-key=YOUR_KEY /find/{postcode}?api-key=YOUR_KEY

For permanent migration, please follow the steps below.

Migration Steps

1. Update Find Endpoint

Temporary Endpoint for Compatibility

We have added a temporary endpoint to offer compatiblity, while migrating from GetAddress to Data8. This will work in the same way as GetAddress, offering a like-for-like service.

GET https://webservices.data-8.co.uk/getaddress.io/find/{postcode}?api-key=YOUR_KEY

Important: This endpoint should only be used during the migration process. Warning will be given prior to removal of the temporary endpoint.

Permanent Migration

GetAddress:

GET https://api.getaddress.io/find/{postcode}?api-key=YOUR_KEY

Data8:

POST https://webservices.data-8.co.uk/AddressCapture/GetFullAddress.json?key=YOUR_KEY
Content-Type: application/json

Body:

{
    "postcode": "CH2 4NE",
		"licence": "WebClickFull",
}

2. Change Response Structure

2A: Expanded Format (?expand=true)

{
  "postcode": "M1 1AE",
  "latitude": 53.4837226,
  "longitude": -2.2446397,
  "addresses": [
    {
      "formatted_address": [
        "1 Piccadilly Gardens",
        "",
        "",
        "Manchester",
        "Greater Manchester"
      ],
      "thoroughfare": "Piccadilly Gardens",
      "building_name": "",
      "sub_building_name": "",
      "sub_building_number": "",
      "building_number": "1",
      "line_1": "1 Piccadilly Gardens",
      "line_2": "",
      "line_3": "",
      "line_4": "",
      "locality": "",
      "town_or_city": "Manchester",
      "county": "Greater Manchester",
      "district": "Manchester",
      "country": "England",
      "residential": false
    }
  ]
}

Data8 Standard Format:

{
  "Status": {
    "Success": true,
    "ErrorMessage": null,
    "CreditsRemaining": 24
  },
  "Results": [
    {
      "Address": {
        "Lines": [
          "Unit 4",
          "Venture Point",
          "Stanney Mill Road",
          "Little Stanney",
          "CHESTER",
          "",
          "CH2 4NE"
        ]
      },
      "RawAddress": {
        "Organisation": "",
        "Department": "",
        "AddressKey": 41034777,
        "OrganisationKey": 0,
        "PostcodeType": "S",
        "BuildingNumber": 0,
        "SubBuildingName": "UNIT 4",
        "BuildingName": "VENTURE POINT",
        "DependentThoroughfareName": "",
        "DependentThoroughfareDesc": "",
        "ThoroughfareName": "STANNEY MILL",
        "ThoroughfareDesc": "ROAD",
        "DoubleDependentLocality": "",
        "DependentLocality": "LITTLE STANNEY",
        "Locality": "CHESTER",
        "Postcode": "CH2 4NE",
        "Dps": "1E",
        "PoBox": "",
        "PostalCounty": "",
        "TraditionalCounty": "CHESHIRE",
        "AdministrativeCounty": "CHESHIRE WEST AND CHESTER",
        "CountryISO2": null,
        "UniqueReference": null,
        "Location": {
          "Easting": 341695,
          "Northing": 374571,
          "GridReference": "SJ416745",
          "Longitude": -2.8755859,
          "Latitude": 53.2649333,
          "CountyCode": null,
          "County": null,
          "DistrictCode": "E06000050",
          "District": "Cheshire West and Chester",
          "WardCode": "E05012216",
          "Ward": "Gowy Rural",
          "Country": "England",
          "Constituency": null
        },
        "AdditionalData": [
          {
            "Name": "LatLongType",
            "Value": "Building"
          }
        ]
      }
    }
  ]
}

Field Mapping Table:

GetAddress Field Data8 Field Notes
postcode RawAddress.Postcode Equivalent Match
latitude RawAddress.Location.Latitude Per-postcode → Per-address (more accurate)
longitude RawAddress.Location.Longitude Per-postcode → Per-address (more accurate)
formatted_address[] N/A Address.Lines[]
thoroughfare RawAddress.ThoroughfareName + RawAddress.ThoroughfareDesc Concatenate street name + type
building_name RawAddress.BuildingName Equivalent Match
sub_building_name RawAddress.SubBuildingName Equivalent Match
sub_building_number N/A Not supplied by PAF
building_number RawAddress.BuildingNumber Equivalent Match
line_1 Address.Lines[0] Equivalent Match
line_2 Address.Lines[1] Equivalent Match
line_3 Address.Lines[2] Equivalent Match
line_4 Address.Lines[3] Equivalent Match
town_or_city RawAddress.Locality Field renamed from post_town/locality
county RawAddress.PostalCounty Equivalent Match
district RawAddress.Location.District Equivalent Match
country RawAddress.Location.Country Equivalent Match
locality RawAddress.DependentLocality Field renamed
residential N/A Infer based on Organisation presence; no explicit field

2B: Simple Format

GetAddress Simple Format:

{
  "postcode": "SW1A 2AA",
  "latitude": 51.5034066,
  "longitude": -0.1275923,
  "addresses": [
    "10 Downing Street, , , , , London, ",
    "11 Downing Street, , , , , London, ",
    "12 Downing Street, , , , , London, "
  ]
}

Each address string follows this fixed 7-element comma-separated format:

"line1,line2,line3,line4,locality,Town/City,County"

Position-to-Field Mapping:

Array Position GetAddress Field Data8 Field
address[0] line1 Address.Lines[0]
address[1] line2 Address.Lines[1]
address[2] line3 Address.Lines[2]
address[3] line4 Address.Lines[3]
address[4] locality Address.Lines[4]
address[5] Town/City Address.Lines[5]
address[6] County Maximum of 6 lines are returned by default.

Key Changes:

  • data.addresses → data.Results
  • String parsing → Direct property access
  • Single lat/lng for postcode → Individual lat/lng per address (more accurate)
  • Access to additional data (UPRN, UDPRN, eastings, northings)

Migration Code Examples

From: GetAddress

async function lookupPostcode(postcode) {
  const response = await fetch(
    `https://api.getaddress.io/find/${postcode}?api-key=${API_KEY}&expand=true`,
  );
  const data = await response.json();

  return data.addresses.map((address) => ({
    line1: address.line_1,
    line2: address.line_2,
    line3: address.line_3,
    line4: address.line_4,
    town: address.town_or_city,
    county: address.county,
    postcode: data.postcode,
    latitude: data.latitude,
    longitude: data.longitude,
  }));
}

To: Data8

async function lookupPostcode(postcode) {
  const response = await fetch("https://webservices.data-8.co.uk/AddressCapture/GetFullAddress.json", {
    method: "POST",
    body: JSON.stringify({
      postcode: postcode,
      licence: "WebClickFull"
    })
  });
  const data = await response.json();

  // Data8 returns one object with Address and RawAddress per item
	return data.Results.map((address) => ({
    line1: address.Address.Lines[0],
    line2: address.Address.Lines[1],
    line3: address.Address.Lines[2],
    line4: address.Address.Lines[3],
    locality: address.RawAddress.DependentLocality, 
    town: address.RawAddress.Locality,
    county: address.RawAddress.PostalCounty,
    postcode: address.RawAddress.Postcode,
    latitude: address.RawAddress.Location.Latitude,
    longitude: address.RawAddress.Location.Longitude,
  }));
}

Need Help?

We are available 9am to 5:30pm UK time by phone +44 (0)151 355 4555 or email helpdesk@data-8.co.uk for migration assistance.

An error has occurred. This application may no longer respond until reloaded. Reload 🗙