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

เลือกแพลตฟอร์ม: 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 เมธอดที่เกี่ยวข้องจะแสดงผลค่า 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 คุณต้องทำดังนี้

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

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

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