Places SDK for Android 為應用程式提供豐富的地點相關資訊,包括地點的名稱和地址、經緯度座標指定的地理位置,以及地點類型 (例如夜店、寵物店、博物館等)。如要存取特定地點的這項資訊,可以使用地點 ID,這是可唯一識別地點的固定 ID。
地點詳細資訊
Place
物件可提供特定地點的相關資訊。您可以透過下列方式保留 Place
物件:
- 呼叫
PlacesClient.fetchPlace()
:請參閱「透過 ID 取得地點」指南。 - 呼叫
PlacesClient.findCurrentPlace()
– 請參閱取得目前地點指南。
提出地點要求時,您必須指定要傳回的地點資料。方法是傳送 Place.Field 值清單,指定要傳回的資料。由於這份清單會影響每次要求的費用,因此相當重要。
地點資料結果不可為空白,因此系統只會傳回含有資料的地點結果 (例如,如果要求的地點沒有相片,結果中就不會顯示 photos
欄位)。
以下範例會傳遞三個 Place.Field 值的清單,指定要求傳回的資料:
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Java
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
存取地點物件資料欄位
取得 Place
物件後,請使用物件的方法存取要求中指定的資料欄位。如果 Place
物件中缺少該欄位,相關方法會傳回空值。以下列舉幾個可用方法的範例。如需所有方法的完整清單,請參閱 Place
API 參考資料。
getAddress()
:地點的地址 (清楚易懂的格式)。getAddressComponents()
– 這個地點的地址元件List
。這些元件是用於擷取地點地址的結構化資訊,例如尋找地點所在的城市。請勿使用這些元件設定地址格式,請改為呼叫getAddress()
,以取得本地化格式的地址。getId()
:地點的文字 ID。請參閱本頁面其餘部分,進一步瞭解地點 ID。getLatLng()
:地點的地理位置,以經緯度座標的形式指定。getName()
- 地點的名稱。getOpeningHours()
:地點的OpeningHours
。呼叫OpeningHours.getWeekdayText()
即可傳回字串清單,代表一週內每天的營業時間和打烊時間。呼叫OpeningHours.getPeriods()
可傳回period
物件清單,其中包含更詳細的資訊,等同於getWeekdayText()
提供的資料。Place
物件還包含getCurrentOpeningHours()
方法,會傳回未來七天內的地點營業時間;而getSecondaryOpeningHours()
,則會傳回地點未來七天內的次要營業時間。isOpen()
:表示地點目前營業的布林值。如果沒有指定時間,目前為預設值。只有在Place.Field.UTC_OFFSET
和Place.Field.OPENING_HOURS
都可用時,系統才會傳回isOpen
。為確保結果正確無誤,請在原始地點要求中要求Place.Field.BUSINESS_STATUS
和Place.Field.UTC_OFFSET
欄位。如未要求,系統會假設商家確實正常運作。如要瞭解如何搭配 Place Details 使用isOpen
,請觀看這部影片。
以下是一些簡單的範例:
Kotlin
val name = place.name val address = place.address val location = place.latLng
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
存取 3.3.0 版中新增的地點資料
Places SDK for Android 3.3.0 版新增資料至 Place
:
- 地點類型:與地點相關聯的新類型值。
- 評論:地點最多五則評論。
- 名稱語言代碼:地點名稱的語言代碼。
以下各節將說明如何存取這項新資料。
存取新的地點類型
每個地點都可以有一或多個相關聯的 type 值。Places SDK for Android 3.3.0 版新增了許多類型值。如需完整清單,請參閱「展開的地點類型」一文。
在 Places SDK for Android 3.2.0 以下版本中,您可以使用 Place.getTypes()
方法存取與地點相關聯的類型值。Place.getTypes()
會以 Place.Types
定義的列舉值傳回類型清單。
Place.getPlaceTypes()
方法會以字串值清單的形式傳回類型值。傳回的值取決於您的 Places SDK for Android 版本:
- Places SDK for Android (新推出):傳回由地點類型 (New) 上顯示的表格 A 和表格 B 所定義的字串,包括 3.3.0 版中新增的所有地點類型。
- Places SDK for Android:傳回
Place.Types
定義的列舉,但其中不包含 3.3.0 版中新增的新類型。
如要瞭解兩個 SDK 版本之間的主要差異,請參閱「選擇 SDK 版本」。
存取地點評論
Places SDK for Android (新版) 新增 Review
類別,其中包含地點的評論。Place
物件最多可包含五則評論。
Review
類別也可以包含作者資訊和作者作者資訊。如果您在應用程式中顯示評論,則必須一併顯示任何作者資訊或作者資訊。詳情請參閱「顯示評論」一文。
如要在 Place
物件中填入評論,您必須:
- 在設定 Google Cloud 專案時啟用新的 SDK。
- 在活動或片段中初始化新的 SDK。
- 在 Place Details 要求的欄位清單中加入
Place.Field.REVIEWS
。 - 呼叫
PlacesClient.fetchPlace()
。 「PlacesClient.findCurrentPlace()
」不支援評論欄位。 - 使用
Place.getReviews()
方法存取Place
物件中的評論資料欄位。
存取地點名稱語言代碼
現有的 Place.getName()
方法會傳回包含地點名稱的文字字串。如要在 Place
物件中填入地點名稱,您必須在 Place Details 要求的欄位清單中加入 Place.Field.NAME
。
Place
物件現在包含名稱字串的語言代碼。如要在 Place
物件中填入語言代碼,您必須:
- 在設定 Google Cloud 專案時啟用新的 SDK。
- 在活動或片段中初始化新的 SDK。
- 在要求的欄位清單中加入
Place.Field.NAME
。這個值會將回應設為在Place
物件中納入地點名稱和語言代碼。 - 呼叫
PlacesClient.fetchPlace()
。PlacesClient.findCurrentPlace()
不支援語言代碼欄位。 - 使用
Place.getNameLanguageCode()
方法存取Place
物件中的語言代碼欄位。
在 3.3.0 版中設定區碼
Places SDK for Android (新版) 會將區碼要求參數新增至 Place Details。區碼是用來設定回應的格式,指定為 雙字元 CLDR 代碼值。這個參數也會對搜尋結果產生偏誤。 沒有預設值。您必須啟用新的 SDK 才能設定區碼。
如果回應中地址欄位的國家/地區名稱與區碼相符,系統就會省略地址中的國家/地區代碼。
多數 CLDR 代碼與 ISO 3166-1 代碼相同,只有少數例外。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而 ISO 3166-1 代碼卻是「gb」(正式的國名為「大不列顛暨北愛爾蘭聯合王國」)。這個參數可根據適用法律影響結果。
透過 ID 取得地點
地點 ID 是用來識別特定地點的文字 ID,在 Places SDK for Android 中,您可以呼叫 Place.getId()
來擷取地點 ID。Place Autocomplete 服務也會針對與所提供搜尋查詢和篩選器相符的每個地點,傳回地點 ID。您可以儲存地點 ID,日後再用於擷取 Place
物件。
如要依據 ID 取得地點,請呼叫 PlacesClient.fetchPlace()
並傳遞 FetchPlaceRequest
。
API 會在 Task
中傳回 FetchPlaceResponse
。FetchPlaceResponse
包含與提供地點 ID 相符的 Place
物件。
以下程式碼範例說明如何呼叫 fetchPlace()
以取得指定地點的詳細資料。
Kotlin
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify the fields to return. val placeFields = listOf(Place.Field.ID, Place.Field.NAME) // Construct a request object, passing the place ID and fields array. val request = FetchPlaceRequest.newInstance(placeId, placeFields) placesClient.fetchPlace(request) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}") }.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 the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Construct a request object, passing the place ID and fields array. final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); placesClient.fetchPlace(request).addOnSuccessListener((response) -> { Place place = response.getPlace(); Log.i(TAG, "Place found: " + place.getName()); }).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. } });
取得營業狀態
PlacesClient.isOpen(IsOpenRequest request)
方法會傳回 IsOpenResponse
物件,根據呼叫中指定的時間,指出地點目前是否營業中。
這個方法使用 IsOpenRequest
類型的單一引數,其中包含:
Place
物件,或指定地點 ID 的字串。- 選用的時間值,用於指定 1970-01-01T00:00:00Z 開始的時間 (以毫秒為單位)。如果沒有指定時間,目前為預設值。
如要使用這個方法,Place
物件中必須有下列欄位:
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
如果 Place
物件中未提供這些欄位,或是您傳遞地點 ID,此方法會使用 PlacesClient.fetchPlace()
擷取這些欄位。如要進一步瞭解如何建立包含必要欄位的 Place 物件,請參閱 Place Details。
以下範例可判斷地點是否正在營業。在這個範例中,您只將地點 ID 傳遞至 isOpen()
:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> isOpen = response.isOpen()); // ...
下一個範例顯示呼叫 isOpen()
的位置,也就是您傳遞 Place
物件。Place
物件必須包含有效的地點 ID:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" // Specify the required fields for an isOpen request. val placeFields: List<Place.Field> = listOf( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET ) val placeRequest: FetchPlaceRequest = FetchPlaceRequest.newInstance(placeId, placeFields) val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest) placeTask.addOnSuccessListener { placeResponse -> place = placeResponse.place val isOpenRequest: IsOpenRequest = try { IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = isOpenResponse.isOpen } // ... } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; // Specify the required fields for an isOpen request. List<Place.Field> placeFields = new ArrayList<>(Arrays.asList( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET )); FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request); placeTask.addOnSuccessListener( (placeResponse) -> { Place place = placeResponse.getPlace(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> isOpen = isOpenResponse.isOpen()); // ... }); // ...
在應用程式中顯示歸因資訊
當應用程式顯示地點資訊 (包括地點評論) 時,應用程式也必須顯示任何作者資訊。詳情請參閱「歸因」一文。
進一步瞭解地點 ID
Places SDK for Android 中使用的地點 ID 與 Places API 中使用的 ID 相同。每個地點 ID 只能對應一個地點,但一個地點可以有多個地點 ID。在其他情況下,系統可能會導致地點取得新的地點 ID。舉例來說,如果商家搬遷至新地點,就可能發生這種情況。
透過指定地點 ID 要求地點時,您可以放心,回應中一律會收到相同的地點 (如果地點仍然存在)。不過請注意,回應中可能包含的地點 ID 與要求中的地點 ID 不同。
詳情請參閱地點 ID 總覽。