Google Places API

Query Autocomplete

Looking to use this service in a JavaScript application? Check out the Places Library of the Google Maps API v3.

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

  1. Query Autocomplete Requests
    1. Location Biasing
    2. Example Autocomplete Requests
  2. Query Autocomplete Responses
    1. Status Codes
    2. Error Messages

Query Autocomplete Requests

The Google Query Autocomplete API is part of the Google Places API and shares an API key and quotas 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 as well as 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 of: 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 Place service will return candidate matches based on this string and order results based on their perceived relevance.
  • sensor — Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request. This value must be either true or false.
  • key — Your application's API key. This key identifies your application for purposes of quota management. Visit the APIs Console to select an API Project and obtain your key. Maps API for Business customers must use the API project created for them as part of their Places for Business 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 in which to return results. See the supported list of domain languages. If language is not supplied, the Place 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 Place 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=AddYourOwnKeyHere&sensor=false&input=pizza+near%20par

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

  https://maps.googleapis.com/maps/api/place/queryautocomplete/json?key=AddYourOwnKeyHere&sensor=false&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 parameters:

https://maps.googleapis.com/maps/api/place/queryautocomplete/xml?&key=AddYourOwnKeyHere&sensor=false&input=pizza+near+par

JSON
{
   "predictions" : [
      {
         "description" : "pizza near Paris, France",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 6
            },
            {
               "length" : 4,
               "offset" : 11
            }
         ],
         "terms" : [
            {
               "offset" : 0,
               "value" : "pizza"
            },
            {
               "offset" : 6,
               "value" : "near"
            },
            {
               "offset" : 11,
               "value" : "Paris"
            },
            {
               "offset" : 18,
               "value" : "France"
            }
         ]
      },
      {
         "description" : "Pizza Pronto, Rue Didot, Paris, France",
         "id" : "6aa3d2766116fc6e5c98fb4c2966bd91098d91fc",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 25
            }
         ],
         "reference" : "CkQ0AAAAdx9n4vp6EvNGF50sTnzL8Rkl7glVPDc5TzBzdZfovatJRR8YX2_nJEzC4cTKlaaxGRGNyDGoFeAW3tZfi1qT6BIQYkVaSZj5MUdVn-3t_M2nkxoUqLMuhaAKRrCRKmJq97tPL9rJETk",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Pizza Pronto"
            },
            {
               "offset" : 14,
               "value" : "Rue Didot"
            },
            {
               "offset" : 25,
               "value" : "Paris"
            },
            {
               "offset" : 32,
               "value" : "France"
            }
         ],
         "types" : [ "establishment" ]
      },
      {
         "description" : "Pizza Sant'Antonio, Rue de la Verrerie, Paris, France",
         "id" : "1822d9ce7580e1bcedacc6dfba74eb0d061109dc",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            },
            {
               "length" : 4,
               "offset" : 40
            }
         ],
         "reference" : "ClRDAAAAO4ICVfX08avOOg3Jro2AsvD0IkSMU67DWqx_o7izZ_RwtCeqoMUJ1KV9m77JejUIK3kbZcjQ8Q6-uny4S80KIQ47Lcxx4UNb03ErHEBxlVUSEHHAKlXSwSP0E7u_f3w_LU4aFF5_-rpZC_NXppYqWcmALbi8fXKT",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Pizza Sant'Antonio"
            },
            {
               "offset" : 20,
               "value" : "Rue de la Verrerie"
            },
            {
               "offset" : 40,
               "value" : "Paris"
            },
            {
               "offset" : 47,
               "value" : "France"
            }
         ],
         "types" : [ "establishment" ]
      },
        ...additional results ...
     "status" : "OK"
  }
      

A JSON response contains two root elements:

  • status contains metadata on the request. See Status Codes below.
  • predictions contains an array of query predictions. Note that some of the predictions may be Places, and place references and place types will be included with those predictions.

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 Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>France</value>
   <offset>18</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>4</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Pizza Pronto, Rue Didot, Paris, France</description>
  <type>establishment</type>
  <reference>CkQ0AAAAwl2pMOOLLq5TiV-FU48UEAkpmp9vF0gWHkYBR0aSZ9LBnM1lKVBEAJDPE8RaAFxBKFtdn2XOpr8pGdSUo5WRxhIQ-jPZQmPLm-ipIzcWJtPBOxoUlz0g6p13jfbjjVh9gu4riuMPXRc</reference>
  <id>6aa3d2766116fc6e5c98fb4c2966bd91098d91fc</id>
  <term>
   <value>Pizza Pronto</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Rue Didot</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>25</offset>
  </term>
  <term>
   <value>France</value>
   <offset>32</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>25</offset>
   <length>4</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Pizza Sant'Antonio, Rue de la Verrerie, Paris, France</description>
  <type>establishment</type>
  <reference>ClRDAAAAYN1M9mrYRw3K-6KlmegeywFI2WdTWnuYWg-jiuL-MPjXH_IkjGi8ZdjX_t8eV9ZmDyoinPAuJynsLUJWgpaRWkNrGXC26g20mgFye1IPsa0SEFQJXNitukdsVqX2VaWxd7saFK5UDQGlcLTl1YJY7f8_nyzngOu_</reference>
  <id>1822d9ce7580e1bcedacc6dfba74eb0d061109dc</id>
  <term>
   <value>Pizza Sant'Antonio</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Rue de la Verrerie</value>
   <offset>20</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>40</offset>
  </term>
  <term>
   <value>France</value>
   <offset>47</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>40</offset>
   <length>4</length>
  </matched_substring>
 </prediction>
...additional results ...
</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.

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 of lack of a sensor parameter.
  • INVALID_REQUEST generally indicates that the input parameter is missing.

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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.