Places SDK สำหรับ Android ให้ข้อมูลเกี่ยวกับสถานที่ต่างๆ แก่แอป ซึ่งรวมถึงชื่อและที่อยู่ของสถานที่ สถานที่ตั้งทางภูมิศาสตร์ที่ระบุเป็นพิกัดละติจูด/ลองจิจูด ประเภทสถานที่ (เช่น ไนท์คลับ ร้านสัตว์เลี้ยง พิพิธภัณฑ์) และอื่นๆ หากต้องการเข้าถึงข้อมูลนี้สำหรับสถานที่หนึ่งๆ คุณสามารถใช้รหัสสถานที่ ซึ่งเป็นตัวระบุแบบคงที่ที่ระบุสถานที่โดยไม่ซ้ำกัน
รายละเอียดสถานที่
ออบเจ็กต์ Place
ให้ข้อมูลเกี่ยวกับสถานที่ที่เจาะจง คุณรับออบเจ็กต์ Place
ได้ด้วยวิธีต่อไปนี้
- โทร
PlacesClient.fetchPlace()
– ดูคำแนะนำในการค้นหาสถานที่ผ่านบัตรประจำตัว - โทร
PlacesClient.findCurrentPlace()
– ดูคำแนะนำในการรับข้อมูลสถานที่ปัจจุบัน
เมื่อคุณขอสถานที่ คุณต้องระบุข้อมูลสถานที่ที่ต้องการส่งคืน หากต้องการทำเช่นนี้ ให้ส่งรายการค่า Place.Field ซึ่งระบุข้อมูลที่ต้องการส่งคืน รายการนี้เป็นสิ่งสำคัญที่ควรพิจารณาเนื่องจากมีผลต่อค่าใช้จ่ายสำหรับแต่ละคำขอ
เนื่องจากผลลัพธ์ข้อมูลสถานที่ต้องไม่ว่างเปล่า และระบบจะส่งคืนเฉพาะผลลัพธ์สถานที่ที่มีข้อมูลเท่านั้น (เช่น หากสถานที่ที่ขอไม่มีรูปภาพ ช่อง photos
จะไม่ปรากฏในผลการค้นหา)
ตัวอย่างต่อไปนี้ส่งรายการค่า Place.Field จำนวน 3 ค่าเพื่อระบุข้อมูลที่ส่งกลับมาโดยคำขอ
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
เมธอดที่เกี่ยวข้องจะแสดงผลค่า Null ด้านล่างนี้เป็นตัวอย่างของวิธีการที่ใช้งานได้
ดูรายการเมธอดทั้งหมดได้ที่เอกสารอ้างอิง API ของ Place
getAddress()
– ที่อยู่ของสถานที่ในรูปแบบที่มนุษย์อ่านได้getAddressComponents()
–List
ของคอมโพเนนต์ที่อยู่สำหรับสถานที่นี้ องค์ประกอบเหล่านี้มีไว้เพื่อวัตถุประสงค์ในการดึงข้อมูลที่มีโครงสร้างเกี่ยวกับที่อยู่ของสถานที่ เช่น การค้นหาเมืองที่สถานที่ตั้งอยู่ อย่าใช้คอมโพเนนต์เหล่านี้ในการจัดรูปแบบที่อยู่ แต่ให้เรียกใช้getAddress()
ซึ่งให้ที่อยู่ที่จัดรูปแบบแล้วgetId()
– ตัวระบุข้อความของสถานที่ อ่านเพิ่มเติมเกี่ยวกับรหัสสถานที่ในส่วนอื่นๆ ของหน้านี้getLatLng()
– สถานที่ตั้งทางภูมิศาสตร์ของสถานที่ ระบุเป็นพิกัดละติจูดและลองจิจูดgetName()
– ชื่อสถานที่getOpeningHours()
–OpeningHours
ของสถานที่นี้ เรียกใช้OpeningHours.getWeekdayText()
เพื่อแสดงผลรายการสตริงที่แสดงเวลาเปิดและปิดของแต่ละวันของสัปดาห์ เรียกใช้OpeningHours.getPeriods()
เพื่อแสดงผลรายการออบเจ็กต์period
รายการพร้อมรายละเอียดเพิ่มเติมซึ่งเทียบเท่ากับข้อมูลโดยgetWeekdayText()
นอกจากนี้ ออบเจ็กต์
Place
ยังมีเมธอดgetCurrentOpeningHours()
ซึ่งแสดงผลเวลาทำการของสถานที่ในช่วง 7 วันข้างหน้าด้วย และgetSecondaryOpeningHours()
ที่แสดงเวลาทำการรองของสถานที่ในช่วง 7 วันข้างหน้าisOpen()
– บูลีนที่ระบุว่าสถานที่นี้เปิดอยู่หรือไม่ หากไม่ได้ระบุเวลา ค่าเริ่มต้นจะเป็นตอนนี้ ระบบจะแสดงผลisOpen
ในกรณีที่ทั้งPlace.Field.UTC_OFFSET
และPlace.Field.OPENING_HOURS
พร้อมใช้งานเท่านั้น ขอช่องPlace.Field.BUSINESS_STATUS
และPlace.Field.UTC_OFFSET
ในคำขอตำแหน่งเดิมเพื่อรับประกันผลลัพธ์ที่ถูกต้อง หากไม่ได้ส่งคำขอ ระบบจะถือว่าธุรกิจดำเนินกิจการอยู่ ดูวิธีใช้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 สำหรับ Android เวอร์ชัน 3.3.0 จะเพิ่มข้อมูลใหม่ไปยัง Place
:
- ประเภทสถานที่: ค่าประเภทใหม่ที่เชื่อมโยงกับสถานที่
- รีวิว: รีวิวสูงสุด 5 รายการสำหรับสถานที่หนึ่งๆ
- รหัสภาษาของชื่อ: รหัสภาษาสำหรับชื่อสถานที่
คุณต้องเปิดใช้งาน Places SDK สำหรับ Android (ใหม่) เพื่อเข้าถึงข้อมูลนี้ หากต้องการเรียนรู้ความแตกต่างสำคัญระหว่าง SDK ทั้ง 2 เวอร์ชัน โปรดดูเลือกเวอร์ชัน SDK ของคุณ
ส่วนต่อไปนี้จะอธิบายวิธีเข้าถึงข้อมูลใหม่นี้
เข้าถึงสถานที่ประเภทใหม่ๆ
แต่ละสถานที่อาจมีค่า type อย่างน้อย 1 ค่าที่เชื่อมโยงอยู่ Places SDK สำหรับ Android เวอร์ชัน 3.3.0 เพิ่มค่าประเภทใหม่ๆ มากมาย หากต้องการดูรายการทั้งหมด โปรดดูประเภทสถานที่ที่ขยาย
ใน Places SDK สำหรับ Android เวอร์ชัน 3.2.0 และเวอร์ชันก่อนหน้า คุณใช้เมธอด Place.getTypes()
เพื่อเข้าถึงค่าประเภทที่เชื่อมโยงกับสถานที่ Place.getTypes()
จะแสดงผลรายการประเภทเป็นค่า enum ที่กำหนดโดย Place.Types
เมธอด Place.getPlaceTypes()
จะแสดงผลค่าประเภทเป็นรายการของค่าสตริง ค่าที่แสดงผลจะขึ้นอยู่กับเวอร์ชัน
ของ Places SDK สำหรับ Android ดังนี้
- Places SDK สำหรับ Android (ใหม่): แสดงผลสตริงที่กำหนดโดยตาราง A และตาราง B ซึ่งแสดงในประเภทสถานที่ (ใหม่) รวมถึงประเภทสถานที่ที่เพิ่มไว้ทั้งหมดที่เพิ่มไว้ในเวอร์ชัน 3.3.0
- Places SDK for Android: แสดงผล Enum ที่กำหนดโดย
Place.Types
ซึ่งไม่รวมประเภทใหม่ที่เพิ่มในเวอร์ชัน 3.3.0
ดูความแตกต่างที่สําคัญระหว่าง SDK ทั้ง 2 เวอร์ชันได้ที่ เลือกเวอร์ชัน SDK ของคุณ
เข้าถึงรีวิวสถานที่
Places SDK สำหรับ Android (ใหม่) เพิ่มคลาส Review
ที่มีรีวิวสถานที่ ออบเจ็กต์ Place
มีรีวิวได้สูงสุด 5 รายการ
คลาส Review
ยังสามารถมีการระบุแหล่งที่มาและการระบุแหล่งที่มาผู้เขียน หากแสดงรีวิวในแอป คุณก็ต้องแสดงการระบุแหล่งที่มาหรือการระบุแหล่งที่มาของผู้เขียนด้วย
สำหรับข้อมูลเพิ่มเติม โปรดดูแสดงรีวิว
หากต้องการเพิ่มรีวิวในออบเจ็กต์ Place
คุณต้องทำดังนี้
- เปิดใช้ SDK ใหม่เมื่อตั้งค่าโปรเจ็กต์ Google Cloud
- เริ่มต้น SDK ใหม่ภายในกิจกรรมหรือ Fragment
- ใส่
Place.Field.REVIEWS
ในรายการช่องของคำขอรายละเอียดสถานที่ - โทร
PlacesClient.fetchPlace()
PlacesClient.findCurrentPlace()
ไม่รองรับช่องรีวิว - ใช้เมธอด
Place.getReviews()
เพื่อเข้าถึงช่องข้อมูลรีวิวในออบเจ็กต์Place
เข้าถึงรหัสภาษาของชื่อสถานที่
เมธอด Place.getName()
ที่มีอยู่จะแสดงผลสตริงข้อความที่มีชื่อของสถานที่ หากต้องการเติมข้อมูลออบเจ็กต์ Place
ด้วยชื่อสถานที่ คุณต้องใส่ Place.Field.NAME
ในรายการช่องของคำขอรายละเอียดสถานที่
ตอนนี้ออบเจ็กต์ Place
มีรหัสภาษาสำหรับสตริงชื่อ หากต้องการใส่รหัสภาษาในออบเจ็กต์ Place
คุณต้องดำเนินการต่อไปนี้
- เปิดใช้ SDK ใหม่เมื่อตั้งค่าโปรเจ็กต์ Google Cloud
- เริ่มต้น SDK ใหม่ภายในกิจกรรมหรือ Fragment
- ใส่
Place.Field.NAME
ไว้ในรายการช่องของคำขอ ค่านี้จะกำหนดค่าการตอบสนองให้รวมชื่อสถานที่และรหัสภาษาในออบเจ็กต์Place
- โทร
PlacesClient.fetchPlace()
PlacesClient.findCurrentPlace()
ไม่รองรับช่องรหัสภาษา - ใช้เมธอด
Place.getNameLanguageCode()
เพื่อเข้าถึงช่องรหัสภาษาในออบเจ็กต์Place
ตั้งค่ารหัสภูมิภาคในเวอร์ชัน 3.3.0
Places SDK สำหรับ Android (ใหม่) จะเพิ่มพารามิเตอร์คำขอรหัสภูมิภาคลงในรายละเอียดสถานที่ ระบบใช้รหัสภูมิภาคเพื่อจัดรูปแบบการตอบกลับ ซึ่งระบุเป็นค่า รหัส CLDR ที่มี 2 อักขระ พารามิเตอร์นี้อาจทำให้เกิดการให้น้ำหนักพิเศษกับผลการค้นหาได้เช่นกัน ไม่มีค่าเริ่มต้น คุณต้องเปิดใช้ SDK ใหม่เพื่อตั้งค่ารหัสภูมิภาค
หากชื่อประเทศของช่องที่อยู่ในคำตอบตรงกับรหัสภูมิภาค รหัสประเทศจะไม่แสดงในที่อยู่
รหัส CLDR ส่วนใหญ่เหมือนกับรหัส ISO 3166-1 แต่มีข้อยกเว้นบางประการที่สำคัญ ตัวอย่างเช่น ccTLD ของสหราชอาณาจักรคือ "uk" (.co.uk) ส่วนรหัส ISO 3166-1 คือ "gb" (ในทางเทคนิคแล้วสำหรับเอนทิตี "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ") พารามิเตอร์นี้อาจส่งผลต่อ ผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง
ดูสถานที่โดยใช้รหัส
รหัสสถานที่คือตัวระบุแบบข้อความที่ระบุสถานที่อย่างไม่ซ้ำกัน ใน Places SDK สำหรับ Android คุณจะเรียกดูรหัสของสถานที่ได้โดยการเรียกใช้ Place.getId()
บริการเติมข้อความอัตโนมัติยังแสดงผลรหัสสถานที่สำหรับแต่ละสถานที่ที่ตรงกับคำค้นหาและตัวกรองที่ระบุด้วย คุณจัดเก็บรหัสสถานที่และใช้รหัสดังกล่าวเพื่อเรียกข้อมูลออบเจ็กต์ Place
อีกครั้งในภายหลังได้
หากต้องการไปยังสถานที่ด้วยรหัส ให้โทรหา PlacesClient.fetchPlace()
ผ่าน FetchPlaceRequest
API แสดงผล FetchPlaceResponse
ใน Task
FetchPlaceResponse
มีออบเจ็กต์ 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
หรือสตริงที่ระบุรหัสสถานที่ - ค่าเวลาที่ไม่บังคับซึ่งระบุเวลาเป็นมิลลิวินาทีจาก 1970-01-01T00:00:00Z หากไม่ได้ระบุเวลา ค่าเริ่มต้นจะเป็นตอนนี้
วิธีนี้กำหนดให้ต้องมีช่องต่อไปนี้ในออบเจ็กต์ Place
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
หากไม่มีช่องเหล่านี้อยู่ในออบเจ็กต์ Place
หรือหากคุณส่งรหัสสถานที่ เมธอดจะใช้ PlacesClient.fetchPlace()
เพื่อดึงข้อมูล ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างออบเจ็กต์ Place พร้อมช่องที่จำเป็นได้ที่รายละเอียดสถานที่
ตัวอย่างต่อไปนี้จะกำหนดว่าสถานที่ดังกล่าวเปิดให้บริการหรือไม่ ในตัวอย่างนี้ คุณจะส่งผ่านรหัสสถานที่ไปยัง 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
ต้องมีรหัสสถานที่ที่ถูกต้องดังนี้
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()); // ... }); // ...
แสดงการระบุแหล่งที่มาในแอปของคุณ
เมื่อแอปแสดงข้อมูลสถานที่ ซึ่งรวมถึงรีวิวสถานที่ แอปต้องแสดงที่มาด้วย สำหรับข้อมูลเพิ่มเติม ดูการระบุแหล่งที่มา
ข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่
รหัสสถานที่ที่ใช้ใน Places SDK สำหรับ Android เป็นตัวระบุเดียวกันกับที่ใช้ใน Places API รหัสสถานที่แต่ละรหัสอ้างอิงถึงสถานที่ได้เพียงรายการเดียว แต่สถานที่ 1 แห่งมีรหัสสถานที่ได้มากกว่า 1 รหัส มีกรณีอื่นๆ ที่อาจทำให้สถานที่ได้รับรหัสสถานที่ใหม่ เช่น กรณีนี้อาจเกิดขึ้นหากธุรกิจย้ายไปยังสถานที่ตั้งใหม่
เมื่อคุณขอสถานที่ด้วยการระบุรหัสสถานที่ คุณจะมั่นใจได้ว่าจะได้รับสถานที่เดิมในคำตอบเสมอ (หากสถานที่ดังกล่าวยังคงอยู่) อย่างไรก็ตาม โปรดทราบว่าการตอบกลับอาจมีรหัสสถานที่ที่แตกต่างจากรหัสในคำขอ
ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมรหัสสถานที่