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.

Migration Steps

1. Update Find Endpoint

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.