地點相片 (新)

選取平台： Android iOS 網路服務

歐洲經濟區 (EEA) 開發人員

如果您的帳單地址位於歐洲經濟區，自 2025 年 7 月 8 日起，使用服務時將適用《 Google 地圖平台歐洲經濟區服務條款》。功能會因區域而異。 瞭解詳情。

「地點相片 (新版)」可讓您在應用程式中加入高品質的相片內容。您可以透過「地點相片」存取地點資料庫中儲存的數百萬張相片。Place Photos 會傳回點陣圖片的 URI。點陣圖圖片大小上限為 4800 x 4800 像素。

注意： Place Photos (New) 適用於 Places SDK for Android 3.4.0 以上版本。詳情請參閱「選擇 SDK 版本」。如要進一步瞭解如何使用 4.0.0 版新增的 Kotlin API，請參閱「參考資料總覽」。

Place Photos 要求

如要擷取地點的圖片，請按照下列步驟操作：

1. 使用地點詳細資料 (新版)，透過 fetchPlace() 擷取 Place 物件。 請務必在要納入回應 Place 物件的欄位清單中，加入 Place.Field PHOTO_METADATAS 欄位。
2. 在 OnSuccessListener 中，針對 FetchPlaceResponse 呼叫 Place.getPhotoMetadas()，從回應 Place 物件取得 PhotoMetadata 類型的相片中繼資料物件。
3. 建立 FetchResolvedPhotoUriRequest 物件來提出要求，並傳遞相片中繼資料物件，以及高度上限、寬度上限或兩者的值。
4. 使用 PlacesClient.fetchResolvedPhotoUri() 要求相片 URI。
5. 新增 OnSuccessListener，並從 FetchResolvedPhotoUriResponse 物件取得相片 URI。

注意：如要進一步瞭解如何初始化 PlacesClient，請參閱「初始化 Places API 用戶端」。

您可以透過 CancellationToken 嘗試取消對任何要求類別的要求 (例如 FetchPlaceRequest)。系統會盡力取消要求。取消要求發出後，系統不會傳回任何回應。 發出取消權杖「無法」保證特定要求會取消，即使未傳回任何回應，您仍可能需要支付要求費用。

必要參數

FetchResolvedPhotoUriRequest 的必要參數如下：

• 相片中繼資料

  要傳回的照片中繼資料物件。

• 最大高度或最大寬度

  指定要傳回的圖片高度和寬度上限 (以像素為單位)。如果圖片小於指定值，系統會傳回原始圖片。如果圖片任一維度較大，系統會縮放圖片，使較小的維度符合限制，並保留原始顯示比例。最大高度和最大寬度屬性都接受介於 1 到 4800 之間的整數。您必須指定高度上限、寬度上限或兩者。

  • 如要設定高度上限參數，請在建構 FetchResolvedPhotoUriRequest 物件時呼叫 setMaxHeight() 方法。
  • 如要設定最大寬度參數，請在建構 FetchResolvedPhotoUriRequest 物件時呼叫 setMaxWidth() 方法。

地點相片範例

以下範例示範如何取得地點相片 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 and author attributions.
    final String attributions = photoMetadata.getAttributions();
    final AuthorAttributions authorAttributions = photoMetadata.getAuthorAttributions();

    // Create a FetchResolvedPhotoUriRequest.
    final FetchResolvedPhotoUriRequest photoRequest = FetchResolvedPhotoUriRequest.builder(photoMetadata)
        .setMaxWidth(500)
        .setMaxHeight(300)
        .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.
        }
    });
});

歸因

在大多數情況下，使用地點相片時可以不包含作者資訊，圖片本身也可能已加入必要的作者資訊。不過，PhotoMetadata 類型的相片中繼資料物件可包含下列任一類型的額外出處資訊：

• 出處：可透過 PhotoMetadata.getAttributions() 存取的出處字串。
• AuthorAttributions，這是透過 PhotoMetadata.getAuthorAttributions() 存取的 AuthorAttributions 物件。

如果傳回的 PhotoMetadata 物件包含任一類型的作者資訊，您每次顯示圖片時就必須在應用程式中加入作者資訊。詳情請參閱「顯示出處資訊」。