地點相片

您可以使用 Places SDK for Android 要求要在應用程式中顯示的地點相片。相片服務傳回的相片取自各種來源,包括業主和使用者提供的相片。

選擇相片格式

Places SDK for Android 支援兩種格式的相片要求:

  • 所有 Places SDK for Android 版本:傳回點陣圖圖片。點陣圖圖片的尺寸上限為 1600 x 1600 像素。
  • Places SDK for Android (New) 3.4 以上版本:傳回點陣圖圖片的 URI。點陣圖圖片的尺寸上限為 4800 x 4800 像素。

相片擷取程序

如要擷取地點圖片,請按照下列步驟操作:

  1. 使用 Place Details 擷取 Place 物件 (使用 fetchPlace()findCurrentPlace())。請務必在欄位清單中加入 Place.Field PHOTO_METADATAS 欄位,以便納入回應 Place 物件。
  2. FetchPlaceResponseFindCurrentPlaceResponseOnSuccessListener 中:
    1. 使用 Place.getPhotoMetadas() 從回應 Place 物件中取得 PhotoMetadata 類型的相片中繼資料物件。
    2. 如何取得點陣圖圖片:
      1. 建立 FetchPhotoRequest 物件,並視需要指定高度和寬度上限 (以像素為單位)。相片的寬度或高度上限為 1600 像素。
      2. 使用 PlacesClient.fetchPhoto() 要求相片點陣圖。
      3. 新增 OnSuccessListener 並從 FetchPhotoResponse 取得相片。
    3. 如要取得相片 URI:
      1. 建立 FetchResolvedPhotoUriRequest 物件來提出要求。相片的寬度或高度上限為 4800 像素。
      2. 使用 PlacesClient.fetchResolvedPhotoUri() 要求相片 URI。
      3. 新增 OnSuccessListener 並從 FetchResolvedPhotoUriResponse 物件取得相片 URI。

存取 3.3.0 以上版本中新增的 PhotoMetadata 資料

Places SDK for Android (新版) 會將 AuthorAttributions 欄位新增至 PhotoMetadata 類別。如果應用程式啟用新 SDK,則 Place.getPhotoMetadas() 傳回的 PhotoMetadata 物件可能包含一或多個作者屬性。

如果 PhotoMetadata 物件包含任何作者資訊 (3.3.0 版中新增的新作者作者資訊,或是 3.2.0 以下版本提供的現有作者資訊),則必須在相片中顯示相關資訊。如要進一步瞭解如何處理所有類型的歸因作業,請參閱「歸因」。

如要將作者姓名填入 PhotoMetadata 物件,您必須:

  1. 設定 Google Cloud 專案時啟用新的 SDK。
  2. 在活動或片段中初始化新的 SDK
  3. 在地點詳細資料要求的欄位清單中加入 Place.Field.PHOTO_METADATAS
  4. 呼叫 PlacesClient.fetchPlace() 取得 Place 物件,並呼叫 Place.getPhotoMetadas() 來取得 PhotoMetadata 物件。PlacesClient.findCurrentPlace() 不支援作者姓名欄位。
  5. 使用 PhotoMetadata.getAuthorAttributions() 取得作者姓名標示。

取得相片

本節說明如何以點陣圖或 URI 格式擷取相片。

取得地點相片做為點陣圖

下例示範如何取得地點相片做為點陣圖。

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.
        }
    });
});

      

取得地點相片 URI

下例示範如何取得地點相片 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.
        }
    });
});

出處

在大多數情況下,地點相片可以在沒有作者資訊的情況下使用,圖片中也會顯示必要的作者資訊。不過,PhotoMetadata 類型的相片中繼資料物件可包含下列兩種其他作者資訊:

如果傳回的 PhotoMetadata 物件包含上述任一作者資訊,則無論如何,您都必須在應用程式中加入作者資訊。如需更多資訊,請參閱「顯示作者資訊」。

用量與計費

呼叫 fetchPhoto() 時,系統會視為「地點相片」SKU 來計費。詳情請參閱「用量與計費」頁面。