You can use the Places SDK for Android to request a place photo to display in your application. Photos returned by the photos service come from a variety of sources, including business owners and user-contributed photos.
Choose the photo format
Places SDK for Android supports two formats for the requested photo:
- All Places SDK for Android versions: Returns the bitmap image. The bitmap image has a maximum size of 1600 by 1600 pixels.
- Places SDK for Android (New) version 3.4 and later: Returns a URI to the bitmap image. The bitmap image has a maximum size of 4800 by 4800 pixels.
Photo retrieval process
To retrieve an image for a place:
- Use Place Details to fetch a
Place
object (use eitherfetchPlace()
orfindCurrentPlace()
). Be sure to include thePlace.Field PHOTO_METADATAS
field in the list of fields to include in the responsePlace
object. - In the
OnSuccessListener
for yourFetchPlaceResponse
orFindCurrentPlaceResponse
:- Use
Place.getPhotoMetadas()
to get the photo metadata object, of typePhotoMetadata
from the responsePlace
object. - To get a bitmap image:
- Create a
FetchPhotoRequest
object, optionally specifying maximum height and width (in pixels). Photos can have a maximum width or height of 1600px. - Use
PlacesClient.fetchPhoto()
to request the photo bitmap. - Add an
OnSuccessListener
and get the photo from theFetchPhotoResponse
.
- Create a
- To get a photo URI:
- Create a
FetchResolvedPhotoUriRequest
object to make the request. Photos can have a maximum width or height of 4800px. - Use
PlacesClient.fetchResolvedPhotoUri()
to request the photo URI. - Add an
OnSuccessListener
and get the photo URI from theFetchResolvedPhotoUriResponse
object.
- Create a
- Use
Access PhotoMetadata data added in version 3.3.0 and later
The Places SDK for Android (New) adds the
AuthorAttributions
field to the PhotoMetadata
class. If your app enables the new SDK, then the
PhotoMetadata
object returned by Place.getPhotoMetadas()
can contain one
or more author attributions.
When the PhotoMetadata
object contains any attributions, either the new author
attributions added in version 3.3.0 or the existing attributions available in version 3.2.0 and
earlier, you must display them with the photo. For more information on handling all types of
attributions, see Attributions.
To populate the PhotoMetadata
object with author attributions, you must:
- Enable the new SDK when you Set up your Google Cloud project.
- Initialize the new SDK within an activity or fragment.
- Include the
Place.Field.PHOTO_METADATAS
in the field list of the place details request. - Call
PlacesClient.fetchPlace()
to get thePlace
object, andPlace.getPhotoMetadas()
to get thePhotoMetadata
object. The author attributions field is not supported byPlacesClient.findCurrentPlace()
. - Use
PhotoMetadata.getAuthorAttributions()
to get author attributions.
Get a photo
This section describes how to retrieve a photo as a bitmap or as a URI.
Get a place photo as a bitmap
The following example demonstrates getting a place photo as a bitmap.
Kotlin
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify fields. Requests for photos must always have the PHOTO_METADATAS field. val fields = listOf(Place.Field.PHOTO_METADATAS) // Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace()) val placeRequest = FetchPlaceRequest.newInstance(placeId, fields) placesClient.fetchPlace(placeRequest) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place // Get the photo metadata. val metada = place.photoMetadatas if (metada == null || metada.isEmpty()) { Log.w(TAG, "No photo metadata.") return@addOnSuccessListener } val photoMetadata = metada.first() // Get the attribution text. val attributions = photoMetadata?.attributions // Create a FetchPhotoRequest. val photoRequest = FetchPhotoRequest.builder(photoMetadata) .setMaxWidth(500) // Optional. .setMaxHeight(300) // Optional. .build() placesClient.fetchPhoto(photoRequest) .addOnSuccessListener { fetchPhotoResponse: FetchPhotoResponse -> val bitmap = fetchPhotoResponse.bitmap imageView.setImageBitmap(bitmap) }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { Log.e(TAG, "Place not found: " + exception.message) val statusCode = exception.statusCode TODO("Handle error with given status code.") } } }
Java
// Define a Place ID. final String placeId = "INSERT_PLACE_ID_HERE"; // Specify fields. Requests for photos must always have the PHOTO_METADATAS field. final List<Place.Field> fields = Collections.singletonList(Place.Field.PHOTO_METADATAS); // Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace()) final FetchPlaceRequest placeRequest = FetchPlaceRequest.newInstance(placeId, fields); placesClient.fetchPlace(placeRequest).addOnSuccessListener((response) -> { final Place place = response.getPlace(); // Get the photo metadata. final List<PhotoMetadata> metadata = place.getPhotoMetadatas(); if (metadata == null || metadata.isEmpty()) { Log.w(TAG, "No photo metadata."); return; } final PhotoMetadata photoMetadata = metadata.get(0); // Get the attribution text. final String attributions = photoMetadata.getAttributions(); // Create a FetchPhotoRequest. final FetchPhotoRequest photoRequest = FetchPhotoRequest.builder(photoMetadata) .setMaxWidth(500) // Optional. .setMaxHeight(300) // Optional. .build(); placesClient.fetchPhoto(photoRequest).addOnSuccessListener((fetchPhotoResponse) -> { Bitmap bitmap = fetchPhotoResponse.getBitmap(); imageView.setImageBitmap(bitmap); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } }); });
Get a place photo URI
The following example demonstrates getting a place photo URI.
// Define a Place ID. final String placeId = "INSERT_PLACE_ID_HERE"; // Specify fields. Requests for photos must always have the PHOTO_METADATAS field. final List<Place.Field> fields = Collections.singletonList(Place.Field.PHOTO_METADATAS); // Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace()) final FetchPlaceRequest placeRequest = FetchPlaceRequest.newInstance(placeId, fields); placesClient.fetchPlace(placeRequest).addOnSuccessListener((response) -> { final Place place = response.getPlace(); // Get the photo metadata. final List<PhotoMetadata> metadata = place.getPhotoMetadatas(); if (metadata == null || metadata.isEmpty()) { Log.w(TAG, "No photo metadata."); return; } final PhotoMetadata photoMetadata = metadata.get(0); // Get the attribution text. final String attributions = photoMetadata.getAttributions(); // Create a FetchResolvedPhotoUriRequest. final FetchResolvedPhotoUriRequest photoRequest = FetchResolvedPhotoUriRequest.builder(photoMetadata) .setMaxWidth(500) // Optional. .setMaxHeight(300) // Optional. .build(); // Request the photo URI placesClient.fetchResolvedPhotoUri(photoRequest).addOnSuccessListener((fetchResolvedPhotoUriResponse) -> { Uri uri = fetchResolvedPhotoUriResponse.getUri(); RequestOptions requestOptions = new RequestOptions().override(Target.SIZE_ORIGINAL); Glide.with(this).load(uri).apply(requestOptions).into(imageView); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } }); });
Attributions
In most cases, place photos can be used without attribution, or will have
the required attribution included as part of the image. However, the photo metadata object, of type
PhotoMetadata
,
can contain either of two types of additional attributions:
- Attributions, an attribution string accessed by
PhotoMetadata.getAttributions()
. - AuthorAttributions, an
AuthorAttributions
object accessed byPhotoMetadata.getAuthorAttributions()
.
If the returned PhotoMetadata
object includes either type of attribution, you must
include the attribution in your application wherever you display the image. For more information,
see Displaying Attributions.
Usage and billing
A Places Photo SKU is charged for calls to fetchPhoto()
.
See the Usage and Billing page for details.