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 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'. Theoffset
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 aradius
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
{ "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:
status
contains metadata on the request. See Status Codes below.predictions
contains an array of query predictions. See Query Autocomplete Results for information about these results.
See Processing JSON with JavaScript for help parsing JSON responses.
<?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 abounds
in a remote location.OVER_QUERY_LIMIT
indicates that you are over your quota.REQUEST_DENIED
indicates that your request was denied, generally because thekey
parameter is missing or invalid.INVALID_REQUEST
generally indicates that theinput
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. Forestablishment
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 avalue
field, containing the text of the term, and anoffset
field, defining the start position of this term in the description, measured in Unicode characters.matched_substring
contains anoffset
value and alength
. 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.