The Place Photo service, part of the Places API, 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 request, photo references will be returned for relevant photographic content. Find Place, Nearby Search, and Text Search requests also return a single photo reference per place, when relevant. 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 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
photo_reference
A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.
maxheight or maxwidth
maxheight
specifies the maximum desired height, 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.maxwidth
specifies the maximum desired 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
andmaxwidth
properties accept an integer between1
and1600
.You must specify either
maxheight
, ormaxwidth
, or both.
Photo references
All requests to the Place Photo service must include a photo_reference
,
returned in the response to a Find Place, Nearby Search, Text Search, or Place Details
request. The response to these requests will contain a photos[]
field if the
place has related photographic content.
Note: The number of photos returned varies by request.
- A Find Place, Nearby Search, or Text Search request returns at most one
photo
element in the array. - A Place Details request returns up to ten
photo
elements.
Each photo
element contains 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 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 html_attributions
field, you must include the
additional attribution in your application wherever you display the image.
The following example shows a Place Details request:
curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"
An example of the photos[]
array in the response is shown below.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
}
...
Place Photo example
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&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q &key=YOUR_API_KEY
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:
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 reference was not correctly specified.
- The request did not include either the
maxwidth
or themaxheight
parameters. - The value for either the
maxwidth
or themaxheight
parameter was set tonull
. - The
photo_reference
has expired. Ifphoto_reference
expires, make a request to Place Details, Find Place, Nearby Search, or Text Search to get the updatedphoto_reference
value.