Place Photo (New)

The Place Photo (New) service is a read-only API that allows you to add high quality photographic content to your application. The Place Photo service gives you access to the millions of photos stored in the Places database.

When you get place information using a Place Details, Nearby Search, or Text Search request, you can also request photo resources for relevant photographic content. Using the Photo service, you can then access the referenced photos and resize the image to the optimal size for your application.

Place Photo requests

A Place Photo request is an HTTP GET request to a URL in the form:
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Where the following parameters are required:

  • NAME contains the resource name of the photo.
  • API_KEY contains the API key.
  • PARAMETERS contains either the maxHeightPx parameter, the maxWidthPx parameter, or both.

The complete list of required and optional parameters are described below.

Required parameters

Photo name

A string identifier that uniquely identifies a photo. Photo names are returned from a Place Details (New), Nearby Search (New), or Text Search (New) request in the name property of each element of the photos[] array.

For an example, see Get a photo name.

maxHeightPx and maxWidthPx

Specifies the maximum desired height and width, in pixels, of the image. 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 4800.

You must specify either maxHeightPx, or maxWidthPx, or both.

Optional parameters

skipHttpRedirect

If false (default), make an HTTP redirect to the image to return the image. If true, skip the redirect and return a JSON response containing the image defails. For example:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

This option is ignored for non-HTTP requests.

Get a photo name

All requests to the Place Photo service must include a photo resource name, returned in the response to a Nearby Search, Text Search, or Place Details request. The response to these requests contains a photos[] array if the place has related photographic content.

Each elements of photo[] contains the following fields:

  • name — A string containing the resource name of the photo when you perform a Photo request. This string is in the form:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx — The maximum height of the image, in pixels.
  • widthPx — The maximum width of the image, in pixels.
  • authorAttributions[] — Any required attributions. This field is always present, but might be empty.

Photos returned by the Photo service are sourced from a variety of locations, including business owners and user 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 authorAttributions field, you must include the additional attribution in your application wherever you display the image.

The following example shows a Place Details request that includes photos in the field mask so that the response includes the photos[] array in the response:

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
An example of a photos[] array in the response is shown below.
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },    ...

Request a place photo

The example request below returns an image using its resource name, resizing it so that it is at most 400 pixels tall and wide:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

The response of a successful Place Photo request is an image. The type of the image depends on the type of the originally submitted photo.

If your request exceeds your available quota, the server returns 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, then it returns HTTP 400 status, which indicates an invalid request. The most common reasons for an invalid request include:

  • The submitted photo name was not correctly specified.
  • The request did not include the maxHeightPx or the maxWidthPx parameter.
  • The value of the maxHeightPx or the maxWidthtPx parameter was set to null.
  • The name has expired. If name expires, make a request to Place Details (New), Nearby Search (New), or Text Search (New) to obtain a new name.