# Autocomplete Migration

## Overview[​](#overview "Direct link to 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[​](#key-differences "Direct link to Key Differences")

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

## Migration Steps[​](#migration-steps "Direct link to Migration Steps")

### 1. Update Address Suggestion Endpoint[​](#1-update-address-suggestion-endpoint "Direct link to 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[​](#2-map-to-ideal-postcodes-suggestion-id "Direct link to 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[​](#from-getaddress "Direct link to 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[​](#to-ideal-postcodes "Direct link to 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[​](#conversion "Direct link to Conversion")

When migrating your code, update the response parsing:

#### From: GetAddress[​](#from-getaddress-1 "Direct link to From: GetAddress")

```
// Access suggestions

const suggestions = data.suggestions;

const firstSuggestion = suggestions[0];

const displayText = firstSuggestion.address;

const suggestionId = firstSuggestion.id;
```

#### To: Ideal Postcodes[​](#to-ideal-postcodes-1 "Direct link to 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[​](#3-update-address-resolve-endpoint "Direct link to 3. Update Address Resolve Endpoint")

#### From: GetAddress[​](#from-getaddress-2 "Direct link to 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[​](#to-ideal-postcodes-2 "Direct link to 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[​](#field-mapping "Direct link to 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](/docs/migrate/getaddressio/field-mapping.md).

### 4. Migrate Filter Parameters[​](#4-migrate-filter-parameters "Direct link to 4. Migrate Filter Parameters")

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

#### Filter Parameter Mapping[​](#filter-parameter-mapping "Direct link to 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[​](#example-filtering-by-location "Direct link to Example: Filtering by Location")

##### From: GetAddress[​](#from-getaddress-3 "Direct link to 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[​](#to-ideal-postcodes-3 "Direct link to 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[​](#geospatial-filtering "Direct link to 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?[​](#need-help "Direct link to Need Help?")

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