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
ให้ใช้เมธอดของออบเจ็กต์เพื่อเข้าถึงช่องข้อมูลที่ระบุในคำขอ หากช่องดังกล่าวขาดหายไปจากออบเจ็กต์ 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();
เพิ่มการเข้าถึงข้อมูล Place ในเวอร์ชัน 3.3.0
Places SDK สำหรับ Android เวอร์ชัน 3.3.0 จะเพิ่มข้อมูลใหม่ไปยัง Place
:
- ประเภทสถานที่: ค่าประเภทใหม่ที่เชื่อมโยงกับสถานที่
- รีวิว: รีวิวสูงสุด 5 รายการสำหรับสถานที่หนึ่งๆ
- รหัสภาษาของชื่อ: รหัสภาษาสำหรับชื่อสถานที่
ส่วนต่อไปนี้จะอธิบายวิธีเข้าถึงข้อมูลใหม่นี้
เข้าถึงสถานที่ประเภทใหม่ๆ
แต่ละสถานที่อาจมีค่า 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 สำหรับ Android: แสดงผล Enum ที่
Place.Types
กำหนด ซึ่งไม่รวมประเภทใหม่ที่เพิ่มในเวอร์ชัน 3.3.0
หากต้องการดูความแตกต่างสำคัญระหว่าง SDK ทั้ง 2 เวอร์ชัน โปรดดู เลือกเวอร์ชัน SDK
เข้าถึงรีวิวสถานที่
Places SDK สำหรับ Android (ใหม่) จะเพิ่มคลาส Review
ที่มีรีวิวของสถานที่ ออบเจ็กต์ Place
มีรีวิวได้สูงสุด 5 รายการ
คลาส Review
ยังสามารถมีการระบุแหล่งที่มาและการระบุแหล่งที่มาของผู้เขียนได้อีกด้วย หากแสดงรีวิวในแอป คุณจะต้องแสดงที่มาหรือระบุแหล่งที่มาของผู้เขียนด้วย
สำหรับข้อมูลเพิ่มเติม โปรดดูที่แสดงรีวิว
หากต้องการเติมรีวิวในออบเจ็กต์ Place
คุณต้องดำเนินการต่อไปนี้
- เปิดใช้ SDK ใหม่เมื่อคุณตั้งค่าโปรเจ็กต์ Google Cloud
- เริ่มต้น SDK ใหม่ภายในกิจกรรมหรือส่วนย่อย
- ใส่
Place.Field.REVIEWS
ในรายการฟิลด์ของคำขอรายละเอียดสถานที่ - โทร
PlacesClient.fetchPlace()
PlacesClient.findCurrentPlace()
ไม่รองรับช่องรีวิว - ใช้เมธอด
Place.getReviews()
เพื่อเข้าถึงช่องข้อมูลรีวิวในออบเจ็กต์Place
เข้าถึงรหัสภาษาของชื่อสถานที่
เมธอด Place.getName()
ที่มีอยู่จะแสดงผลสตริงข้อความที่มีชื่อของสถานที่ หากต้องการเติมข้อมูลออบเจ็กต์ Place
ด้วยชื่อสถานที่ คุณต้องใส่ Place.Field.NAME
ในรายการช่องของคำขอรายละเอียดสถานที่
ตอนนี้ออบเจ็กต์ Place
มีรหัสภาษาสำหรับสตริงชื่อแล้ว หากต้องการเติมข้อมูลออบเจ็กต์ Place
ด้วยรหัสภาษา คุณต้องทำดังนี้
- เปิดใช้ SDK ใหม่เมื่อคุณตั้งค่าโปรเจ็กต์ Google Cloud
- เริ่มต้น SDK ใหม่ภายในกิจกรรมหรือส่วนย่อย
- ระบุ
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" (ในทางเทคนิคแล้วสำหรับหน่วยงาน "The United Kingdom of Great Britain and Northern Ireland") พารามิเตอร์ดังกล่าวอาจส่งผลต่อผลลัพธ์ ตามกฎหมายที่เกี่ยวข้องได้
ดูสถานที่โดยใช้รหัส
รหัสสถานที่คือตัวระบุข้อความที่ใช้ระบุสถานที่อย่างไม่ซ้ำกัน คุณจะเรียกข้อมูลรหัสของสถานที่ได้โดยการเรียกใช้ Place.getId()
ใน Places SDK สำหรับ Android
นอกจากนี้ บริการเติมสถานที่อัตโนมัติยังแสดงผลรหัสสถานที่แต่ละแห่งที่ตรงกับคำค้นหาและตัวกรองที่ให้ไว้ด้วย คุณจัดเก็บรหัสสถานที่และใช้รหัสดังกล่าวเพื่อดึงออบเจ็กต์ 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()
เพื่อดึงข้อมูล ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างออบเจ็กต์สถานที่ด้วยช่องที่จำเป็นในรายละเอียดสถานที่
ตัวอย่างต่อไปนี้จะกำหนดว่าสถานที่นั้นๆ เปิดอยู่หรือไม่ ในตัวอย่างนี้ คุณจะส่งผ่านรหัสสถานที่ไปยัง 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 รหัส มีสถานการณ์อื่นๆ ที่อาจทำให้สถานที่ได้รับรหัสสถานที่ใหม่ ตัวอย่างเช่น กรณีนี้อาจเกิดขึ้นหากธุรกิจย้ายไปยัง สถานที่ใหม่
เมื่อคุณขอสถานที่ด้วยการระบุรหัสสถานที่ คุณสามารถมั่นใจได้ว่าจะได้รับสถานที่เดิมในการตอบกลับเสมอ (หากสถานที่ยังคงมีอยู่) อย่างไรก็ตาม โปรดทราบว่าการตอบกลับอาจมีรหัสสถานที่ที่แตกต่างจากในคำขอของคุณ
ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมรหัสสถานที่