The Place Autocomplete service is a web service 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.
Place Autocomplete Requests
The Place Autocomplete service is part of the Places API and shares an API key and quotas with the Places API.
The Place Autocomplete service 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.
The returned predictions are designed to be presented to the user to aid them in selecting the desired place. You can send a Place Details request for more information about any of the places which are returned.
A Place Autocomplete request is an HTTP URL of the following form:
https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters
where output
may be either of the following values:
json
(recommended) indicates output in JavaScript Object Notation (JSON)xml
indicates output as XML
Certain parameters are required to initiate a Place 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 Autocomplete 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 API 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
sessiontoken
— A random string which identifies an autocomplete session for billing purposes. If this parameter is omitted from an autocomplete request, the request is billed independently. See the pricing sheet for details.offset
— The position, in the input term, of the last character that the service uses to match predictions. For example, if the input is 'Google' and theoffset
is 3, the service will match on 'Goo'. The string determined by theoffset
is matched against the first word in the input term only. For example, if the input term is 'Google abc' and theoffset
is 3, the service will attempt to match against 'Goo abc'. If nooffset
is supplied, the service will use the whole term. Theoffset
should generally be set to the position of the text caret.origin
— The origin point from which to calculate straight-line distance to the destination (returned asdistance_meters
). If this value is omitted, straight-line distance will not be returned. Must be specified as latitude,longitude.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 and Location Restrict below.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 list of supported languages and their codes. Note that we often update supported languages so this list may not be exhaustive. If language is not supplied, the Place Autocomplete service will attempt to use the native language of the domain from which the request is sent.types
— The types of place results to return. See Place Types below. If no type is specified, all types will be returned.components
— A grouping of places to which you would like to restrict your results. Currently, you can usecomponents
to filter by up to 5 countries. Countries must be passed as a two character, ISO 3166-1 Alpha-2 compatible country code. For example:components=country:fr
would restrict your results to places within France. Multiple countries must be passed as multiplecountry:XX
filters, with the pipe character (|) as a separator. For example:components=country:us|country:pr|country:vi|country:gu|country:mp
would restrict your results to places within the United States and its unincorporated organized territories.Note: If you receive unexpected results with a country code, verify that you are using a code which includes the countries, dependent territories, and special areas of geographical interest you intend. You can find code information at Wikipedia: List of ISO 3166 country codes or the ISO Online Browsing Platform.
strictbounds
— Returns only those places that are strictly within the region defined bylocation
andradius
. This is a restriction, rather than a bias, meaning that results outside this region will not be returned even if they match the user input.
Session tokens
Place Autocomplete uses session tokens to group the query and selection
phases of a user autocomplete search into a discrete session for billing
purposes. The session begins when the user starts typing a query, and concludes
when they select a place. Each session can have multiple queries, followed by
one place selection. Once a session has concluded, the token is no longer
valid; your app must generate a fresh token for each session. We recommend
using session tokens for all autocomplete sessions. If the
sessiontoken
parameter is omitted, or if you reuse a session
token, the session is charged as if no session token was provided (each request
is billed separately).
Read more about session tokens.
The following example shows a request using the sessiontoken
parameter:
https://maps.googleapis.com/maps/api/place/autocomplete/json?input=1600+Amphitheatre&key=<API_KEY>&sessiontoken=1234567890
Location biasing
You may bias results to a specified circle by passing a
location
and a radius
parameter. This
instructs the Place Autocomplete service to prefer showing results
within that circle. Results outside of the defined area may still be
displayed. You can use the components
parameter to filter results
to show only those places within a specified country.
Tip: Establishment results generally do not rank highly
enough to show in results when the search area is large. If you want
establishments to appear in mixed establishment/geocode results, you can
specify a smaller radius. Alternatively, use types=establishment
to restrict results to establishments only.
Location restrict
You may also restrict results to the region defined by location
and a radius
parameter, by adding the strictbounds
parameter. This instructs the Place Autocomplete service to return only
results within that region.
Place types
You may restrict results from a Place Autocomplete request to be of a certain
type by passing a types
parameter. The parameter specifies a type
or a type collection, as listed in the supported types below. If nothing is
specified, all types are returned. In general only a single type is allowed.
The exception is that you can safely mix the geocode
and
establishment
types, but note that this will have the same effect
as specifying no types. The supported types are:
geocode
instructs the Place Autocomplete service to return only geocoding results, rather than business results. Generally, you use this request to disambiguate results where the location specified may be indeterminate.address
instructs the Place Autocomplete service to return only geocoding results with a precise address. Generally, you use this request when you know the user will be looking for a fully specified address.establishment
instructs the Place Autocomplete service to return only business results.- the
(regions)
type collection instructs the Places service to return any result matching the following types:locality
sublocality
postal_code
country
administrative_area_level_1
administrative_area_level_2
- the
(cities)
type collection instructs the Places service to return results that matchlocality
oradministrative_area_level_3
.
Examples of Place Autocomplete requests
A request for establishments containing the string "Amoeba" within an area centered in San Francisco, CA:
https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY
The same request, restricted to results within 500 meters of Ashbury St & Haight St, San Francisco:
https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY
A request for addresses containing "Vict" with results in French:
https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY
A request for cities containing "Vict" with results in Brazilian Portuguese:
https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY
Note that you'll need to replace the API key in these examples with your own key.
Place Autocomplete responses
Place Autocomplete responses are returned in the format indicated by the
output
flag within the request's URL path. The results below are
indicative of what may be returned for a query with the following
parameters:
input=Paris&types=geocode
{ "status": "OK", "predictions" : [ { "description" : "Paris, France", "distance_meters" : 8030004, "id" : "691b237b0322f28988f3ce03e321ff72a12167fd", "matched_substrings" : [ { "length" : 5, "offset" : 0 } ], "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ", "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw", "terms" : [ { "offset" : 0, "value" : "Paris" }, { "offset" : 7, "value" : "France" } ], "types" : [ "locality", "political", "geocode" ] }, { "description" : "Paris-Madrid Grocery (Spanish Table Seattle), Western Avenue, Seattle, WA, USA", "distance_meters" : 12597, "id" : "f4231a82cfe0633a6a32e63538e61c18277d01c0", "matched_substrings" : [ { "length" : 5, "offset" : 0 } ], "place_id" : "ChIJHcYlZ7JqkFQRlpy-6pytmPI", "reference" : "ChIJHcYlZ7JqkFQRlpy-6pytmPI", "structured_formatting" : { "main_text" : "Paris-Madrid Grocery (Spanish Table Seattle)", "main_text_matched_substrings" : [ { "length" : 5, "offset" : 0 } ], "secondary_text" : "Western Avenue, Seattle, WA, USA" }, "terms" : [ { "offset" : 0, "value" : "Paris-Madrid Grocery (Spanish Table Seattle)" }, { "offset" : 46, "value" : "Western Avenue" }, { "offset" : 62, "value" : "Seattle" }, { "offset" : 71, "value" : "WA" }, { "offset" : 75, "value" : "USA" } ], "types" : [ "grocery_or_supermarket", "food", "store", "point_of_interest", "establishment" ] }, { "description" : "Paris, TX, USA", "distance_meters" : 2712292, "id" : "518e47f3d7f39277eb3bc895cb84419c2b43b5ac", "matched_substrings" : [ { "length" : 5, "offset" : 0 } ], "place_id" : "ChIJmysnFgZYSoYRSfPTL2YJuck", "reference" : "ChIJmysnFgZYSoYRSfPTL2YJuck", "structured_formatting" : { "main_text" : "Paris", "main_text_matched_substrings" : [ { "length" : 5, "offset" : 0 } ], "secondary_text" : "TX, USA" }, "terms" : [ { "offset" : 0, "value" : "Paris" }, { "offset" : 7, "value" : "TX" }, { "offset" : 11, "value" : "USA" } ], "types" : [ "locality", "political", "geocode" ] }, ...additional results ...
<?xml version="1.0" encoding="UTF-8"?> <AutocompletionResponse> <status>OK</status> <prediction> <description>Paris, France</description> <type>locality</type> <type>political</type> <type>geocode</type> <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference> <id>691b237b0322f28988f3ce03e321ff72a12167fd</id> <term> <value>Paris</value> <offset>0</offset> </term> <term> <value>France</value> <offset>7</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id> <structured_formatting> <description>Paris</description> <subdescription>France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> <distance_meters>8030004</distance_meters> </prediction> <prediction> <description>Paris-Madrid Grocery (Spanish Table Seattle), Western Avenue, Seattle, WA, USA</description> <type>grocery_or_supermarket</type> <type>food</type> <type>store</type> <type>point_of_interest</type> <type>establishment</type> <reference>ChIJHcYlZ7JqkFQRlpy-6pytmPI</reference> <id>f4231a82cfe0633a6a32e63538e61c18277d01c0</id> <term> <value>Paris-Madrid Grocery (Spanish Table Seattle)</value> <offset>0</offset> </term> <term> <value>Western Avenue</value> <offset>46</offset> </term> <term> <value>Seattle</value> <offset>62</offset> </term> <term> <value>WA</value> <offset>71</offset> </term> <term> <value>USA</value> <offset>75</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJHcYlZ7JqkFQRlpy-6pytmPI</place_id> <structured_formatting> <description>Paris-Madrid Grocery (Spanish Table Seattle)</description> <subdescription>Western Avenue, Seattle, WA, USA</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> <distance_meters>12597</distance_meters> </prediction> <prediction> <description>Paris, TX, USA</description> <type>locality</type> <type>political</type> <type>geocode</type> <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference> <id>518e47f3d7f39277eb3bc895cb84419c2b43b5ac</id> <term> <value>Paris</value> <offset>0</offset> </term> <term> <value>TX</value> <offset>7</offset> </term> <term> <value>USA</value> <offset>11</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id> <structured_formatting> <description>Paris</description> <subdescription>TX, USA</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> </structured_formatting> <distance_meters>2712292</distance_meters> <extension> <score>1.1127435</score> </extension> </prediction> ...additional results ...
A JSON response contains two root elements:
status
contains metadata on the request. See Status Codes below.predictions
contains an array of places, with information about the place. See Place Autocomplete Results for information about these results. The Places API returns up to 5 results.
Of particular interest within the results are the place_id
elements, which can be used to request more specific details about the
place via a separate query. See
Place Details
requests.
See Processing JSON with JavaScript for help parsing JSON responses.
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 or more
<prediction>
elements, each containing information about a single place. See Place Autocomplete Results for information about these results. The Places API returns up to 5 results.
We recommend that you use json
as the preferred output flag
unless your application requires xml
for some reason.
Processing XML trees requires some care, so that you reference proper nodes
and elements. See
Processing
XML with XPath for help processing XML.
From our Terms of Service
Display the required
logos and attributions
Respect Google's copyrights and attribution. Ensure that the logo and copyright notice are visible, and display the "powered by Google" logo if you're using data without a map.

Status codes
The status
field within the Place Autocomplete response object
contains the status of the request, and may contain debugging information
to help you track down why the Place Autocomplete 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 of lack of an invalidkey
parameter.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.
Place 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.distance_meters
contains an integer indicating the straight-line distance between the predicted place, and the specifiedorigin
point, in meters. This field is only returned when theorigin
point is specified in the request. This field is not returned in predictions of typeroute
.place_id
is a textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in theplaceId
field of a Places API request. For more information about place IDs, see the Place IDs overview.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.types
contains an array of types that apply to this place. For example:[ "political", "locality" ]
or[ "establishment", "geocode", "beauty_salon" ]
. The array can contain multiple values. Learn more about Place types.matched_substrings
contains an array withoffset
value andlength
. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.structured_formatting
provides pre-formatted text that can be shown in your autocomplete results, and contains the following subfields:main_text
contains the main text of a prediction, usually the name of the place.main_text_matched_substrings
contains an array withoffset
value andlength
. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.secondary_text
contains the secondary text of a prediction, usually the location of the place.
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.