Google Developers Academy

Implementing a Basic Place Search

Learning objectives
  • Return a list of Places around a specific location.
  • Retrieve additional results about a specific Place.

Since the Google Places API is a web-based service, you must construct an appropriate Place Search request URL to retrieve a list of places. The most basic Place Search request URL has the following format:

https://maps.googleapis.com/maps/api/place/search/json
  ?location=COORDINATES_IN_LAT_LONG
  &radius=DISTANCE_IN_METERS
  &sensor=TRUE_OR_FALSE
  &key=YOUR_API_KEY

Parameters

There are three parameters that you must include for a Place search:

  • location: The latitude and longitude pair, in decimal degrees, where the search should originate. The coordinates you use for the location parameter can come from the GPS sensor of a mobile device, a browser that supports the HTML 5 Geolocation API, or can be derived from an address using a geocoding service, such as the Google Geocoding API. You can also manually determine the coordinates of an address using the Google Maps API Simple Geocoding Example.
  • 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. To get your key, follow the instructions listed in Obtaining an API Key, then come back to this lesson.

Optionally, you can include a radius parameter (with a value in meters) for retrieving Places ranked by prominence, which is the default ranking. Place prominence is determined using a number of factors, including Google search index rankings and Place check-ins. The Places API returns up to 20 places.

You can find out more about these parameters, as well as some other optional parameters, in the developer's guide.

Sending a Place Search Request

The following URL is an example of a basic Place Search request. After you’ve substituted your Places API key into the URL below, paste it into your browser’s address bar to retrieve the most prominent places within a 1 km radius of the Union Square Park in downtown San Francisco, California (for which the latitude is 37.787930 and longitude is -122.4074990).

https://maps.googleapis.com/maps/api/place/search/json
  ?location=37.787930,-122.4074990
  &radius=1000
  &sensor=false
  &key=YOUR_API_KEY

The sample response below shows the first three places returned for this Place Search request. The results are in JSON format, although you can retrieve the same results in XML by substituting json with xml in the URL.

{
   "html_attributions" : [],
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : 37.79593620000001,
               "lng" : -122.40000320
            },
            "viewport" : {
               "northeast" : {
                  "lat" : 37.80475270,
                  "lng" : -122.38399580
               },
               "southwest" : {
                  "lat" : 37.78711860,
                  "lng" : -122.41601060
               }
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/geocode-71.png",
         "id" : "7498697d87cb1a28280277cb7825e0a4c21387d6",
         "name" : "Financial District",
         "reference" : "CoQBegAAAFrgJ9ZyeZrV_a9QWteNl9hrNGq-9qhPIP0M9yIL00HhKzBJNERhX95nEnAAtgBKqc2e51Yq2-OG3g-D8YZ20pcFKK7n3Pipd3Rpz7JmFedlg-gimYv3YGhOYVhblHYhhJM8y48J7tbDT4QPKsnumhsyhTf-5YktikanlFKt3NKNEhDwKmUyXRDhsYS1-rzHCZSRGhQP5VmDcuvvxvYE7e7dC-0PWYhfjw",
         "types" : [ "neighborhood", "political" ],
         "vicinity" : "San Francisco"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : 37.7856560,
               "lng" : -122.4012520
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/art_gallery-71.png",
         "id" : "5e693f5ae4f1cd1512732b1568ff0e4b67ab0291",
         "name" : "San Francisco Museum of Modern Art",
         "rating" : 4.30,
         "reference" : "CpQBgQAAAO9fVOGklWz3ugJeJ0DuVibD60yFJ_z19hm5Cm7f4NYsIECaVqC2yhQ746w2vMmAJmA-jYNNwp5_ot7hsRxVmcbO1TdvBtYG3LZ6JD2vxgMXSCFK3U2McAywoOsbPwjU-9fN6jtHmvuiCXNDamIUP4IX462NsmyO06digENJcMoLES75jTTvVBjuRvNFRdIJnRIQDtf7lhNra8eTmAYy1PKKnhoU7hDZ-Y6TB8HRnHBsVDnsWnL5E0o",
         "types" : [ "art_gallery", "store", "establishment" ],
         "vicinity" : "151 Third Street, San Francisco"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : 37.7791590,
               "lng" : -122.4158080
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/library-71.png",
         "id" : "b1c83827c82c9fa59ffcdad652d1e8a1b04a4ae8",
         "name" : "San Francisco Public Library",
         "rating" : 4.20,
         "reference" : "CoQBewAAAP-wCLLWVV2kys-vTPPr9LZPUkZXqrUUjG6LTRmcVARlehuh_SkvisDlH5X6WgoX6BG16e7RSS94xxhZbj0B3i7gC1KFDz_Oc88hK6YUj3w8Ix0N5M6UmKfAIXq1CYXLMrt_KAR7WsNF65MiSnj-Nqu0AMxwW-dMvRfmHOk7xGW0EhCyRZgNzYmPV08XAHZ-HBx_GhQYlLxuAU4MH8FvkdMWbQ1Xvf7WxA",
         "types" : [ "library", "establishment" ],
         "vicinity" : "100 Larkin Street, San Francisco"
      },
…

The response includes a results array, with individual objects in the array for each Place returned. Location information is included as well as basic identifying information such as name and rating are returned.

Most importantly, note that a reference value is provided for each result. This reference value is what is used to request additional details about the Place. If you intend to request the extended details for any given place, you will need to keep track of each place’s reference value.

Now try additional Place Search requests by substituting the latitude and longitude coordinate pairs in the URL with locations in which you are interested. Below are some additional coordinate pairs to get you started.

  • Paris, France: 48.855228, 2.353134
  • Cape Town, South Africa: -33.924845,18.424072
  • Bangkok, Thailand: 13.748723,100.49881
  • Tokyo, Japan: 35.681109,139.75944

Requesting Place Details

If you need more comprehensive information about a particular Place included in a Place Search response, you can retrieve it using the Place Details service. This service allows you to retrieve additional information about Places, including phone number(s), componentized addresses, and web site URLs.

In order to retrieve a Place from the Place Details service, you first will need to obtain the reference value provided for each place in a Place Search response (as in the example above). You can use the reference value as a unique token to submit requests to the Place Details service for a specific Place.

The Python script below demonstrates how to query the Places Search service and extract the the reference value included in the response.

# Import the relevant libraries
import urllib2
import json

# Set the Places API key for your application
AUTH_KEY = 'Your API Key'

# Define the location coordinates
LOCATION = '37.787930,-122.4074990'

# Define the radius (in meters) for the search
RADIUS = 5000

# Compose a URL to query a predefined location with a radius of 5000 meters
url = ('https://maps.googleapis.com/maps/api/place/search/json?location=%s'
         '&radius=%s&sensor=false&key=%s') % (LOCATION, RADIUS, AUTH_KEY)

# Send the GET request to the Place details service (using url from above)
response = urllib2.urlopen(url)

# Get the response and use the JSON library to decode the JSON
json_raw = response.read()
json_data = json.loads(json_raw)

# Iterate through the results and print them to the console
if json_data[‘status’] == ‘OK’:
  for place in json_data['results']:
    print ‘%s: %s\n’ % (place['name'], place['reference'])'

Once you have the reference value for the Place for which you would like more information, you can use it to construct a Place Details request URL. These URLs must include a reference parameter as well as the sensor and key parameters discussed previously. After you add your API key to the following URL, you can copy it and paste it into your browser’s address bar to retrieve the Place details for the Coit Tower in San Francisco:

https://maps.googleapis.com/maps/api/place/details/json
?reference=CmRYAAAAciqGsTRX1mXRvuXSH2ErwW-jCINE1aLiwP64MCWDN5vkXvXoQGPKldMfmdGyqWSpm7BEYCgDm-iv7Kc2PF7QA7brMAwBbAcqMr5i1f4PwTpaovIZjysCEZTry8Ez30wpEhCNCXpynextCld2EBsDkRKsGhSLayuRyFsex6JA6NPh9dyupoTH3g
  &sensor=false
  &key=YOUR_API_KEY

This Place Details query will retrieve the following results:

  "html_attributions" : [],
   "result" : {
      "address_components" : [
         {
            "long_name" : "1",
            "short_name" : "1",
            "types" : [ "street_number" ]
         },
         {
            "long_name" : "Telegraph Hill Blvd",
            "short_name" : "Telegraph Hill Blvd",
            "types" : [ "route" ]
         },
         {
            "long_name" : "San Francisco",
            "short_name" : "San Francisco",
            "types" : [ "locality", "political" ]
         },
         {
            "long_name" : "CA",
            "short_name" : "CA",
            "types" : [ "administrative_area_level_1", "political" ]
         },
         {
            "long_name" : "US",
            "short_name" : "US",
            "types" : [ "country", "political" ]
         },
         {
            "long_name" : "94133",
            "short_name" : "94133",
            "types" : [ "postal_code" ]
         }
      ],
      "formatted_address" : "1 Telegraph Hill Blvd, San Francisco, CA, United States",
      "formatted_phone_number" : "(415) 362-0808",
      "geometry" : {
         "location" : {
            "lat" : 37.8023860,
            "lng" : -122.40590
         }
      },
      "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
      "id" : "b29bfcfc1c01d4fb92de2cb3e5bc1c18fc3fb446",
      "international_phone_number" : "+1 415-362-0808",
      "name" : "Coit Tower",
      "rating" : 4.0,
      "reference" : "CnRoAAAA8MjAq8vd7YoBXpjv7HjIUy45BK_loXguYs7ckASmLz8gnUpR1FeiU1B9wQw5epzyiep4ruJgAEu6T7gVcPa9tsbm3eEKIYR2s9LvCU0FZSwkhOUHQShur7sMSF0U-nIrXfp_P_HWEXuqueCSrlVuQRIQT99Bvb7DGjWgXjBIQEeDlBoUbrwbFFgtnyr-ME5GXUt4F27Q-y4",
      "types" : [ "park", "establishment" ],
      "url" : "http://maps.google.com/maps/place?cid=16034424363326561604",
      "vicinity" : "1 Telegraph Hill Blvd, San Francisco",
      "website" : "http://sfrecpark.org/CoitTower.aspx"
   },
   "status" : "OK"
}

Now try using some of the reference values from the other queries you used in the previous section on Place Searches to retrieve the details for other places that interest you.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.