Google Places API

Place Autocomplete

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

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.

  1. Examples of Mobile Apps using Place Autocomplete
  2. Place Autocomplete Requests
    1. Location Biasing
    2. Place Types
    3. Example Autocomplete Requests
  3. Place Autocomplete Responses
    1. Status Codes
    2. Error Messages
    3. Place Autocomplete Results

Examples of Mobile Apps using Place Autocomplete

The Place Autocomplete service is useful in mobile apps, where you may want to offer users a location-based autocomplete feature.

The following images show mobile applications using Place Autocomplete to assist a user in finding a location. In the first example, the request restricts the search to geographic place types. In the second example, all place types are returned. See more about Place Autocomplete requests below.

Android app using Place Autocomplete, courtesy of Airbnb:

Android app using Place Autocomplete

iOS app using Place Autocomplete, courtesy of Sunrise:

iOS app using Place Autocomplete

Place Autocomplete Requests

The Place Autocomplete service is part of the Google Places API and shares an API key and quotas with the Google 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.
  • sensor — Indicates whether or not the autocomplete 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 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 below.
  • language — The language in which to return results. See the supported list of domain languages. 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 country. The country 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.

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. Alternativley, use types=establishment to restrict results to establishments only.

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 (address) results. Generally, you use this request to disambiguate results where the location specified may be indeterminate.
  • 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_area1
    • administrative_area2
  • the (cities) type collection instructs the Places service to return results that match either locality or administrative_area3.

Example 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&sensor=true&key=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&sensor=true&key=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=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 URL request's path. The results below are returned for a query with the following parameters:

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions": [ {
    "description": "Paris, France",
    "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
    "reference": "CiQYAAAA0Q_JA...kT3ufVLDDvTQsOwZ_tc",
    "terms": [ {
      "value": "Paris",
      "offset": 0
    }, {
      "value": "France",
      "offset": 7
    } ],
    "types": [ "geocode" ],
    "matched_substrings": [ {
      "offset": 0,
      "length": 5
    } ]
  }, {
    "description": "Paris, TX, United States",
    "id" : "518e47f3d7f39277eb3bc895cb84419c2b43b5ac",
    "reference": "CjQjAAAAHnbxZZ...BDR3iIOFdMTxwo1jHg",
    "terms": [ {
      "value": "Paris",
      "offset": 0
    }, {
      "value": "TX",
      "offset": 7
    }, {
      "value": "United States",
      "offset": 11
    } ],
    "types": [ "geocode" ],
    "matched_substrings": [ {
      "offset": 0,
      "length": 5
    } ]
  }, {
    "description": "Paris, Ontario, Canada",
    "id" : "e7ac9c89d4a590305242b0cb5bf43064027223c9",
    "reference": "CjQhAAAAIv_YWYt...F8KZHY36TwMrbyu_g",
    "terms": [ {
      "value": "Paris",
      "offset": 0
    }, {
      "value": "Ontario",
      "offset": 7
    }, {
      "value": "Canada",
      "offset": 16
    } ],
    "types": [ "geocode" ],
    "matched_substrings": [ {
      "offset": 0,
      "length": 5
    } ]
  }
  ...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>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</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>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

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 reference 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 of 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.

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

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.
  • reference contains a unique token that you can use to retrieve additional information about this place in a Place Details request. You can store this token and use it at any time in future to refresh cached data about this place, but the same token is not guaranteed to be returned for any given place across different searches.
  • id contains a unique stable identifier denoting this place. This identifier may not be used to retrieve information about this place, but can be used to consolidate data about this place, and to verify the identity of a place across separate searches.
  • 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_substring contains an offset value and a length. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.