Home / Docs / API Reference / Address Autocomplete

Address Autocomplete API Documentation

Fast, accurate postal address validation

The Swiftcomplete Address Autocomplete API provides realtime address suggestions as you type, eliminating typos and mistakes and reducing the time it takes to find accurate postal addresses.

If you are looking for a general places or location search, see our Places API Documentation.

If you need any help integrating our Address Autocomplete API into your website or application, get in touch and one of our product experts will help get you started.

In this documentation:

Data Coverage Authentication Integration Options JavaScript Integration API Integration

Data Coverage

The following countries are available in the Swiftcomplete Address Autocomplete API:

Australia

Canada

Denmark

Japan

Liechtenstein

Luxembourg

Norway

Switzerland

United Kingdom

Coverage for the whole of the UK (England, Northern Ireland, Scotland & Wales) from the Royal Mail PAF database.

United States

Authentication

Each request must be authenticated with an Address Autocomplete API key, which you can create in your Swiftcomplete account:

1. Sign in if you're already registered, or create a Swiftcomplete account if you're new to the service.

2. Go to the API section and create an Address Autocomplete API Key.

Integration Options

Once you've created an Address Autocomplete API Key, you can integrate the address lookup onto your website or checkout with the JavaScript Autocomplete Integration, or build a server side integration using the API or with the npm package.

JavaScript Integration

The JavaScript Swiftcomplete Address Autocomplete integration is a code snippet that can be included on your website or in your checkout to provide address search with realtime suggestions as you type.

Step 1: Include the code snippet

Firstly, copy & paste the code snippet into the <head> section of your HTML, before the closing </head> tag.

Make sure you only copy the code snippet once, even if you have multiple address fields on your page:

Code snippet

<script type="text/javascript">
    !function (e, t, c) {
    e.swiftcomplete = e.swiftcomplete || {};
    var s = t.createElement("script");
    s.async = !0, s.src = c;
    var r = t.getElementsByTagName("script")[0];
    r.parentNode.insertBefore(s, r)
    }(window, document, "https://script.swiftcomplete.com/js/swiftcomplete.js");
</script>

Step 2: Add Address Autocomplete functionality to a text field

Now copy this script and paste it directly after the previous code snippet, before the closing <head> tag.

To get the script running, replace "INSERT_KEY_HERE" with your Address Autocomplete API key, and replace "INSERT_TEXT_FIELD_ID_HERE" with the ID of an existing textbox on your page.

The script initialises Swiftcomplete Places on your existing textbox, restricts searching to Great Britain and logs the record and coordinates to the developer console when you select a result from the list of autocomplete suggestions.

Initialise Swiftcomplete Places on page load

<script type="text/javascript">
    /*#########################################
    Insert your API key here to run the demo:
    #########################################*/
    var SWIFTCOMPLETE_API_KEY = "INSERT_KEY_HERE";
    var SWIFTCOMPLETE_SEARCH_FIELD_ID = "INSERT_TEXT_FIELD_ID_HERE";

    function initialiseSwiftcomplete() {
        swiftcomplete.runWhenReady(function () {
            // Attach search functionality to existing field
            swiftcomplete.controls["Search field"] = new swiftcomplete.PlaceAutoComplete({
                field: document.getElementById(SWIFTCOMPLETE_SEARCH_FIELD_ID),
                key: SWIFTCOMPLETE_API_KEY,
                searchFor: ""
            });

            // Restrict searching to just Great Britain (leave this out to search all available countries)
            swiftcomplete.controls["Search field"].setCountries('gb');

            // Add event listener to listen for when a result has been selected
            document.getElementById(SWIFTCOMPLETE_SEARCH_FIELD_ID).addEventListener('swiftcomplete:place:selected', function (e) {
                // Record
                console.log(e.detail.result.record);

                // Coordinates
                console.log(e.detail.result.geometry.centre);
            }, false);
        });
    }

    window.addEventListener("load", initialiseSwiftcomplete, false);
</script>

Step 3: Test your integration

Refresh your page, and try searching in your existing text field. The record and coordinates are printed to the developer console when you click a result from the list of suggestions.

API Integration

Integrate the Swiftcomplete Places API for general location and place search functionality.

Parameters

keystringrequired
A Places API Key.
textstring
A full or partial search term, such as a postcode, street or city name. Text can be provided keystroke by keystroke for autocomplete suggestions as you type.
biasTowardsstring
WGS84 coordinates in the format "latitude,longitude".
Prioritises results near your provided coordinates to increase relevance and reduce the number of keystrokes it takes to find a result.
The API will prioritise results near your approximate location (determined by your IP address) if this parameter is not provided.
countriesstring
A comma separated list of ISO 3166-1 alpha-2 country codes to restrict searching to certain countries (e.g. "ca,us" to restrict searching to Canada and the United States).
The API will search all available countries if this parameter is not provided.
distanceUnitsstringdefault: metric
Unit of measurement to display how far away the address if you provide coordinates to bias towards:
- metric
- imperial
maxResultsintegerdefault: 5
Max number of results to return (up to 5).
searchForstring
A comma separated list of result types to restrict the types of results returned.
Types are hierarchical, so providing "transit" includes everything in the transit category, "transit.airport" only returns airports and "transit.airport.large" only returns the largest airports.
Use the hierarchical types to filter results to only include exactly what you're looking for.
First level:
- placePostcodes and all types of settlements (cities, towns, villages, counties, provinces etc.)
- roadAll types of roads
- transitAll types of public transport
Second level:
- place.areaPostcodes and counties, states etc.
- place.settlementCities, towns, villages etc.
- transit.airportAirports
- transit.metroMetro and London Underground stops
- transit.railwayRailway stations
- transit.tramTram stops
Third level:
- place.area.countyCounties
- place.area.postcodePostcodes, ZIP codes etc.
- place.area.countryCountries
- place.area.stateStates
- place.area.provinceProvinces
- place.area.territoryTerritories
- place.settlement.largeLarge cities
- place.settlement.mediumCities & towns
- place.settlement.smallDistricts, villages & hamlets
- transit.airport.largeLarge international airports
- transit.airport.mediumMedium regional airports
- transit.metro.station.gblondondlrLondon DLR stations
- transit.metro.station.gblondonundergroundLondon Underground stations
- transit.tram.stop.gbcroydontramlinkLondon tram stops (Croydon Tramlink)
- transit.tram.stop.gbedinburghtramsEdinburgh Tram stops
- transit.tram.stop.gbmanchestermetrolinkManchester Metrolink tram stops
- transit.tram.stop.gbnottinghamnetNottingham NET tram stops
- transit.tram.stop.gbsheffieldsupertramSheffield Supertram tram stops
- transit.tram.stop.gbwestmidlandsmetroWest Midlands Metro tram stops
For example, pass "place.area.country,transit" to only search for country names and public transport.
The API will search for all data types if searchFor is not provided.

Sample API Request

https://api.swiftcomplete.com/v1/places/?key=INSERT_KEY_HERE&countries=gb&biasTowards=52.929666,-1.275370&text=nottingham&maxResults=1

API Response

primary.textstring
A simplified summary of the main part of the address
primary.highlightsint[]
Pairs of indexes into primary.text to indicate which characters have been matched. e.g. "[0,3,5,8]" indicates characters 0-3 and 5-8 have been matched.
secondary.textstring
A simplified summary of the secondary description of the address
secondary.highlightsint[]
The same as primary.highlights but for secondary.text
typestring
A hierarchical type description of the address separated by full stops.
See searchFor for a list of types.
recordobject
A text description of the result.
geometry.centre.latfloat
Latitude of the centre point of the address
geometry.centre.lonfloat
Longitude of the centre point of the address
distance.unitsstring
Unit of measurement to display how far away the address is from your provided coordinates
distance.measurementfloat
Distance the address is from your provided coordinates, in units specified by distance.units

Sample API Response

[
    {
        "primary": {
            "text": "Nottingham",
            "highlights": [
                0,
                9
            ]
        },
        "secondary": {
            "text": "East Midlands",
            "highlights": []
        },
        "type": "place.settlement.large",
        "record": {
            "country": {
                "text": "England"
            },
            "region": {
                "text": "East Midlands"
            },
            "county": {
                "text": "City of Nottingham"
            },
            "postcode": {
                "text": "NG1"
            },
            "primarylocality": {
                "text": "Nottingham",
                "highlights": [
                    0,
                    9
                ]
            }
        },
        "geometry": {
            "centre": {
                "lat": 52.9562,
                "lon": -1.1512
            }
        },
        "distance": {
            "units": "mi",
            "measurement": 5.5,
            "from": {
                "type": "biasLocation",
                "biasTowardsIndex": 0
            }
        }
    }
]