v1
latestOpenAPI 3.0.02026-07-241437122.4 KBAutocomplete
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.
<a href="https://locationiq.com/demo#autocomplete" target="_blank">Try this API in our Playground</a>
If you use Leaflet for your maps, you add LocationIQ's Autocomplete as a plugin instantly! You can <a href="https://github.com/location-iq/leaflet-geocoder" target="_blank">view instructions here</a>. You can also view a <a href="https://maps.locationiq.com" target="_blank">live demo here</a>.
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 parameters
Free-form query string to search for. Commas are optional, but improves performance by reducing the complexity of the search.
Limit search results to a specific country or a comma-separated list of countries. Should be the ISO 3166-1 alpha-2 code(s).
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) <a href="https://wiki.openstreetmap.org/wiki/Map_Features" target="_blank">exhaustive list</a>.
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
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 the number of returned results. Accepted value: 1 to 20. Defaults to 10.
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.
Restrict result to items contained within the bounds specified in the viewbox parameter. Defaults to 0.
Wrap json output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats.
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.
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.
Adds state or province code when available to the state_code key inside the address object when available. Defaults to 0.
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.
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.
Response
OK
Example response
[
{
"address": {
"house_number": "3894",
"road": "Spring Mill Way",
"residential": "Hunter’s Point",
"village": "Landen",
"city": "Landen",
"county": "Warren County",
"state": "Ohio",
"postcode": "45039",
"country": "United States of America",
"country_code": "us",
"state_code": "oh"
}
}
]