@swiftcomplete/address-autocomplete

Description

This package provides address autocomplete using the Swiftcomplete Places API.

Using this package, you can search for addresses, streets, postcodes and places using full or partial query strings.

The underlying API can prioritise results near a coordinate, and can handle missing information and mistakes.

Installation

npm install @swiftcomplete/address-autocomplete

Authentication

Each request needs to be authenticated with an API key, which you can obtain by creating a Swiftcomplete account.

Request flow

Each session should call autocomplete() for each keystroke to obtain a list of suggestions, and must finish by calling populateResult(index, suggestions) to select an address.

The only occasion a session should end without calling populateResult() is if you can't find your address.

If you build your integration incorrectly without calling populateResult(), your account will be billed per keystroke which is far less cost effective.

Example: Search for an address

const swiftcompleteAddressAutocomplete = require('@swiftcomplete/address-autocomplete');

swiftcompleteAddressAutocomplete.setAPIKey('INSERT-KEY-HERE');

// Call swiftcompleteAddressAutocomplete.autocomplete for each keystroke until your address appears in the list of results
let autocompleteResults = await swiftcompleteAddressAutocomplete.autocomplete('100 champs elysees par');

// Select the 1st result in the list (index 0)
const selectIndex = 0;

let result = await swiftcompleteAddressAutocomplete.populateResult(selectIndex, autocompleteResults);

console.log(result.suggestions[selectIndex]);

Example: Using container searching

Container searching can be used to let users search by any part of an address, whilst requiring a full address to be selected.

The service returns a list of addresses to choose from if a street or postcode container ID is passed in the options object.

const swiftcompleteAddressAutocomplete = require('@swiftcomplete/address-autocomplete');

swiftcompleteAddressAutocomplete.setAPIKey('INSERT-KEY-HERE');

// Call swiftcompleteAddressAutocomplete.autocomplete for each keystroke until your address appears in the list of results
let autocompleteResults = await swiftcompleteAddressAutocomplete.autocomplete('av des champs elysees par');

// As autoCompleteResults[0].isContainer == true, set container = autoCompleteResults[0].container to view addresses on the street
// Make sure to clear the query text
let containerResults = await swiftcompleteAddressAutocomplete.autocomplete('', {
    container: autocompleteResults.suggestions[0].container
});

// Select the 5th result in the container result list (index 4)
const selectIndex = 4;

let result = await swiftcompleteAddressAutocomplete.populateResult(selectIndex, containerResults);

console.log(result.suggestions[selectIndex]);

Example: Searching within containers

It's possible to search within containers (e.g. for a building number) to further narrow down the results.

const swiftcompleteAddressAutocomplete = require('@swiftcomplete/address-autocomplete');

swiftcompleteAddressAutocomplete.setAPIKey('INSERT-KEY-HERE');

// Call swiftcompleteAddressAutocomplete.autocomplete for each keystroke until your address appears in the list of results
let autocompleteResults = await swiftcompleteAddressAutocomplete.autocomplete('av des champs elysees par');

// As autoCompleteResults[0].isContainer == true, set container = autoCompleteResults[0].container to view addresses on the street
// Clear the query text, and set to a building name / number to narrow down the results
let containerResults = await swiftcompleteAddressAutocomplete.autocomplete('100', {
    container: autocompleteResults.suggestions[0].container
});

// Select the first result in the filtered result list (index 0)
const selectIndex = 0;

let result = await swiftcompleteAddressAutocomplete.populateResult(selectIndex, containerResults);

console.log(result.suggestions[selectIndex]);

Customise the response with the optional options object

It's possible to pass in an optional options object to customise the response. Each field is optional within the object:

biasTowards

Prioritises results near a latitude, longitude coordinate or IP address. IP addresses resolve to a general area and aren't always accurate or precise. ("latitude,longitude" or "x.x.x.x")

countries

Restrict searching to a list of two-letter country codes. e.g. "gb,fr" to only search within the United Kingdom and France. Default is "", which searches all available countries

container

Restricts searching to a specific street or postcode. Obtained from result[x].container

distanceUnits

Unit of measurement to display how far away the address is from your coordinate or IP address ("metric", "imperial", "m", "km", "ft", "mi", default: "metric")

maxDistance

A distance in kilometres to limit the search radius from the biasTowards coordinate

maxResults

Max number of interim autocomplete or container results to return (up to 5, default: 1)

const swiftcompleteAddressAutocomplete = require('@swiftcomplete/address-autocomplete');

swiftcompleteAddressAutocomplete.setAPIKey('INSERT-KEY-HERE');

// Using the options object to suggest the nearest three addresses with building number "166" to a coordinate in France.
let autocompleteResults = await swiftcompleteAddressAutocomplete.autocomplete('166', {
    biasTowards: '48.88635,2.29497',
    countries: 'fr',
    maxResults: 3
});

console.log(autocompleteResults);

Response field descriptions

• primary.text - A simple description of the address, usually the building & street
• secondary.text - A simple description of the location, usually the city
• geometry.centre - The coordinates of the address
• geometry.centre.type - The accuracy of the coordinates, either "address", "street" or "postcode"
• distance - How far the address is from your coordinates
• distance.geometry.centre - Your original coordinates
• populatedRecord.lines - The fully formatted postal address, line by line
• populatedRecord.label - The fully formatted postal address, in a simple label format

Data coverage

Swiftcomplete address autocomplete is currently available in the following countries:

• Denmark
• France
• Liechtenstein
• Luxembourg
• United Kingdom

We regularly update and expand our data coverage - contact us if there's a country or dataset that isn't listed and we'll let you know where it is on our priority list.