New pricing changes went into effect on July 16, 2018. For more information, check out the Guide for Existing Users.

Query Autocomplete

The Query Autocomplete service can be used to provide a query prediction for text-based geographic searches, by returning suggested queries as you type.

Query Autocomplete Requests

The Query Autocomplete service is part of the Places API and and shares an API key and quota with the Places API.

The Query Autocomplete service allows you to add on-the-fly geographic query predictions to your application. Instead of searching for a specific location, a user can type in a categorical search, such as "pizza near New York" and the service responds with a list of suggested queries matching the string. As the Query Autocomplete service can match on both full words and substrings, applications can send queries as the user types to provide on-the-fly predictions.

A Query Autocomplete request is an HTTP URL of the following form:

https://maps.googleapis.com/maps/api/place/queryautocomplete/output?parameters

where output may be either json or xml.

Certain parameters are required to initiate a Query Autocomplete request. As is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

Required parameters

  • input — The text string on which to search. The Places service will return candidate matches based on this string and order results based on their perceived relevance.
  • key — Your application's API key. This key identifies your application for purposes of quota management. See Get a key for more information. Google Maps APIs Premium Plan customers must use the API project created for them as part of their Premium Plan purchase.

Optional parameters

  • offset — The character position in the input term at which the service uses text for predictions. For example, if the input is 'Googl' and the completion point is 3, the service will match on 'Goo'. The offset should generally be set to the position of the text caret. If no offset is supplied, the service will use the entire term.
  • location — The point around which you wish to retrieve place information. Must be specified as latitude,longitude.
  • radius — The distance (in meters) within which to return place results. Note that setting a radius biases results to the indicated area, but may not fully restrict results to the specified area. See Location Biasing for more information.
  • language — The language code, indicating in which language the results should be returned, if possible. Searches are also biased to the selected language; results in the selected language may be given a higher ranking. See the supported list of domain languages. If language is not supplied, the Places service will attempt to use the native language of the domain from which the request is sent.

Location Biasing

You may bias results to a specified circle by passing a location and a radius parameter. Doing so instructs the Places service to prefer showing results within that circle; results outside of the defined area may still be displayed.

Example Query Autocomplete Requests

A request "Pizza near Par":

https://maps.googleapis.com/maps/api/place/queryautocomplete/json?key=YOUR_API_KEY&input=pizza+near%20par

A request "Pizza near Par", with results in French:

  https://maps.googleapis.com/maps/api/place/queryautocomplete/json?key=YOUR_API_KEY&language=fr&input=pizza+near%20par

Note that you'll need to replace the API key in these examples with your own key.

Query Autocomplete Responses

Query Autocomplete Responses are returned in the format indicated by the output flag within the URL request's path. The results below are returned for a query with the following parameters:

https://maps.googleapis.com/maps/api/place/queryautocomplete/xml?&key=YOUR_API_KEY&input=pizza+near+sydne

JSON
{
   "predictions" : [
      {
         "description" : "pizza near Sydney, New South Wales, Australia",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 11
            }
         ],
         "terms" : [
            {
               "offset" : 0,
               "value" : "pizza"
            },
            {
               "offset" : 6,
               "value" : "near"
            },
            {
               "offset" : 11,
               "value" : "Sydney"
            },
            {
               "offset" : 19,
               "value" : "New South Wales"
            },
            {
               "offset" : 36,
               "value" : "Australia"
            }
         ]
      },
      {
         "description" : "pizza near Sydney, NS, Canada",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 11
            }
         ],
         "terms" : [
            {
               "offset" : 0,
               "value" : "pizza"
            },
            {
               "offset" : 6,
               "value" : "near"
            },
            {
               "offset" : 11,
               "value" : "Sydney"
            },
            {
               "offset" : 19,
               "value" : "NS"
            },
            {
               "offset" : 23,
               "value" : "Canada"
            }
         ]
      },
        ...additional results ...
      {
         "description" : "Bondi Pizza, Campbell Parade, Sydney, New South Wales, Australia",
         "id" : "c478ed4e7cb075b307fdce4ad4f6c9d15cab01d7",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 6
            },
            {
               "length" : 5,
               "offset" : 30
            }
         ],
         "place_id" : "ChIJv0wpwp6tEmsR0Glcf5tugrk",
         "reference" : "ClRPAAAAYozD2iM3dQvDMrvrLDIALGoHO7v6pWhxn5vIm18pOyLLqToyikFov34qJoe4NnpoaLtGIWd5LWm5hOpWU1BT-SEI2jGZ8WXuDvYiFtQtjGMSEIR4thVlMws1tnNuE3hE2k0aFCqP_yHWRNSLqaP_vQFzazO-D7Hl",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Bondi Pizza"
            },
            {
               "offset" : 13,
               "value" : "Campbell Parade"
            },
            {
               "offset" : 30,
               "value" : "Sydney"
            },
            {
               "offset" : 38,
               "value" : "New South Wales"
            },
            {
               "offset" : 55,
               "value" : "Australia"
            }
         ],
         "types" : [ "establishment" ]
      }
   ],
     "status" : "OK"
  }

A JSON response contains two root elements:

See Processing JSON with JavaScript for help parsing JSON responses.

XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>pizza near Sydney, New South Wales, Australia</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>11</offset>
  </term>
  <term>
   <value>New South Wales</value>
   <offset>19</offset>
  </term>
  <term>
   <value>Australia</value>
   <offset>36</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>6</offset>
   <length>4</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>pizza near Sydney, NS, Canada</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>11</offset>
  </term>
  <term>
   <value>NS</value>
   <offset>19</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>23</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>6</offset>
   <length>4</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
...additional results ...
 <prediction>
  <description>Bondi Pizza, Campbell Parade, Sydney, New South Wales, Australia</description>
  <type>establishment</type>
  <place_id>ChIJv0wpwp6tEmsR0Glcf5tugrk</place_id>
  <reference>ClRPAAAADqzkHp7ZNKcaFxP-foYYI5dix_sSaqfkUgxEYaJrB0ntyg704tMG8sEJjebhIVLW4viCsKtnlxiBrrFk9fxq0ruf4oUdQDfv7zwmS4P68KQSEPKUkFNTgit63QOGRYeElv4aFJnD0wN2thFO6XFRq2JsHzQEirvC</reference>
  <id>c478ed4e7cb075b307fdce4ad4f6c9d15cab01d7</id>
  <term>
   <value>Bondi Pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Campbell Parade</value>
   <offset>13</offset>
  </term>
  <term>
   <value>Sydney</value>
   <offset>30</offset>
  </term>
  <term>
   <value>New South Wales</value>
   <offset>38</offset>
  </term>
  <term>
   <value>Australia</value>
   <offset>55</offset>
  </term>
  <matched_substring>
   <offset>6</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>30</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

An XML response consists of a single <AutocompletionResponse> element with two types of child elements:

  • A single <status> element contains metadata on the request. See Status Codes below.
  • Zero of more <prediction> elements, each containing information about a single query prediction. See Query Autocomplete Results for information about these results.

We recommend that you use json as the preferred output flag unless your application requires xml. Processing XML trees requires some care, so that you reference proper nodes and elements. See Parsing XML with XPath for help processing XML.

Status Codes

The status field within the Query Autocomplete response object contains the status of the request, and may contain debugging information to help you track down why the request failed. The status field may contain the following values:

  • OK indicates that no errors occurred and at least one result was returned.
  • ZERO_RESULTS indicates that the search was successful but returned no results. This may occur if the search was passed a bounds in a remote location.
  • OVER_QUERY_LIMIT indicates that you are over your quota.
  • REQUEST_DENIED indicates that your request was denied, generally because the key parameter is missing or invalid.
  • INVALID_REQUEST generally indicates that the input parameter is missing.
  • UNKNOWN_ERROR indicates a server-side error; trying again may be successful.

Error Messages

When the Places service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about the reasons behind the given status code.

Query Autocomplete Results

When the Places service returns JSON results from a search, it places them within a predictions array. Even if the service returns no results (such as if the location is remote) it still returns an empty predictions array. XML responses consist of zero or more <prediction> elements.

Each prediction result contains the following fields:

  • description contains the human-readable name for the returned result. For establishment results, this is usually the business name.
  • terms contains an array of terms identifying each section of the returned description (a section of the description is generally terminated with a comma). Each entry in the array has a value field, containing the text of the term, and an offset field, defining the start position of this term in the description, measured in Unicode characters.
  • matched_substring contains an offset value and a length. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.

Note that some of the predictions may be places, and the place_id and types fields will be included with those predictions. See Place Autocomplete Results for information about these results.

The sensor Parameter

The Places API previously required that you include the sensor parameter to indicate whether your application used a sensor to determine the user's location. This parameter is no longer required.

Send feedback about...

This page
Documentation feedback
Places API
Product feedback