All tutorials
Swiftcomplete Address Autocomplete API: REST Integration Guide
intermediate
The Swiftcomplete Public API provides structured and real-time address suggestions based on user input. You can use it for:
- Traditional address autocomplete
- what3words address search
- Location-aware search suggestions
- Postal address resolution
Base URL: https://api.swiftcomplete.com/v1
Authentication: All endpoints require an API key provided via ?api_key=YOUR_KEY query parameter.
If you need any help integrating our Swiftcomplete API into your website or application, get in touch, and one of our product experts will help get you started.
1Authentication
Each request must be authenticated with a Swiftcomplete API key, which you can create in your Swiftcomplete account:
2Integration options
Once you’ve created a Swiftcomplete API Key, you can choose the integration method that best fits your application:
1. ✨ Integrate Directly with the REST API
Allows developers to build bespoke integrations in any programming language. You send a search term and receive structured address suggestions in real time.
- Full control over UI/UX
- Supports autocomplete, lookup, and full address resolution
- Jump to API Reference →
2. 📄 Use the JavaScript Web Component
Easily add the Swiftcomplete search box to any web form or checkout page using our drop-in JS SDK.
- Real-time address suggestions
- Keyboard and mouse interactions
- Easy event hooks (e.g. selected, manual entry)
- JavaScript Integration Guide
3. 🛒 Use Prebuilt E-Commerce Plugins
Install Swiftcomplete on your store without writing custom code:
- WooCommerce Plugin
- BigCommerce Integration
- Ecwid Integration
- Shopify Plus (available soon as a plugin)
3API Reference
A technical breakdown of the Swiftcomplete endpoint, parameters, request formatting, and usage.
GET /swiftlookup/
Real-time address, postcode, and what3words suggestions.
| Name | Required | Type | Description | Example |
|---|---|---|---|---|
| key | yes | string | Your Swiftcomplete API key | xxxxxxx |
| text | no | string | Search term or partial input | W2 5EU / 65 alfred rd / filled.count.soap / London |
| biasTowards | no | string | what3words or lat,lng coordinate for prioritizing results | coordinates, what3words |
| container | no | string | Object containing parameters for managing the autocomplete container. | { V1;65|ALFRED Road|LONDON|W2;51.521198;-0.196309 } |
| searchFor | no | string | A comma-separated list of result types to filter results. 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. View the table linked to this page. | 'what3words, address, place, road, transit' |
| countries | no | string | ISO alpha-2 country codes | 'ca,uk' |
| maxDistance | no | string | A distance in km to limit the search radius from the biasTowards coordinate.Max distance (meters) | 3000 |
| maxResults | no | string | Maximum number of results to display. Note If the results are more than maxResults=100 than pageFrom parameter needs to be used to loop the results per 100 records.Max results (1–5 typical) | 5 (for address, 3 (for what3words), 100 (container for address) |
| populateIndex | no | string | Index for populating the autocomplete field. Used to obtain detailed information about a result in the response array. For example, to obtain full information for the first record, pass populatedIndex=0, or for the second, pass populatedIndex=1 and so on. | 1 |
| populateLineCount | no | string | Number of lines to populate in the autocomplete field. If used the users don’t have a specific labeled address lines. | 5 |
| distanceUnits | no | string | Unit of measurement for distance display metric → Return distance in kilometres, unless under 1km in which case metres are returned imperial → Return distance in miles, unless under 0.1 miles in which case feet are returned | ‘metric’ or ‘imperial’ or ‘km’ or ‘miles’ or ‘feet’ |
| groupResults | no | boolean | A comma-separated list of result types to filter results. 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. | true |
| populateLineFormat | no | string | Format for populating lines in the autocomplete field. lineFormat0=AddressLine1, lineFormat1=AddressLine2, lineFormat2=AddressLine3, lineFormat3=TertiaryLocality, SecondaryLocality, PrimaryLocality, STATEABBREVIATION, lineFormat4=POSTCODE, lineFormat5=PrimaryCountry, lineFormat6=what3words. | [..] |
| pageFrom | no | string | Indicates the starting page for results. | 1 |
4Example Usage
See example API requests and the expected responses for autocomplete and lookup.
Example Request
curl "https://api.swiftcomplete.com/v1/swiftlookup/?text=221B%20Baker%20Street&key=YOUR_API_KEY"Copied
Example Response
[ { "primary": { "text": "221 Baker St", "highlights": [ 0, 2, 4, 8, 10, 11 ] }, "secondary": { "text": "Alvaston", "highlights": [] }, "type": "address.residential.building.data", "isContainer": false, "geometry": { "centre": { "lat": 52.896976, "lon": -1.435977, "type": "postcode" } }, "populatedRecord": { "lines": [ "221 Baker Street", "", "", "Alvaston, Derby", "DE24 8SG", "United Kingdom", "" ], "licenses": [], "label": "221 Baker Street\nAlvaston\nDERBY\nDE24 8SG\nUnited Kingdom", "data": { "postalCode": { "text": "DE24 8SG", "isFullPostalCode": true, "gb": { "incode": { "text": "8SG" }, "postcodeSector": { "text": "8" }, "postcodeUnit": { "text": "SG" }, "outcode": { "text": "DE24" }, "postcodeArea": { "text": "DE" }, "postcodeDistrict": { "text": "24" } } }, "business": null, "subBuilding": null, "building": { "name": null, "number": { "text": "221" } }, "road": { "primary": { "text": "Baker Street" }, "secondary": null }, "poBox": null, "country": { "primary": { "text": "United Kingdom", "iso3166-2": "GB" }, "secondary": null }, "place": { "primary": { "text": "DERBY" }, "secondary": { "text": "Alvaston" }, "tertiary": null }, "admin": { "stateProvince": null, "stateProvinceAbbreviation": null, "gb": { "county": null, "ceremonialCounty": { "text": "Derbyshire", "code": null }, "region": { "text": "East Midlands", "code": "E12000004" }, "ward": { "text": "Alvaston North", "code": "E05015509" }, "district": null, "londonBorough": null, "innerOuterLondon": null, "unitaryAuthority": { "text": "Derby", "code": "E06000015" } } } } }, "countryCode": "GB" } ]
Copied
5API Response Fields
Explore all the fields returned in a standard autocomplete API response, including type definitions and examples.
| Name | Type | Description | Example |
|---|---|---|---|
| primary.text | string | A simplified summary of the main part of the address. | Nottingham |
| primary.highlights | int[] | Indexes into primary.text to indicate matched characters. | [0,9] |
| secondary.text | string | A summary of the secondary description of the address. | East Midlands |
| secondary.highlights | int[] | Indexes into secondary.text to indicate matched characters. | [] |
| type | string | A hierarchical type description of the address. | place.settlement.large or what3words |
| record | object | A text description of the result. | {"country": { "text": "England" }, "postcode": { "text": "NG1" }} |
| geometry.centre.lat | float | Latitude of the centre point of the address. | 52.9562 |
| geometry.centre.lon | float | Longitude of the centre point of the address. | -1.1512 |
| geometry.centre.type | string | Type of the centre point of the address. | address |
| distance.units | string | Unit of measurement for distance | mi |
| distance.measurement | float | Distance of the address from provided coordinates. | 5.5 |
| distance.type | string | Type of distnace | biasTowards |
| distance.geometry | object | Centre of the coordinates | { "centre": { "lat": 51.4508, "lon": -3.224277 } } |
| isContainer | boolean | Does the address contains more addresses? | TRUE |
| container | string | Object containing parameters for managing the autocomplete container. | V1;Sappers Farm Cottage|Cranfield Park Road|WICKFORD|SS12;51.597130;0.531537 |
| countryCode | string | An ISO 3166-1 alpha-2 country code. | GB |
| populateRecord | object | Contains lines, licenses, and label. | { "lines": [ "Tile House", "CF64 4HE", "United Kingdom" ] } |
| populateRecord.lines | string | The fully formatted postal address, line by line. | |
| populateRecord.label | string | The fully formatted postal address, in a label format. | |
| populateRecord.licenses | string | The licenses of the addresses |
6Error Handling
Review the possible API errors and HTTP status codes, and how to resolve them.
| Code | Description | Error message |
|---|---|---|
| 200 | Success | |
| 400 | 1. Invalid what3words Bias, 2. Malformed biasTowards, 3. Invalid maxResults number | 1. The what3words address provided was not valid, 2. Expected a list of WGS84 `latitude, longitude` pairs separated by commas, however when split, the list was length 1, 3. Expected a number up to a maximum of 5, received 100 |
| 401 | Invalid API key | Invalid API key. Please provide a valid API key in the query string or as a header |
| 403 | Free trial expired | Your free trial has expired. Please sign in to your account and purchase credits to continue using the service. |
| 429 | Rate limited | Too many requests - wait or upgrade |
7Troubleshooting
Need help, or have any questions? Get in touch with our customer support team at support@swiftcomplete.com, and we’ll help you get started with the JavaScript integration for the Swiftcomplete API.