Skip to main content

Autocomplete Migration

Overview​

This guide helps you migrate from GetAddress.io's Autocomplete API to Ideal Postcodes' Address Finder API.

Both APIs use a two-step process for autocomplete, which involves getting address suggestions given user input and then resolving the selected suggestion into a full address.

Key Differences​

FeatureGetAddress.ioIdeal Postcodes
Endpoint/autocomplete/{term}/v1/autocomplete/addresses?query={term}
Authenticationapi-key= parameterapi_key= parameter

Migration Steps​

1. Update Address Suggestion Endpoint​

Both APIs use similarly structured endpoints to retrieve address suggestions.

GetAddress.io:

GET https://api.getaddress.io/autocomplete/{term}?api-key=YOUR_KEY

Ideal Postcodes:

GET https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?query={term}&api_key=YOUR_KEY

2. Map to Ideal Postcodes Suggestion ID​

Both APIs return suggestion lists with IDs, but the response structure differs:

  • GetAddress.io: Suggestions in suggestions array, display text in address field
  • Ideal Postcodes: Suggestions in result.hits array, display text in suggestion field

From: GetAddress.io​

{
  "suggestions": [
    {
      "address": "10 Downing Avenue, Guildford, Surrey, GU2 7SY",
      "url": "/get/VGp4ZzNrNXZMbVJ5OG1UcWg3YjJGNA",
      "id": "VGp4ZzNrNXZMbVJ5OG1UcWg3YjJGNA"
    },
    {
      "address": "10 Downing Close, Bradford, West Yorkshire, BD3 0QT",
      "url": "/get/UXdlOXJwTDJuNGNaM3hKaDF2OGtTNg",
      "id": "UXdlOXJwTDJuNGNaM3hKaDF2OGtTNg"
    }
  ]
}

To: Ideal Postcodes​

{
  "result": {
    "hits": [
      {
        "id": "paf_10093397",
        "suggestion": "10 Downing Avenue, Guildford, GU2",
        "udprn": 10093397,
        "urls": {
          "udprn": "/v1/udprn/10093397"
        }
      },
      {
        "id": "paf_1550664",
        "suggestion": "10 Downing Close, Bradford, BD3",
        "udprn": 1550664,
        "urls": {
          "udprn": "/v1/udprn/1550664"
        }
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}

Conversion​

When migrating your code, update the response parsing:

From: GetAddress.io​

// Access suggestions
const suggestions = data.suggestions;
const firstSuggestion = suggestions[0];
const displayText = firstSuggestion.address;
const suggestionId = firstSuggestion.id;

To: Ideal Postcodes​

// Access suggestions
const suggestions = data.result.hits;
const firstSuggestion = suggestions[0];
const displayText = firstSuggestion.suggestion;
const suggestionId = firstSuggestion.id;

3. Update Address Resolve Endpoint​

From: GetAddress.io​

GET https://api.getAddress.io/get/{id}?api-key={api-key}
{
    "postcode": "NN1 3ER",
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "formatted_address": [
        "10 Watkin Terrace",
        "",
        "",
        "Northampton",
        "Northamptonshire"
     ],
    "thoroughfare":  "Watkin Terrace",
    "building_name":  "",
    "sub_building_name":  "",
    "sub_building_number":  "",
    "building_number":  "10",
    "line_1":  "10 Watkin Terrace",
    "line_2":  "",
    "line_3":  "",
    "line_4":  "",
    "locality":  "",
    "town_or_city":  "Northampton",
    "county":  "Northamptonshire",
    "district":  "Northampton",
    "country":  "England",
    "residential":  true
}

To: Ideal Postcodes​

GET https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/{address_id}/gbr?api_key=YOUR_KEY
{
  "postcode": "GU2 7SY",
  "postcode_inward": "7SY",
  "postcode_outward": "GU2",
  "post_town": "Guildford",
  "dependant_locality": "",
  "double_dependant_locality": "",
  "thoroughfare": "Downing Avenue",
  "dependant_thoroughfare": "",
  "building_number": "10",
  "building_name": "",
  "sub_building_name": "",
  "po_box": "",
  "department_name": "",
  "organisation_name": "",
  "udprn": 10093397,
  "postcode_type": "S",
  "su_organisation_indicator": "",
  "delivery_point_suffix": "2D",
  "line_1": "10 Downing Avenue",
  "line_2": "",
  "line_3": "",
  "premise": "10",
  "longitude": -0.6002693,
  "latitude": 51.2385077,
  "eastings": 497810,
  "northings": 149745,
  "country": "England",
  "traditional_county": "Surrey",
  "administrative_county": "Surrey",
  "postal_county": "Surrey",
  "county": "Surrey",
  "district": "Guildford",
  "ward": "Onslow",
  "uprn": "100061387496",
  "id": "paf_10093397",
  "country_iso": "GBR",
  "country_iso_2": "GB",
  "county_code": "",
  "language": "en",
  "umprn": "",
  "dataset": "paf"
}

Field Mapping​

The resolved address contains many fields that need to be mapped. Key differences include:

  • Address Lines: GetAddress.io uses 4 lines, Ideal Postcodes uses 3
  • Field Naming: town_or_city → post_town, locality → dependant_locality
  • Additional Data: Ideal Postcodes provides UPRN, UDPRN, eastings, and northings

For a complete field mapping reference including TypeScript types and migration code examples, see the Address Field Mapping Reference.

Need Help?​

We are available 9am to 5pm UK time on chat or email support@ideal-postcodes.co.uk for migration assistance.