All tutorials
Swiftcomplete JavaScript Integration: Add Address Autocomplete to Web Forms
The Swiftcomplete API provides real-time address suggestions as you type, eliminating typos and mistakes and reducing the time it takes to find accurate postal addresses.
If you need help integrating our Swiftcomplete API into your website or application, contact us, and one of our product experts will help you get started.
Each request must be authenticated with a Swiftcomplete API key, which you can create in your Swiftcomplete account:
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
- Visit Swiftcomplete RESTful API
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)
- Jump to JavaScript Integration →
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)
The JavaScript Swiftcomplete integration is a code snippet that can be included on your website or in your checkout to provide address search with real-time suggestions as you type.
Firstly, copy & paste the code snippet into the <head> section of your HTML, before the closing </head> tag.
Note: Make sure you only copy the code snippet once, even if you have multiple address fields on your page.
<script>!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://assets.swiftcomplete.com/js/swiftlookup.js"); </script>
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 Swiftcomplete API key, and replace INSERT_TEXT_FIELD_ID_HERE with the ID of an existing textbox on your page.
The script initialises Swiftcomplete 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.
<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.SwiftLookup({ 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:Swiftcomplete: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>
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.
Swiftcomplete has released an updated, branded integration library — Swiftcomplete — which replaces the legacy “Places” API and associated scripts. This new version offers improved reliability, updated styling, and streamlined hosting via a modern CDN.
All new integrations should now use the Swiftcomplete library. Existing integrations will remain functional but are no longer recommended for new development.
✅ Use These Updated Resources
Embed the following Swiftcomplete resources in your integration:
<!-- JavaScript --> <script src="https://assets.swiftcomplete.com/js/swiftlookup.js"></script> <!-- CSS --> <link rel="stylesheet" href="https://assets.swiftcomplete.com/css/swiftlookup.css" />
These files are hosted on a CDN for improved performance and reliability and are aligned with the latest Swiftcomplete branding and data models.
🚫 Do Not Use (Deprecated)
Please update any documentation or integration that references the following legacy files:
<script src="https://script.swiftcomplete.com/js/swiftcomplete.js"></script>
These older assets are deprecated and no longer maintained.
| Area | Legacy | New (Swiftcomplete) |
|---|---|---|
| JavaScript script | swiftcomplete.js | swiftlookup.js |
| CSS | swiftcomplete.css | swiftlookup.css |
| API endpoint | /v1/places | /v1/swiftlookup/ |
| Constructor | swiftcomplete | swiftcomplete |
| Class Name | PlaceAutocomplete | SwiftLookup |
| Events | swiftcomplete:place:manualentry | swiftcomplete:swiftlookup:manualentry |
| Events | swiftcomplete:place:selected | swiftcomplete:swiftlookup:selected |
| Events | swiftcomplete:userLocation | swiftcomplete:swiftlookup:userLocation |
📦 Notes for Developers
- Existing integrations will continue to function, but all new integrations should adopt Swiftcomplete.
- The Swiftcomplete library is more consistent with the latest postal datasets, brand styling, and performance standards.
- Updated documentation and demos reflect this migration, ensuring an easier onboarding for developers.
These are the configuration options passed into the Swiftcomplete component when initialising the autocomplete. Each parameter customises how the component behaves, from API keys and input fields to how results are displayed and filtered. Use these to tailor the experience to your platform.
| Parameter Name | Value (Example) | Type | Description |
|---|---|---|---|
| key | xxxxx | String | API key for Swiftcomplete. |
| field | input-id | String | The HTML input element ID. |
| searchFor | 'what3words, address, place, road,transit' | String | Comma-separated types: address, what3words, place, transit, etc.Hierarchical. includes nested types like transit.airport.large (See the table below for more info) |
| emptyQueryMode | 'prompt' / 'results' | String | Web: 'prompt' or 'results'vv |
| scrollToFieldOnFocus | true | Boolean | Indicates if the field should be scrolled into view on focus. |
| populateLineCount | 5 | Number | Number of address lines to populate. Max 8. |
| populateLineFormat | [...] | Array | Format for populating lines in the autocomplete field. lineFormat0=Company lineFormat1=SubBuilding,BuildingName lineFormat2=BuildingNumber SecondaryRoad, Road, PoBox lineFormat3=TertiaryLocality, SecondaryLocality lineFormat4=PrimaryLocality lineFormat5=POSTCODE lineFormat6=PrimaryCountry lineFormat7= what3words |
| hideOnEmptyResults | false | Boolean | Hides the dropdown when results are empty. |
| requestDeviceLocation | true | Boolean | Requests browser geolocation. |
| showControlAfterPermissions | true | Boolean | Shows control after permission is granted. |
| text | 'w25eu' / 'London' / 'filled.count.soap' | String | A full or partial search term such as a postcode, street, city or what3words. |
| promptText | 'Type your address...' | String | Displayed when search field is empty. |
| noResultsText | 'No results found, please try again!' | String | Displayed when search returns no results. |
| manualEntryText | 'Can't find your address? Click here to enter' | String | Displayed when user opts to manually enter address. |
| Level | Type | Description |
|---|---|---|
| First Level | ||
| what3words | All what3words addresses | |
| address | All traditional addresses | |
| place | Postcodes and all types of settlements (cities, towns, villages, counties, provinces, etc.) | |
| road | All types of roads | |
| transit | All types of public transport | |
| Second Level | ||
| place.area | Postcodes and counties, states, etc. | |
| place.settlement | Cities, towns, villages, etc. | |
| transit.airport | Airports | |
| transit.metro | Metro and London Underground stops | |
| transit.railway | Railway stations | |
| transit.tram | Tram stops | |
| Third Level | ||
| place.area.county | Counties | |
| place.area.postcode | Postcodes, Zip codes, etc | |
| place.area.country | Countries | |
| place.area.state | States | |
| place.area.province | Provinces | |
| place.area.territory | Territories | |
| place.settlement.large | Large Cities | |
| place.settlement.medium | Cities & towns | |
| place.settlement.small | Districts, villages & hamlets | |
| transit.airport.large | Large international airports | |
| transit.airport.medium | Medium regional airports | |
| transit.metro.station.gblondondlr | London DLR stations | |
| transit.metro.station.gblondonunderground | London Underground stations | |
| transit.tram.stop.gbcroydontramlink | London tram stops (Croydon Tramlink) | |
| transit.tram.stop.gbedinburghtrams | Edinburgh Tram stops | |
| transit.tram.stop.gbmanchestermetrolink | Manchester Metrolink tram stops | |
| transit.tram.stop.gbnottinghamnet | Nottingham NET tram stops | |
| transit.tram.stop.gbsheffieldsupertram | Sheffield Supertram tram stops | |
| transit.tram.stop.gbwestmidlandsmetro | West Midlands Metro tram stops |
These functions let you dynamically control the behaviour of the Swiftcomplete component after it has been initialised. You can change settings like maximum results, restrict searches to certain countries, or bias searches toward a specific location. Useful for custom logic and app flows.
| Function Name | Example Usage | Description |
|---|---|---|
| setMaxAutocompleteResults(amount) | setMaxAutocompleteResults(5) | Sets max results for general text searches (1–5). |
| setMaxContainerResults(amount) | setMaxContainerResults(100) | Sets max results when inside a container (1–100). |
| setSearchFor(types) | setSearchFor('address,what3words') | Restricts result types. |
| setCountries(code) | setCountries('gb') | Restrict search to countries (ISO 3166-1 alpha-2). |
| setMaxDistance(meters) | setMaxDistance(3000) | Restrict search radius in meters. |
| biasTowards(location) | biasTowards('///filled.count.soap') | Prioritise search near location or lat/lon. |
| setTextSearchOptions({...}) | setTextSearchOptions({...}) | Override search options like maxResults, countries, etc. |
| getDeviceLocation(true) | getDeviceLocation(true) | Requests geolocation, biases results. |
| getAddressAutocompleteCoverage() | getAddressAutocompleteCoverage()['gb'] | Lists available countries for address autocomplete. |
| hasAddressAutocompleteCoverageForCountry('gb') | true | Checks if a country supports autocomplete. |
| setReactFieldValue(el, value) | setReactFieldValue(input, "new value") | Updates React input state properly. |
The component emits these events during the user’s interaction with the autocomplete. You can use them to trigger business logic, populate form fields, or track analytics. Mobile-specific equivalents are also supported where applicable.
| Event Name | Trigger Source | Description |
|---|---|---|
| swiftcomplete:swiftlookup:selected | User selects a result | Returns selected result with address lines, geometry, type, what3words address, etc. |
| swiftcomplete:swiftlookup:suggestion | Suggestions fetched | Returns the list of current suggestions being displayed. |
| swiftcomplete:swiftlookup:userLocation | Device location used | Returns lat/lon of user location if geolocation is allowed. |
| swiftcomplete:swiftlookup:manualentry | Manual entry clicked | Triggered when user opts to manually enter address. |
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.