Autocomplete API

The Autocomplete API is designed to enhance search experiences in frontend applications, offering instant place suggestions in search bars and form fields as users type, recognizing both partial and full words for a streamlined and efficient user interaction.

Try the Autocomplete demo


Use Autocomplete in a Map

If you use LocationIQ Maps with either Leaflet or Maplibre libraries, you can add LocationIQ's Autocomplete as a plugin instantly!

Leaflet JS

This plugin offers additional customization which can be viewed here.

Maplibre JS


Use Autocomplete in a Form without a Map

jQuery

Other ways to use Autocomplete without a map or outside a map:


Brief Overview of Request / Response Parameters

The information presented below is a condensed summary. For a more detailed and exhaustive list of parameters, refer to API Reference Page.

Request

Request Format

Requests can be sent to the following endpoint:

 https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=SEARCH_STRING

πŸ‘

Requests

The Autocomplete API endpoint 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.

Request Example

curl --request GET \
  --url 'https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=Empire'
<?php
$curl = curl_init('https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=Empire');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}

import requests

url = "https://api.locationiq.com/v1/autocomplete"

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'q': 'Empire'
}

response = requests.get(url, params=data)

print(response.text)
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=Empire",
  "method": "GET"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

🚧

Autocomplete Usage

The Autocomplete API endpoint is intended for use where predictive, typeahead functionality is necessary. It is not designed to be compatible with Search/ Forward Geocoding endpoint.

Required Parameters

NameDescriptionRequiredValues
keyYour API KeyYes
qQuery string to search for
Maximum length: 200
Yes

Frequently used parameters (optional):

NameDescriptionValues
limitLimit the number of returned results. Default is 10.[1 to 20]
countrycodesLimit search to a list of countries. [Read more.]
normalizecityFor 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.[0 |1]
accept-languagePreferred language for showing search results. Defaults to en. Unlike Search and Reverse endpoints, the Autocomplete endpoint supports only a single 2 digit language code. 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 and Swedish sv. If you'd like us to add support for a specific language, please reach out. [Read more.][en]

πŸ“˜

List of all input parameters available on the API Reference page


Response

Response Example

[
    {
        "place_id": "0",
        "osm_id": "34633854",
        "osm_type": "way",
        "licence": "https://locationiq.com/attribution",
        "lat": "40.7484284",
        "lon": "-73.985654619873",
        "boundingbox": [
            "40.7479226",
            "40.7489422",
            "-73.9864855",
            "-73.9848259"
        ],
        "class": "tourism",
        "type": "attraction",
        "display_name": "Empire State Building, 350, 5th Avenue, New York City, New York, 10018, United States of America",
        "display_place": "Empire State Building",
        "display_address": "350, 5th Avenue, New York City, New York, 10018, United States of America",
        "address": {
            "name": "Empire State Building",
            "house_number": "350",
            "road": "5th Avenue",
            "city": "New York City",
            "state": "New York",
            "postcode": "10018",
            "country": "United States of America"
        }
    },
    {
        "place_id": "0",
        "osm_id": "34633854",
        "osm_type": "way",
        "licence": "https://locationiq.com/attribution",
        "lat": "40.7484284",
        "lon": "-73.985654619873",
        "boundingbox": [
            "40.7479226",
            "40.7489422",
            "-73.9864855",
            "-73.9848259"
        ],
        "class": "office",
        "type": "yes",
        "display_name": "Empire State Building, 350, 5th Avenue, New York City, New York, 10018, United States of America",
        "display_place": "Empire State Building",
        "display_address": "350, 5th Avenue, New York City, New York, 10018, United States of America",
        "address": {
            "name": "Empire State Building",
            "house_number": "350",
            "road": "5th Avenue",
            "city": "New York City",
            "state": "New York",
            "postcode": "10018",
            "country": "United States of America"
        }
    }
]

Response Parameters

NameDescription
latThe Latitude of this element
lonThe Longitude of this element
display_placeOnly the name part of the address; if the type is a city, just the city's name. If the type is highway, just the road's name. This is helpful when a client library wants to display this information separately.
display_addressThe complete address without the text already present in display_place
display_nameThe display name of this element, with complete address

πŸ“˜

List of all response parameters available on the API Reference page