รายละเอียดสถานที่

Places SDK สำหรับ Android จะให้ข้อมูลที่สมบูรณ์เกี่ยวกับสถานที่ต่างๆ แก่แอปของคุณ ซึ่งรวมถึงชื่อและที่อยู่ของสถานที่ทางภูมิศาสตร์ ซึ่งระบุเป็นพิกัดละติจูด/ลองจิจูด ประเภทสถานที่ (เช่น ไนท์คลับ ร้านสัตว์เลี้ยง พิพิธภัณฑ์) และอื่นๆ หากต้องการเข้าถึงข้อมูลนี้สำหรับสถานที่หนึ่งๆ คุณสามารถใช้รหัสสถานที่ ซึ่งเป็นตัวระบุคงที่ที่ระบุสถานที่ได้แบบไม่ซ้ำกัน

รายละเอียดสถานที่

ออบเจ็กต์ Place ให้ข้อมูลเกี่ยวกับสถานที่ที่เฉพาะเจาะจง คุณจะรับออบเจ็กต์ Place ได้ด้วยวิธีต่อไปนี้

• โทร PlacesClient.fetchPlace() – ดูคำแนะนำในการรับสถานที่โดยใช้รหัส
• โทร PlacesClient.findCurrentPlace() – ดูคำแนะนำในการรับข้อมูลสถานที่ปัจจุบัน

เมื่อคุณส่งคำขอข้อมูลสถานที่ คุณต้องระบุข้อมูลสถานที่ที่จะส่งคืน หากต้องการทำเช่นนี้ ให้ส่งรายการค่า Place.Field ซึ่งระบุข้อมูลที่จะแสดง รายการนี้เป็นสิ่งสำคัญที่ควรพิจารณาเนื่องจากมีผลต่อค่าใช้จ่ายสำหรับคำขอแต่ละรายการ

เนื่องจากผลลัพธ์ของข้อมูลสถานที่ต้องไม่ว่างเปล่า โดยจะแสดงผลลัพธ์เฉพาะสถานที่ที่มีข้อมูลเท่านั้น (ตัวอย่างเช่น หากสถานที่ที่ขอไม่มีรูปภาพ ช่อง photos จะไม่ปรากฏในผลลัพธ์)

ตัวอย่างต่อไปนี้ส่งรายการค่า Place.Field จำนวน 3 ค่าเพื่อระบุข้อมูลที่ส่งกลับมาโดยคำขอ

// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)

// Specify the fields to return.
final List placeFields = 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 พร้อมรายละเอียดสถานที่ได้จากวิดีโอนี้

ตัวอย่างง่ายๆ:

val name = place.name
val address = place.address
val location = place.latLng

      

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 คุณต้องดำเนินการต่อไปนี้

1. เปิดใช้ SDK ใหม่เมื่อคุณตั้งค่าโปรเจ็กต์ Google Cloud
2. เริ่มต้น SDK ใหม่ภายในกิจกรรมหรือส่วนย่อย
3. ใส่ Place.Field.REVIEWS ในรายการฟิลด์ของคำขอรายละเอียดสถานที่
4. โทร PlacesClient.fetchPlace() PlacesClient.findCurrentPlace() ไม่รองรับช่องรีวิว
5. ใช้เมธอด Place.getReviews() เพื่อเข้าถึงช่องข้อมูลรีวิวในออบเจ็กต์ Place

เข้าถึงรหัสภาษาของชื่อสถานที่

เมธอด Place.getName() ที่มีอยู่จะแสดงผลสตริงข้อความที่มีชื่อของสถานที่ หากต้องการเติมข้อมูลออบเจ็กต์ Place ด้วยชื่อสถานที่ คุณต้องใส่ Place.Field.NAME ในรายการช่องของคำขอรายละเอียดสถานที่

ตอนนี้ออบเจ็กต์ Place มีรหัสภาษาสำหรับสตริงชื่อแล้ว หากต้องการเติมข้อมูลออบเจ็กต์ Place ด้วยรหัสภาษา คุณต้องทำดังนี้

1. เปิดใช้ SDK ใหม่เมื่อคุณตั้งค่าโปรเจ็กต์ Google Cloud
2. เริ่มต้น SDK ใหม่ภายในกิจกรรมหรือส่วนย่อย
3. ระบุ Place.Field.NAME ในรายการช่องของคำขอ ค่านี้กำหนดค่าการตอบกลับให้มีทั้งชื่อสถานที่และรหัสภาษาในออบเจ็กต์ Place
4. โทร PlacesClient.fetchPlace() PlacesClient.findCurrentPlace() ไม่รองรับช่องรหัสภาษา
5. ใช้เมธอด 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() เพื่อรับรายละเอียดเกี่ยวกับสถานที่ที่ระบุ

// 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")
        }
    }

      

// 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() เท่านั้น

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
}
// ...

      

@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 ต้องมีรหัสสถานที่ที่ถูกต้อง:

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
    }
    // ...
}
// ...

      

@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 รหัส มีสถานการณ์อื่นๆ ที่อาจทำให้สถานที่ได้รับรหัสสถานที่ใหม่ ตัวอย่างเช่น กรณีนี้อาจเกิดขึ้นหากธุรกิจย้ายไปยัง สถานที่ใหม่

เมื่อคุณขอสถานที่ด้วยการระบุรหัสสถานที่ คุณสามารถมั่นใจได้ว่าจะได้รับสถานที่เดิมในการตอบกลับเสมอ (หากสถานที่ยังคงมีอยู่) อย่างไรก็ตาม โปรดทราบว่าการตอบกลับอาจมีรหัสสถานที่ที่แตกต่างจากในคำขอของคุณ

ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมรหัสสถานที่