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

เลือกแพลตฟอร์ม: Android iOS JavaScript บริการบนเว็บ

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

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

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

เมื่อคุณขอสถานที่ คุณต้องระบุข้อมูลสถานที่ที่จะแสดงคืน ซึ่งทำได้โดยการส่งรายการค่า 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 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 กับรายละเอียดสถานที่ได้จากวิดีโอนี้

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

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 for 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" (ทางเทคนิคสำหรับหน่วยงาน "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ") พารามิเตอร์อาจส่งผลต่อผลลัพธ์โดยขึ้นอยู่กับกฎหมายที่เกี่ยวข้อง

ดูสถานที่โดยใช้รหัส

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

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

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