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.

Note: You can use Place Autocomplete even
without a map. If you do show a map, it must be a Google map. When you display
predictions from the Place Autocomplete service without a map, you must
include the
'Powered by
Google' logo.

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.

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 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

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 the offset is 3, the service will
match on 'Goo'. The string determined by the offset is matched
against the first word in the input term only. For example, if the input
term is 'Google abc' and the offset is 3, the service will
attempt to match against 'Goo abc'. If no offset is supplied,
the service will use the whole term. The offset should
generally be set to the position of the text caret.

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 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 use
components 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 multiple country: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.

strictbounds — Returns only those places that are
strictly within the region defined by location and radius. 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 can use session tokens to group together autocomplete
requests for billing purposes. A session token is a random string that is used
to uniquely identify a session. A session consists of the activities required to
resolve user input to a place. When a session token is passed (using the
optional session_token parameter), autocomplete requests are not
billed independently, but are instead billed once after a full autocomplete
result is returned. If the session_token parameter is omitted, each
request is billed independently. See the pricing sheet
for details.

Warning: Be sure to pass a unique
session token for each new session. Using the same token for more than one
session will result in each request being billed individually. Using a version
4 UUID is recommended.

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.

Note: If you do not supply the location
and radius, the API will attempt to detect the user's location from their
IP address, and will bias the results to that location.

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 match locality or
administrative_area_level_3.

Examples of Place Autocomplete requests

A request for establishments containing the string "Amoeba" within
an area centered in San Francisco, CA:

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:

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
Parsing
XML with XPath for help processing XML.

From our Terms of Service

Display the requiredlogos 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 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 an invalid key parameter.

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.

Note: This field is not guaranteed to be
always present, and its content is subject to change.

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. For establishment results,
this is usually the business name.

place_id is a textual identifier that uniquely identifies a
place. To retrieve information about the place, pass this identifier in the
placeId field of a Places API request.
For more information about place IDs, see the
place ID 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 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.

types contains an array of types that apply to this place.
For example: [ "political", "locality" ] or
[ "establishment", "geocode" ].

matched_substrings contains an array with offset
value and length. These describe the location of the entered
term in the prediction result text, so that the term can be highlighted if
desired.

structured_formatting 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 with
offset value and length. 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.

Note: The Place Autocomplete response does not
include the scope or alt_ids fields that you may see
in search results or place details. This is because Autocomplete returns only
Google-scoped place IDs. It does not return app-scoped place IDs that have
not yet been accepted into the Google Places database. For more details about
Google-scoped and app-scoped place IDs, see the documentation on
adding places.

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.