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.
The API Explorer lets you make live requests so that you can get familiar with the API and the API options:
Try it!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, themaxWidthPx
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 details.
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/ChIJ2fzCmcW7j4AR2JzfXBBoh6EAn 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:
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 themaxWidthPx
parameter. - The value of the
maxHeightPx
or themaxWidthtPx
parameter was set tonull
. - The
name
has expired. Ifname
expires, make a request to Place Details (New), Nearby Search (New), or Text Search (New) to obtain a newname
.
Try it!
The API Explorer lets you make sample requests so that you can get familiar with the API and the API options.
To make a request:
- Select the API icon, , on the right side of the page.
- Set the
name
parameter to:places/PLACE_ID/photos/PHOTO_RESOURCE/media
- Set
skipHttpRedirect
totrue
so that the request returns a JSON response. By default, the request returns the image, which cannot be displayed by the API Explorer. - Select Execute button. In the pop-up, choose the account that you want to use to make the request.
In the API Explorer panel, select the expand icon, , to expand the API Explorer window.