Autocomplete

get

https://us1.locationiq.com/v1/autocomplete

The Autocomplete API is a variant of the Search API that returns place predictions in response to an HTTP request. The request specifies a textual search string and optional geographic bounds. The service can be used to provide autocomplete functionality for text-based geographic searches, by returning places such as businesses, addresses and points of interest as a user types.

The Autocomplete API can match on full words as well as substrings. Applications can therefore send queries as the user types, to provide on-the-fly place predictions.

Try this API in our Playground

If you use Leaflet for your maps, you add LocationIQ's Autocomplete as a plugin instantly! You can view instructions here. You can also view a live demo here.

The Autocomplete API endpoint (https://api.locationiq.com/v1) offers an Anycast IP address and route user requests to a datacenter closest to them. You can still manually specify a region similar to other LocationIQ endpoints, but in the interest of end-user experience, we don't recommended such a configuration.

Query Params

string

required

Free-form query string to search for. Commas are optional, but improves performance by reducing the complexity of the search.

countrycodes

string

Limit search results to a specific country or a comma-separated list of countries. Should be the ISO 3166-1 alpha-2 code(s).

tag

string

Restricts results to specific types of elements. This can be used to return only administrative areas - such as towns or cities - or specific Points of Interest such as schools or restaurants.

This is defined as key value pairs of class and type values based on OpenStreetMap''s (OSM) exhaustive list.

Multiple class and type values can be specified as a comma-separated list.

Examples:

To return only cities: tag=place:city
To return only types of place, such as Suburbs, Towns and Cities, use a wildcard: tag=place:*
To restrict results to specific types of place: tag=place:city,place:town,place:village
To restrict results to cafes: tag=amenity:cafe
To restrict results to all types except those with amenity as class: tag=!amenity:*
To restrict results to only the amenity class except gym: tag=amenity:*,!amenity:gym
To restrict results to all types except elements with amenity as class and gym as type: tag=!amenity:gym

layers

string

Restricts results to specific layers on the Autocomplete API.

Multiple layer values can be specified as a comma-separated list. Values are case-insensitive and extra spaces are ignored. Unsupported values are ignored.

Supported values: road, neighbourhood, suburb, city, county, state, country, postcode

Note: layers=postcode applies a postal-code-only filter only when it is the sole layer and tag is not set. If tag is set, tag filtering is preserved and postcode in layers is ignored.

Examples:

To return only states: layers=state
To return only countries: layers=country
To return states and countries: layers=state,country
To return postal code records: layers=postcode

limit

integer

1 to 20

Limit the number of returned results. Accepted value: 1 to 20. Defaults to 10.

viewbox

string

The preferred area to find search results. Any two corner points of the box - max_lon,max_lat,min_lon,min_lat or min_lon,min_lat,max_lon,max_lat - are accepted in any order as long as they span a real box. To restrict results to those within the viewbox, use along with the bounded option.

bounded

integer

enum

Restrict result to items contained within the bounds specified in the viewbox parameter. Defaults to 0.

Allowed:

json_callback

string

Wrap json output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats.

normalizecity

integer

enum

Defaults to 0

For responses with no city value in the address section, the next available element in this order - city_district, locality, town, borough, municipality, village, hamlet, quarter, neighbourhood - from the address section will be normalized to city. Defaults to 0.

Allowed:

accept-language

string

Defaults to en

Preferred language order for showing search results, overrides the value specified in the Accept-Language HTTP header. Defaults to en.

Accepts a simple comma separated list of the supported language codes.
To use native language for the response when available, use accept-language=native.

The Autocomplete endpoint currently supports the following languages: English en, Czech cs, Dutch nl, French fr, German de, Indonesian id, Italian it, Norwegian no, Polish pl, Spanish es, Russian ru, Swedish sv and Ukrainian uk.

If you'd like us to add support for a specific language, please reach out.

statecode

integer

enum

Defaults to 0

Adds state or province code when available to the state_code key inside the address object when available. Defaults to 0.

Allowed:

importancesort

integer

enum

Defaults to 1

Determines whether results are sorted by their individual importance values. If importancesort=0 and is used along with the viewbox parameter, results are sorted only by distance. Defaults to 1.

Allowed:

dedupe

integer

enum

Defaults to 0

When enabled, the geocoder attempts to filter out duplicate results for the same real-world place. Because limit is applied before deduplication, fewer results than requested may be returned.

Allowed:

Responses

200OK

400Bad Request

401Unauthorized

403The request has been made from an unauthorized domain.

404No location or places were found for the given input.

429Request exceeded the rate-limits set on your account.

500Internal Server Error