Documentation

Autocomplete Advanced

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. Tricks like debouncing and skipping non alphanumeric characters, found in our Slpy JS Autocomplete library, greatly reduces the amount of requests sent while a user is typing. Check the pricing page for current Search API credit costs.

Storing and Limits

Temporary Geocoding Only

Server side storage and/or caching of responses is currently not permitted due to licensing.
All requests should be in response to end user actions.

Service Limits

Free Plan accounts are limited to a total of 60 requests per minute. Limit hits can be tracked in Per Key analytics, and will show as a 1-min rate limit of "search". Blocked requests will return a 429 response code, and a "reject-reason" header of "Account Maximum Reached".

Coverage

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

The current list of supported country codes are:
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

Address or Admin

We have two autocomplete types that cover most use cases. Address autocomplete looks for a complete address with included building number and all address parts applicable to the country. Admin autocomplete searches for cities, regions, and other administrative boundaries, and can be filtered to whatever specific type is required. Autocomplete is not meant to be "fuzzy" like our Geocoding search, and will not try to force a match that is not exact. This allows for faster responses and is meant to steer the user to the correct result.


Address Autocomplete

Autocomplete on full building addresses.

Request

Make the HTTPS Get or Post request using the url and parameters below.

Get URL

https://api.slpy.com/v1/search?autocomplete=address&query={search string}&country={country}&key={your_api_key}

Post URL

https://api.slpy.com/v1/search?key={your_api_key}
Parameter Description
key
String
Required
The API Key created on your Account page after you login to Slpy.
autocomplete
String
Required
should be set as "address". See Admin section below for searching cities or regions.
query
String
Required
URL encoded search string with an overal format that should match the Country's standard address format
country
String
Required
The two character iso_alpha2 country code.
Use the word "GLOBAL" instead of a specific country code to search all countries.
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.

Usage

Example usage

Get URL

https://api.slpy.com/v1/search?autocomplete=address&query=400 Broad St, Sea&language=en&country=us&key=abc123

Post URL

https://api.slpy.com/v1/search?key=abc123
Post Data Object Value
autocomplete address
query 400+Broad+St+Sea
language en
country us

Response

The response is returned as a JSON formatted object, which contains an array of results. It is ordered by confidence, with information on the location.

{
	"0": {
		"address": "151 3rd St, San Francisco, CA",
		"focus": "<b>151 3rd St</b>, <b>San</b> Francisco, CA",
		"city": "San Francisco",
		"region": "CA",
		"street": "151 3rd St",
		"postcode": "94105",
		"country_code": "US",
		"country": "United States of America",
		"level": 10,
		"lat": 37.785915,
		"lon": -122.400734
	},
	"1": {
		"address": "151 Third St, San Sabado, TX",
		"focus": "<b>151 Third St</b>, <b>San</b> Sabado, TX",
		"city": "San Sabado",
		"region": "TX",
		"street": "151 Third St",
		"postcode": "77474",
		"country_code": "US",
		"country": "United States of America",
		"level": 10,
		"lat": 29.80495,
		"lon": 96.096947
	},
	"license": "© Slpy © OpenStreetMap contributors. Caching/storage not permitted. Attribution-Terms at https://www.slpy.com"
}

Address Response

Parameter Description
address
String
Full result text with proper casing.
focus
String
The full result with <b> tags included to show matched words to the user in bold.
city
String
Result city
street
String
street name including bulding number
region
String
State or Region
postcode
String
Zip or postal code
country_code
String
two digit country code
country
String
Full country name
level
Integer
Level code for place type. Usually 10 for address autocomplete.
  • 10 : Exact match on street address.
  • 9 : Matched street address with lower confidence.
  • 8 : Approximate street number.
  • 7 : Road Level or unvalidated low confidence address.
lat
Number
The latitude of the returned point
lon
Number
The longitude of the returned point
license
String
Required attribution, copyrights, and legal disclaimer. "© Slpy, © OpenStreetMap contributors" should be displayed on the map or somewhere near the results displayed information as required by our partners and data sources.

Admin (Places) Autocomplete

Use "admin" to autocomplete administrative boundaries like cities, regions, states, districts, counties, and countries.

Request

Make the HTTPS Get or Post request using the url and parameters below.

Get URL

https://api.slpy.com/v1/search?autocomplete=admin&query={search string}&filter={city,district,region,postcode,country}&country={country}&key={your_api_key}

Post URL

https://api.slpy.com/v1/search?key={your_api_key}
Parameter Description
key
String
Required
The API Key created on your Account page after you login to Slpy.
autocomplete
String
Required
should be set as "admin". See Address section above for searching street addresses and points of interest.
query
String
Required
URL encoded search string with an overal format that should match the Country's standard address format
country
String
Required
The two character iso_alpha2 country code.
Use the word "GLOBAL" instead of a specific country code to search all countries.
filter
String
optional
An optional 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.

Usage


Get URL

https://api.slpy.com/v1/search?autocomplete=admin&query=Seatt&filter=city&country=us&language=en&key=abc123

Post Data Object

https://api.slpy.com/v1/search?key=abc123
Post Request Header Value
autocomplete admin
query Seatt
filter city
language en
country us

Response

The response is returned as a JSON formatted object, which contains an array of results. It is ordered by confidence, with information on the location.

{
	"0": {
		"admin": "San Francisco County, California",
		"focus": "<b>San Francisco</b> County, California",
		"name": "San Francisco County",
		"abv": "SF",
		"type": "district",
		"parent": "California",
		"parent_short": "CA",
		"country_code": "US",
		"country": "United States of America",
		"level": 3,
		"lat": 37.729176,
		"lon": -123.046638
	},
	"1": {
		"admin": "San Francisco, California",
		"focus": "<b>San Francisco</b>, California",
		"name": "San Francisco",
		"abv": "",
		"type": "city",
		"parent": "California",
		"parent_short": "CA",
		"country_code": "US",
		"country": "United States of America",
		"level": 4,
		"lat": 37.729176,
		"lon": -123.046638
	},
	"license": "© Slpy © OpenStreetMap contributors. Caching/storage not permitted. Attribution-Terms at https://www.slpy.com"
}

Admin Response

Parameter Description
admin
String
Full result with proper casing.
focus
String
The full result with <b> tags included to show matched words to the user in bold.
name
String
The name of the administrative place without parent context
abv
String
The results abreviation if available
type
String
The result type of city, district, region, postcode, or country
parent
String
The parent administrative boundary that the result is surrounded by.
parent_short
String
The abbreviation for the parent administrative boundary that the result is surrounded by.
country_code
String
two digit country code
country
String
Full country name
level
Integer
Level code for place type.
  • 5 : Postcode
  • 4 : City or Town
  • 3 : District or County
  • 2 : Region or State
  • 1 : Country
lat
Number
The latitude of the returned point
lon
Number
The longitude of the returned point
license
String
Required attribution, copyrights, and legal disclaimer. "© Slpy, © OpenStreetMap contributors" should be displayed on the map or somewhere near the results displayed information as required by our partners and data sources.

Examples

Real world examples using the Slpy JS Autocomplete library.

Shipping Checkout

  • Autocomplete for shipping and billing
  • Autofill address parts

Store Locator

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

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

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