Autocomplete & Autofill

If you want to allow users to quickly pull up an address or location without typing all the details, autocomplete can help you do that.

Pricing

Each autocomplete request counts as a Search API request. Check the pricing page for current Search API credit costs.

Street Coverage

Because of the rapidly growing nature of street addresses, autocomplete should always be used as a guide and supplement to your users, and not for limiting input. Autocomplete coverage should not be considered comprehensive of all street addresses.

Supported country codes for street addresses:
us, ae, ar, at, au, be, bm, br, ca, ch, cl, co, cz, de, dk, ee, es, fi, fo, fr, gr, is, it, jm, kr, lt, lu, lv, mx, nl, no, nz, pl, pt, qa, qu, ru, sa, se, si, tw, ua, us, uy, vg, vi, xk, za

Getting Started

Add the Slpy JS library and CSS to your project.

JavaScript HTML
NPM Module

CSS and JS

Copy-paste the stylesheet <link> and javascript <script> lines below into your <head>.

<!-- CSS -->
<link href="https://api.slpy.com/lib/slpy/latest/slpy-style.css" rel="stylesheet">
<!-- JS -->
<script src="https://api.slpy.com/lib/slpy/latest/slpy.js"></script>

Install Slpy JS

Install Slpy or see the Slpy JS Github for more options.

npm install slpy

Add CSS Files

Include or import the Slpy CSS files from your node_modules folder.

import 'slpy/dist/css/slpy-style.css'

Autocomplete

The addAutocomplete function adds an autocomplete feature to a specified input element. This function can receive the element itself or its ID, an options object with multiple configurations, and an optional callback function that handles the selected item.

Usage

Street Address with HTML Element

var inputElement = document.getElementById('input-element-id');
slpy.addAutocomplete( inputElement, {
	apiKey: 'your-api-key',
	country: 'US',
	autocompleteType: 'address',
	}
 );

City and Postcode Admin with Element ID

slpy.addAutocomplete( 'input-element-id', {
	apiKey: 'your-api-key',
	country: 'US',
	autocompleteType: 'admin',
	filter: 'city,postcode',
	width: "100%",
	offsetLeft: -25,
	offsetTop: 5,
	limit: 8
  }, 
  function(returnInput, selectedItem) {
	console.log('Selected item:', selectedItem);
  }
 );

Update Country

<select onchange="changeCountry(this)">
	<option value="US" selected>United States</option>
	<option value="CA">Canada</option>
</select>

<script>
	var autocompleteInput = slpy.addAutocomplete(inputElement, {
		apiKey: 'your-api-key',
		country: 'US'
		}
	);
	//use returned updateAutocomplete function to change options
	function changeCountry(selectedElement) {
		autocompleteInput.updateAutocomplete({country: selectedElement.value});
	}
</script>

Function

slpy.addAutocomplete( inputElementOrId, options, callback );

inputElementOrId String or HTMLElement Required	Either the ID of a form input element or the html input element itself.
options Object Required	Object containing configuration options. See below.
callback Function optional	A callback function that will be executed when an item is selected. Use it to submit a form or perform an action on the page. See below for more info and examples.

Options Object

apiKey String Required	Sign up or Log in, then create a Key from your account page.
country String Required	The two character iso_alpha2 country code.
autocompleteType String optional	"address" Looks for a complete address with included building number and all address parts applicable to the country. "admin" Searches for cities, regions, and other administrative boundaries and can be filtered to whatever specific type is required. "all" (Default) First searches "admin". If results are less than 10, it then searches "address".
filter String optional	For autocompleteType 'admin' or 'all' only. A comma seperated list of desired administrative types. City District Region Postcode Country
language String optional	The preferred two character language code for the returned result. See Supported Languages for a list of codes available. Default is "en" for English.
width String optional	Default is width of input, with min-width of 250px. Use width option to manually set the autocomplete dropdown width. example: "300px", "100%".
offsetLeft Integer optional	The left offset of the autocomplete dropdown, in pixels.
offsetTop Integer optional	The top offset of the autocomplete dropdown, in pixels.
limit Integer optional	The maximum number of results to display in the dropdown. Default/Maximum is 10.
debounceTime Integer optional	Debounce time (in milliseconds) for search requests. Default is 175. A smaller number will improve responsiveness, but increase number of requests while typing.

Callback Function

function (returnInput, selectedItem)

You can pass an optional callback function that will be executed when an item is selected.

returnInput HTMLElement Required	The input element with the selected value. Use when working with multiple autocomplete inputs, like a checkout page with autocomplete on both shipping and billing fields.
selectedItem JSON Object Required	The response object of the selected item. See the Advanced Response Section for more information on its fields and behavior.

Returns

You can assign addAutocomplete to a variable to alter options at a later time.

updateAutocomplete ( options object ) Function optional	addAutocomplete returns a function for updating of autocomplete options like country or autocompleteType AFTER they have been initialized. You only need to pass updated options.

Example

var autocompleteInput = slpy.addAutocomplete( inputElementOrId, options, callback );

//trigger update
autocompleteInput.updateAutocomplete({country: "ca"});

Response

Slpy JS is designed to automatically format the response, and populate your Input Element with the results. Check out the Advanced Autocomplete page for detailed information on the request and response.

Code Sample

A basic form input example that adds a postcode or city autocomplete.

<link href="https://api.slpy.com/lib/slpy/latest/slpy-style.css" rel="stylesheet">
<script src="https://api.slpy.com/lib/slpy/latest/slpy.js"></script>

<form id="search-form" method="post" action="">
	<div class="search">
		<input type="text" id="search-text" name="s" placeholder="Postcode or City, State" id="search-text"
			value="" />
		<input type="submit" id="search-submit" value="" />
	</div>
</form>

<script>
	var searchInput = document.getElementById('search-text');
	var searchForm = document.getElementById('search-form');

	slpy.addAutocomplete('search-text', {
		apiKey: 'your_api_key',
		country: 'US',
		autocompleteType: 'admin',
		filter: 'city,postcode',
		limit: 8
	}, function (returnInput, selectedItem) {
			searchInput.value = selectedItem.admin;
			searchForm.submit();
		}
	);
</script>

import React, { useEffect, useRef } from 'react';
import { slpy } from 'slpy';
import 'slpy/dist/css/slpy-style.css';

function SearchForm() {
  const searchInputRef = useRef(null);
  const searchFormRef = useRef(null);

  useEffect(() => {
	slpy.addAutocomplete('search-text', {
	  apiKey: 'your_api_key',
	  country: 'US',
	  autocompleteType: 'admin',
	  filter: 'city,postcode',
	  limit: 8
	}, (returnInput, selectedItem) => {
	  searchInputRef.current.value = selectedItem.admin;
	  searchFormRef.current.submit();
	});
  }, []);

  return (
	<form ref={searchFormRef} id="search-form" method="post" action="">
	  <div className="search">
		<input type="text" ref={searchInputRef} name="s" placeholder="Postcode or City, State" id="search-text" />
		<input type="submit" id="search-submit" value="" />
	  </div>
	</form>
  );
}

export default SearchForm;

import { Component, ElementRef, OnInit, ViewChild } from '@angular/core';
import { slpy } from 'slpy';

@Component({
  selector: 'app-search-form',
  template: `
	<form #searchForm id="search-form" method="post" action="">
	  <div class="search">
		<input type="text" #searchInput name="s" placeholder="Postcode or City, State" id="search-text" />
		<input type="submit" id="search-submit" value="" />
	  </div>
	</form>
  `,
  styleUrls: ['https://api.slpy.com/lib/slpy/latest/slpy-style.css']
})
export class SearchFormComponent implements OnInit {
  @ViewChild('searchInput') searchInput: ElementRef;
  @ViewChild('searchForm') searchForm: ElementRef;

  ngOnInit() {
	slpy.addAutocomplete('search-text', {
	  apiKey: 'your_api_key',
	  country: 'US',
	  autocompleteType: 'admin',
	  filter: 'city,postcode',
	  limit: 8
	}, (returnInput, selectedItem) => {
	  this.searchInput.nativeElement.value = selectedItem.admin;
	  this.searchForm.nativeElement.submit();
	});
  }
}

<template>
  <form ref="searchForm" id="search-form" method="post" action="">
	<div class="search">
	  <input type="text" ref="searchInput" name="s" placeholder="Postcode or City, State" id="search-text" />
	  <input type="submit" id="search-submit" value="" />
	</div>
  </form>
</template>

<script>
import { onMounted, ref } from 'vue';
import { slpy } from 'slpy';
import 'slpy/dist/css/slpy-style.css';

export default {
  setup() {
	const searchInput = ref(null);
	const searchForm = ref(null);

	onMounted(() => {
	  slpy.addAutocomplete('search-text', {
		apiKey: 'your_api_key',
		country: 'US',
		autocompleteType: 'admin',
		filter: 'city,postcode',
		limit: 8
	  }, (returnInput, selectedItem) => {
		searchInput.value.value = selectedItem.admin;
		searchForm.value.submit();
	  });
	});

	return {
	  searchInput,
	  searchForm
	};
  }
};
</script>

<script>
  import { onMount } from 'svelte';
  import { slpy } from 'slpy';
  import 'slpy/dist/css/slpy-style.css';

  let searchInput;
  let searchForm;

  onMount(() => {
	slpy.addAutocomplete('search-text', {
	  apiKey: 'your_api_key',
	  country: 'US',
	  autocompleteType: 'admin',
	  filter: 'city,postcode',
	  limit: 8
	}, (returnInput, selectedItem) => {
	  searchInput.value = selectedItem.admin;
	  searchForm.submit();
	});
  });
</script>

<form bind:this={searchForm} id="search-form" method="post" action="">
  <div class="search">
	<input type="text" bind:this={searchInput} name="s" placeholder="Postcode or City, State" id="search-text" />
	<input type="submit" id="search-submit" value="" />
  </div>
</form>

Example

Real world examples and common use cases.

Store Locator

Autocomplete for city and postcode
Use a callback to show stores on a map.

Address Autofill

The addressAutocomplete function adds autocomplete to all street input or textarea elements in a Form, and will autofill address parts automatically.

Autocomplete Attribute

This function uses the autocomplete attribute for autofill to identify address fields. It supports multiple sections and attaches to each "street-address" or "address-line1" input. It will autofill "address-level1" with Region, "address-level2" with City, as well as "country", "country-name", and "postal-code". Check the usage section below for an example.

HTML Spec - Autofilling form: Autocomplete attribute

Usage


<form id="form-element-id">
	<!-- Residential Shipping -->
	<input name="ra" autocomplete="section-residential shipping address-line1">
	<input name="rc" autocomplete="section-residential shipping address-level2">
	<input name="rr" autocomplete="section-residential shipping address-level1">
	<input name="rp" autocomplete="section-residential shipping postal-code">

	<!-- Company Shipping -->
	<textarea name="ca" autocomplete="section-company shipping street-address">
	<input name="cc" autocomplete="section-company shipping address-level2">
	<input name="cr" autocomplete="section-company shipping address-level1">
	<input name="cp" autocomplete="section-company shipping postal-code">

	<!-- Billing -->
	<input name="ba" autocomplete="billing address-line1">
	<input name="bc" autocomplete="billing address-level2">
	<input name="br" autocomplete="billing address-level1">
	<input name="bp" autocomplete="billing postal-code">
</form>

slpy.addressAutocomplete( 'form-element-id', {
  apiKey: 'your-api-key',
  country: 'US',
} );

Function

slpy.addressAutocomplete( formElementOrId, options );

formElementOrId String or HTMLElement Required	Either the ID of a form element or the html form element itself.
options Object Required	Object containing configuration options. See below.

Options Object

apiKey String Required	Sign up or Log in, then create a Key from your account page.
country String Required	The two character iso_alpha2 country code.
language String optional	The preferred two character language code for the returned result. See Supported Languages for a list of codes available. Default is "en" for English.
width String optional	Default is width of input, with min-width of 250px. Use width option to manually set the autocomplete dropdown width. example: "300px", "100%".
offsetLeft Integer optional	The left offset of the autocomplete dropdown, in pixels.
offsetTop Integer optional	The top offset of the autocomplete dropdown, in pixels.
limit Integer optional	The maximum number of results to display in the dropdown. Default/Maximum is 10.
debounceTime Integer optional	Debounce time (in milliseconds) for search requests. Default is 175. A smaller number will improve responsiveness, but increase number of requests while typing.

Returns

Array of updateAutocomplete()

addressAutocomplete returns an array of updateAutocomplete functions for updating of autocomplete options like the country after they have been initialized. You only need to pass updated options.

Example

var formAutocompletes = slpy.addressAutocomplete( formElementOrId, options );

//trigger update
formAutocompletes.forEach(function(autocompleteInput ) {
		autocompleteInput.updateAutocomplete({
			country: selectedOption.value
		});
});

Code Sample

A basic shipping address example that adds an address autofill to the street field.

<link href="https://api.slpy.com/lib/slpy/latest/slpy-style.css" rel="stylesheet">
<script src="https://api.slpy.com/lib/slpy/latest/slpy.js"></script>

<form id="form-element-id"" method="post" action="">
	<input name="ra" autocomplete="shipping address-line1" placeholder="street">
	<input name="rc" autocomplete="shipping address-level2" placeholder="city">
	<input name="rr" autocomplete="shipping address-level1" placeholder="region">
	<input name="rp" autocomplete="shipping postal-code" placeholder="postcode">
</form>

<script>
		slpy.addressAutocomplete('form-element-id', {
			apiKey: 'your_api_key',
			country: 'US'
		});
</script>

import React, { useEffect, useRef } from 'react';
import { slpy } from 'slpy';
import 'slpy/dist/css/slpy-style.css';

function AddressForm() {
	const formRef = useRef(null);

	useEffect(() => {
		slpy.addressAutocomplete('form-element-id', {
			apiKey: 'your_api_key',
			country: 'US'
		});
	}, []);

	return (
		<form ref={formRef} id="form-element-id" method="post" action="">
			<input name="ra" autocomplete="shipping address-line1" placeholder="street" />
			<input name="rc" autocomplete="shipping address-level2" placeholder="city" />
			<input name="rr" autocomplete="shipping address-level1" placeholder="region" />
			<input name="rp" autocomplete="shipping postal-code" placeholder="postcode" />
		</form>
	);
}

export default AddressForm;

import { Component, OnInit, ViewChild, ElementRef } from '@angular/core';
import { slpy } from 'slpy';

@Component({
	selector: 'app-address-form',
	template: `
		<form #formElement id="form-element-id" method="post" action="">
			<input name="ra" autocomplete="shipping address-line1" placeholder="street" />
			<input name="rc" autocomplete="shipping address-level2" placeholder="city" />
			<input name="rr" autocomplete="shipping address-level1" placeholder="region" />
			<input name="rp" autocomplete="shipping postal-code" placeholder="postcode" />
		</form>
	`,
	styleUrls: ['https://api.slpy.com/lib/slpy/latest/slpy-style.css']
})
export class AddressFormComponent implements OnInit {
	@ViewChild('formElement') formElement: ElementRef;

	ngOnInit() {
		slpy.addressAutocomplete('form-element-id', {
			apiKey: 'your_api_key',
			country: 'US'
		});
	}
}

<template>
	<form ref="formElement" id="form-element-id" method="post" action="">
		<input name="ra" autocomplete="shipping address-line1" placeholder="street" />
		<input name="rc" autocomplete="shipping address-level2" placeholder="city" />
		<input name="rr" autocomplete="shipping address-level1" placeholder="region" />
		<input name="rp" autocomplete="shipping postal-code" placeholder="postcode" />
	</form>
</template>

<script>
import { onMounted, ref } from 'vue';
import { slpy } from 'slpy';
import 'slpy/dist/css/slpy-style.css';

export default {
	setup() {
		const formElement = ref(null);

		onMounted(() => {
			slpy.addressAutocomplete('form-element-id', {
				apiKey: 'your_api_key',
				country: 'US'
			});
		});

		return {
			formElement
		};
	}
};
</script>

<script>
import { onMount } from 'svelte';
import { slpy } from 'slpy';
import 'slpy/dist/css/slpy-style.css';

let formElement;

onMount(() => {
	slpy.addressAutocomplete('form-element-id', {
		apiKey: 'your_api_key',
		country: 'US'
	});
});
</script>

<form bind:this={formElement} id="form-element-id" method="post" action="">
	<input name="ra" autocomplete="shipping address-line1" placeholder="street" />
	<input name="rc" autocomplete="shipping address-level2" placeholder="city" />
	<input name="rr" autocomplete="shipping address-level1" placeholder="region" />
	<input name="rp" autocomplete="shipping postal-code" placeholder="postcode" />
</form>

Example

Real world examples and common use cases.

Shipping Checkout

Autocomplete for shipping and billing
Autofill address parts

Troubleshooting

No Response

Your Api Key may not be configured correctly. Open Developer Tools, and look in the Network tab for "search?" files not loading with status 200. Click the file and check "Response Headers" for "Reject-Reason:".
Example: "Reject-Reason:Bad Referrer: cdpn.io" not matching "codepen.io" in key's whitelist.

Error Codes

In Depth

Read the Advanced Autocomplete page for detailed information on the request and response used in the Search API. You can use the callback in addAutocomplete to create custom features like the addressAutocomplete function.

Next Steps

Enhance your search with Maps or Autocomplete

Search & Geocoding

Add a search bar to your map.
Translate addresses to coordinates
Search for points of interest.

Maps

Display your location
Provide context to an address
Add popups for more information

Documentation

Autocomplete & Autofill

Pricing

Street Coverage

Getting Started

CSS and JS

Install Slpy JS

Add CSS Files

Autocomplete

Usage

Street Address with HTML Element

City and Postcode Admin with Element ID

Update Country

Function

Options Object

Callback Function

Returns

Example

Response

Code Sample

Example

Store Locator

Address Autofill

Autocomplete Attribute

Usage

Function

Options Object

Returns

Array of updateAutocomplete()

Example

Code Sample

Example

Shipping Checkout

Troubleshooting

No Response

In Depth

Next Steps

Search & Geocoding

Maps