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:

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 a Swiftcomplete API Key.

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.

3. 🛒 Use Prebuilt E-Commerce Plugins

Install Swiftcomplete on your store without writing custom code:

3API Reference

A technical breakdown of the Swiftcomplete endpoint, parameters, request formatting, and usage.

GET /swiftlookup/

Real-time address, postcode, and what3words suggestions.

NameRequiredTypeDescriptionExample
keyyesstringYour Swiftcomplete API keyxxxxxxx
textnostringSearch term or partial inputW2 5EU / 65 alfred rd / filled.count.soap / London
biasTowardsnostringwhat3words or lat,lng coordinate for prioritizing results coordinates, what3words
containernostringObject containing parameters for managing the autocomplete container. { V1;65|ALFRED Road|LONDON|W2;51.521198;-0.196309 }
searchFornostringA 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'
countriesnostringISO alpha-2 country codes'ca,uk'
maxDistancenostringA distance in km to limit the search radius from the biasTowards coordinate.Max distance (meters)3000
maxResultsnostringMaximum 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)
populateIndexnostringIndex 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
populateLineCountnostringNumber of lines to populate in the autocomplete field. If used the users don’t have a specific labeled address lines.5
distanceUnitsnostringUnit 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’
groupResultsnobooleanA 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
populateLineFormatnostringFormat for populating lines in the autocomplete field. lineFormat0=AddressLine1, lineFormat1=AddressLine2, lineFormat2=AddressLine3, lineFormat3=TertiaryLocality, SecondaryLocality, PrimaryLocality, STATEABBREVIATION, lineFormat4=POSTCODE, lineFormat5=PrimaryCountry, lineFormat6=what3words.[..]
pageFromnostringIndicates 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.

NameTypeDescriptionExample
primary.textstringA simplified summary of the main part of the address.Nottingham
primary.highlightsint[]Indexes into primary.text to indicate matched characters.[0,9]
secondary.textstringA summary of the secondary description of the address.East Midlands
secondary.highlightsint[]Indexes into secondary.text to indicate matched characters.[]
typestringA hierarchical type description of the address.place.settlement.large or what3words
recordobjectA text description of the result.{"country": { "text": "England" }, "postcode": { "text": "NG1" }}
geometry.centre.latfloatLatitude of the centre point of the address.52.9562
geometry.centre.lonfloatLongitude of the centre point of the address.-1.1512
geometry.centre.typestringType of the centre point of the address.address
distance.unitsstringUnit of measurement for distancemi
distance.measurementfloatDistance of the address from provided coordinates.5.5
distance.typestringType of distnacebiasTowards
distance.geometryobjectCentre of the coordinates{ "centre": { "lat": 51.4508, "lon": -3.224277 } }
isContainerbooleanDoes the address contains more addresses?TRUE
containerstringObject containing parameters for managing the autocomplete container.V1;Sappers Farm Cottage|Cranfield Park Road|WICKFORD|SS12;51.597130;0.531537
countryCodestringAn ISO 3166-1 alpha-2 country code.GB
populateRecordobjectContains lines, licenses, and label.{ "lines": [ "Tile House", "CF64 4HE", "United Kingdom" ] }
populateRecord.linesstringThe fully formatted postal address, line by line.
populateRecord.labelstringThe fully formatted postal address, in a label format.
populateRecord.licensesstringThe licenses of the addresses
6Error Handling

Review the possible API errors and HTTP status codes, and how to resolve them.

CodeDescriptionError message
200Success
4001. Invalid what3words Bias, 2. Malformed biasTowards, 3. Invalid maxResults number1. 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
401Invalid API keyInvalid API key. Please provide a valid API key in the query string or as a header
403Free trial expiredYour free trial has expired. Please sign in to your account and purchase credits to continue using the service.
429Rate limitedToo 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.

Server and ScriptingUse 3 word addresses within an address searchSwiftComplete

Related tutorials