Google Places API

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

Place Photos

The Places Photo service is a read-only API that allows you to easily add high quality photographic content to your application. The Photo service gives you access to the millions of photos stored in the Places and Google+ Local database. When you search for Places using either a Place Search or Place Details request, photo references will be returned for relevant photographic content. The Photo service lets you access the referenced photos, and resize the image to the optimal size for your application.

Photo References

All requests to the Place Photo service must include a photoreference, returned in the response to a Place Search or Place Details request. The response to either service will contain a photos[] field if that Place has related photographic content. The number of photos returned varies by request. A Place Search will return at most one photo element in the array while the Details request will return up to ten photo elements. Each photo element will contain the following fields:

  • photo_reference — a string used to identify the photo when you perform a Photo request.
  • height — the maximum height of the image.
  • width — the maximum width of the image.
  • html_attributions[] — contains any required attributions. This field will always be present, but may be empty.

Photos returned by the Photo service are sourced from a variety of locations, including business owners and Google+ users contributed photos. In most cases, these photos can be used without attribution, or will have the required attribution included as a part of the image. However, if the returned photo element includes a value in the html_attributions field, you will have to include the additional attribution in your application wherever you display the image.

An example of a photos[] array is shown below.

...
"photos" : [
   {
      "html_attributions" : [],
      "height" : 853,
      "width" : 1280,
      "photo_reference" : "CnRvAAAAwMpdHeWlXl-lH0vp7lez4znKPIWSWvgvZFISdKx45AwJVP1Qp37YOrH7sqHMJ8C-vBDC546decipPHchJhHZL94RcTUfPa1jWzo-rSHaTlbNtjh-N68RkcToUCuY9v2HNpo5mziqkir37WU8FJEqVBIQ4k938TI3e7bf8xq-uwDZcxoUbO_ZJzPxremiQurAYzCTwRhE_V0"
   }
...

Place Photo Requests

A Place Photo request is an HTTP URL of the following form:

https://maps.googleapis.com/maps/api/place/photo?parameters

Certain parameters are required to initiate a search 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

  • key — Your application's API key. This key identifies your application for purposes of quota management. Visit the APIs Console to create an API Project and obtain your key.
  • photoreference — A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.
  • sensor — Indicates whether or not the Place Photo request came from a device using a location sensor (e.g. a GPS). This value must be either true or false.
  • maxheight or maxwidth — Specifies the maximum desired height or width, in pixels, of the image returned by the Place Photos service. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio. Both the maxheight and maxwidth properties accept an integer between 1 and 1600.

An example request is shown below. This request will return the referenced image, resizing it so that it is at most 400 pixels wide.

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photoreference=CoQBegAAAFg5U0y-iQEtUVMfqw4KpXYe60QwJC-wl59NZlcaxSQZNgAhGrjmUKD2NkXatfQF1QRap-PQCx3kMfsKQCcxtkZqQ&sensor=true&key=AddYourOwnKeyHere

Note that you'll need to replace the photo reference and key in this example in order for the request to work in your application.

Place Photo Response

The response of a successful Place Photo request will be an image. The type of the image will depend upon the type of the originally submitted photo.

If your request exceeds your available quota, the server will return an HTTP 403 status and display the below image to indicate that the quota has been exceeded:

Over Quota image

If the server is unable to understand your request, it will return HTTP 400 status, which indicates an invalid request. The most common reasons why you might see an invalid request include:

  • The submitted photo reference was incorrectly specified.
  • Your request did not include either a maxwidth or maxheight parameter.

Error Messages

When the Places service returns an HTTP 400 status, there may be an additional error_message field within the response object. This field contains more detailed information about the reasons behind the status code.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.