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

นักพัฒนาแอปในเขตเศรษฐกิจยุโรป (EEA)

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

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

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

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

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

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

Kotlin

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

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);

เข้าถึงฟิลด์ข้อมูลออบเจ็กต์สถานที่

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

  • 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.displayName
        val address = place.formattedAddress
        val location = place.location

Java

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

รับสถานที่ตามรหัส

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

หากต้องการรับสถานที่ตามรหัส ให้เรียกใช้ PlacesClient.fetchPlace() โดยส่ง FetchPlaceRequest

API จะแสดง FetchPlaceResponse ใน Task FetchPlaceResponse มีออบเจ็กต์ Place ที่ตรงกับรหัสสถานที่ที่ระบุ

ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก fetchPlace() เพื่อรับรายละเอียดของสถานที่ที่ระบุ

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

// Specify the fields to return.
val placeFields = listOf(
    Place.Field.ID,
    Place.Field.DISPLAY_NAME,
    Place.Field.FORMATTED_ADDRESS,
    Place.Field.LOCATION
)

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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location, location.latitude, location.longitude
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

// Specify the fields to return.
final List<Place.Field> placeFields =
    Arrays.asList(
            Place.Field.ID,
            Place.Field.DISPLAY_NAME,
            Place.Field.FORMATTED_ADDRESS,
            Place.Field.LOCATION
    );

// 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();

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

    binding.placeName.setText(name);
    binding.placeAddress.setText(address);
    if (location != null) {
        binding.placeLocation.setText(
                getString(R.string.place_location, location.latitude, location.longitude)
        );
    } else {
        binding.placeLocation.setText(null);
    }

    Log.i(TAG, "Place found: " + place.getDisplayName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException apiException) {
        final String message = getString(R.string.place_not_found, apiException.getMessage());
        binding.placeName.setText(message);
        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 หรือหากคุณส่ง Place ID เมธอดจะใช้ PlacesClient.fetchPlace() เพื่อดึงข้อมูล ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างออบเจ็กต์ Place ที่มีฟิลด์ที่จำเป็นได้ที่รายละเอียดสถานที่

ตัวอย่างต่อไปนี้จะตรวจสอบว่าสถานที่เปิดอยู่หรือไม่ ในตัวอย่างนี้ คุณจะส่งเฉพาะรหัสสถานที่ไปยัง isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = PlaceIdProvider.getRandomPlaceId()

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    Log.e("PlaceIsOpen", "Error: " + e.message)
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen ?: false
    binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString())
    Log.d("PlaceIsOpen", "Is open by ID: $isOpen")
}
// ...

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    Log.e("PlaceIsOpen", "Error: " + e.getMessage());
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) -> {
            final boolean isOpen = Boolean.TRUE.equals(response.isOpen());
            binding.isOpenByIdResult.setText(getString(R.string.is_open_by_id, String.valueOf(isOpen)));
            Log.d("PlaceIsOpen", "Is open by ID: " + isOpen);
        });
placeTask.addOnFailureListener((exception) -> {
    binding.isOpenByIdResult.setText(getString(R.string.is_open_by_id, "Error: " + exception.getMessage()));
    Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
});

ตัวอย่างถัดไปแสดงการเรียก isOpen() ที่คุณส่งออบเจ็กต์ Place Place ออบเจ็กต์ต้องมีรหัสสถานที่ที่ถูกต้อง

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = PlaceIdProvider.getRandomPlaceId()
// 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.DISPLAY_NAME
)

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) {
        Log.e("PlaceIsOpen", "Error: " + e.message)
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = when (isOpenResponse.isOpen) {
            true -> getString(R.string.is_open)
            else -> getString(R.string.is_closed)
        }
        binding.isOpenByObjectResult.text = getString(
            R.string.is_open_by_object,
            place.displayName,
            isOpen
        )
        Log.d("PlaceIsOpen", "Is open by object: $isOpen")
    }
    // ...
}
// ...

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
// 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.DISPLAY_NAME
));

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) {
                Log.e("PlaceIsOpen", "Error: " + e.getMessage());
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> {
                        final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen());
                        binding.isOpenByObjectResult.setText(getString(R.string.is_open_by_object, place.getDisplayName(), String.valueOf(isOpen)));
                        Log.d("PlaceIsOpen", "Is open by object: " + isOpen);
                    });
            isOpenTask.addOnFailureListener(
                    (exception) -> { // also update the result text field
                        binding.isOpenByObjectResult.setText(getString(R.string.is_open_by_object, place.getDisplayName(), "Error: " + exception.getMessage()));
                        Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
                    });
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByObjectResult.setText("Error: " + exception.getMessage());
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());

แสดงการระบุแหล่งที่มาในแอป

เมื่อแอปแสดงข้อมูลสถานที่ ซึ่งรวมถึงรีวิวสถานที่ แอปต้องแสดงการระบุแหล่งที่มาด้วย ดูข้อมูลเพิ่มเติมได้ที่ การระบุแหล่งที่มา

ข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่

รหัสสถานที่ที่ใช้ใน Places SDK สำหรับ Android เป็นตัวระบุเดียวกันกับที่ใช้ใน Places API รหัสสถานที่แต่ละรหัสจะอ้างอิงได้เพียงสถานที่เดียว แต่สถานที่เดียวอาจมีรหัสสถานที่มากกว่า 1 รหัส นอกจากนี้ ยังมีสถานการณ์อื่นๆ ที่อาจทำให้สถานที่ได้รับรหัสสถานที่ใหม่ เช่น กรณีที่ธุรกิจย้ายไปสถานที่ใหม่

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

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