Place Autocomplete

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 and substrings, resolving place names, addresses, and plus codes. 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 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.
  • origin — The origin point from which to calculate straight-line distance to the destination (returned as distance_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 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.

    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 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 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 and a call to Place Details is made. Each session can have multiple queries, followed by one place selection. The API key(s) used for each request within a session must belong to the same Google Cloud Console project. Once a session has concluded, the token is no longer valid; your app must generate a fresh token for each session. 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).

We recommend the following guidelines:

  • Use session tokens for all autocomplete sessions.
  • Generate a fresh token for each session. Using a version 4 UUID is recommended.
  • Ensure that the API key(s) used for all Place Autocomplete and Place Details requests within a session belong to the same Google Cloud Console project.
  • 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.

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

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

JSON
{
  "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
<?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.

Learn More

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 a valid 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.

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.
  • distance_meters contains an integer indicating the straight-line distance between the predicted place, and the specified origin point, in meters. This field is only returned when the origin point is specified in the request. This field is not returned in predictions of type route.
  • 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 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 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", "beauty_salon" ]. The array can contain multiple values. Learn more about Place types.
  • 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 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 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.

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.