Autocomplete Migration

Overview

This guide helps you migrate from GetAddress'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

Feature	GetAddress	Ideal Postcodes
Endpoint	/autocomplete/{term}	/v1/autocomplete/addresses?query={term}
Authentication	api-key= parameter	api_key= parameter

Migration Steps

1. Update Address Suggestion Endpoint

Both APIs use similarly structured endpoints to retrieve address suggestions.

GetAddress:

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: Suggestions in suggestions array, display text in address field
• Ideal Postcodes: Suggestions in result.hits array, display text in suggestion field

From: GetAddress

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

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

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

4. Migrate Filter Parameters

GetAddress supports a filter object to restrict autocomplete results. Ideal Postcodes provides equivalent filtering via query parameters.

Filter Parameter Mapping

GetAddress Filter	Ideal Postcodes Equivalent	Notes
filter.postcode	postcode=	Filter by postcode
filter.residential=true	is_residential=true	Only residential addresses
filter.residential=false	is_organisational=true	Only business/organisational addresses
filter.town_or_city	post_town=	Filter by post town
filter.country	country=	Values: England, Scotland, Wales, Northern Ireland
filter.radius	box=	See geospatial filtering below

Example: Filtering by Location

From: GetAddress

POST https://api.getaddress.io/autocomplete/{term}?api-key=YOUR_KEY
Content-Type: application/json

{
  "filter": {
    "town_or_city": "London",
    "residential": true
  }
}

To: Ideal Postcodes

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

Geospatial Filtering

GetAddress uses a radius filter with centre coordinates:

{
  "filter": {
    "radius": {
      "km": "5",
      "longitude": -0.118092,
      "latitude": 51.509865
    }
  }
}

Ideal Postcodes uses a bounding box approach with the box parameter. Specify a comma-separated list of coordinates defining the box corners (west longitude, north latitude, east longitude, south latitude):

GET https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?query={term}&api_key=YOUR_KEY&box=-0.2,51.6,0.0,51.4

To convert a radius to a bounding box, calculate the corner coordinates from the centre point and desired distance.

Need Help?

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