Google Developers Academy

Using Place Autocomplete to Make Search Easier

Learning objectives
  • Learn about the Place Autocomplete service.
  • Use region biasing to narrow the result set.

The Google Place Autocomplete service is a simple yet powerful feature of the Google Places API. It provides real-time, predictive search against strings (partial or complete) that a user types into a text input box like the one below.

The Places results that are returned are similar to the Places Search results.

As with the other HTTP-based parts of the Google Places API, the Place Autocomplete service returns results in JSON or XML. Since you’ve already worked through the previous lessons, the sample results in the sections below should look familiar.

Note: As with the Google Places API web service, you’ll need to use an API key to authenticate your requests. The Place Autocomplete service is subject to the same usage limits as the Google Places API.

Testing Out a Sample Request

You can familiarize yourself with making a request to the Place Autocomplete service by copying and pasting the sample URL below into your browser’s URL address bar. Be sure to replace YOUR_API_KEY with your own API key. This is a search for the string bank:

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=bank
  &sensor=false
  &key=YOUR_API_KEY

As you can see, the response is in JSON and contains several places that contain the specified string (the example below only displays the first result):

{
   "predictions" : [
      {
         "description" : "Bankstown, New South Wales, Australia",
         "id" : "f3c6aed570eb75d9ae9642d91d5805950438dce1",
         "matched_substrings" : [
            {
               "length" : 4,
               "offset" : 0
            }
         ],
         "reference" : "CkQ9AAAAXbAzvCvFbxNiraj2kWcRMHwksSzKjUMYSP4W6QXF5dSfQwWFoQSj3Vk1geo1hGnE6E8K7wJVgkmqjeBvENTB9BIQwCfgfnkMkDJvEA2SRHYEdhoUoAh3fIdJZm8GKJbj9IZiEKf6-WY",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Bankstown"
            },
            {
               "offset" : 11,
               "value" : "New South Wales"
            },
            {
               "offset" : 28,
               "value" : "Australia"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },

…

The first result is for the city of Bankstown in New South Wales, Australia, and this place would be the first result shown to a user if you displayed the results after the user typed four characters.

Parameters

There are three required parameters that you’ll need to include with any request to the Place Autocomplete service:

  • input: The string to search for.
  • sensor: Indicates whether the location is coming from a sensor device, such as a GPS. The value can be true or false.
  • key: A Places API key from the APIs Console.

There are various other request parameters that you can use with the Place Autocomplete service, including a location, Place types, radius, country, and more. You can pick and choose which request parameters will work best based on your intended use case(s).

Region biasing by area

For example, if you know that your user is only looking for Places close to a specific point, then your requests should include the location and radius parameters to restrict results to the defined area. This approach is called region biasing.

For example, to restrict the previous bank search to a specific area:

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=bank
  &location=37.769036,-122.483439
  &radius=500
  &sensor=false
  &key=YOUR_API_KEY

Try it out and you’ll see that the results are now filtered for San Francisco.

Region biasing by country

In addition to using location and radius, you can use the the components parameter to set region biasing by country. This is useful for applications that are only used in a specific country, or for searches in which you know that the search needs to be limited to a specific country. You’ll need to find out the ISO 2 letter country code for the desired country.

You can try out using the components parameter by replacing the location and radius parameters from the last example with components=country:xx. In the example below, the results are biased for the United Kingdom (for which the country code is < code>gb).

https://maps.googleapis.com/maps/api/place/autocomplete/json
  ?input=bank
  &components=country:gb
  &sensor=false
  &key=YOUR_API_KEY

Note how the results are all for places in the United Kingdom.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.