การค้นหาในบริเวณใกล้เคียง (ใหม่)

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

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

โดยค่าเริ่มต้น การตอบกลับจะมีสถานที่ทุกประเภทภายในพื้นที่การค้นหา คุณกรองคำตอบได้โดยระบุรายการประเภทสถานที่ที่จะรวมหรือยกเว้นจากคำตอบอย่างชัดเจน เช่น คุณสามารถระบุให้รวมเฉพาะสถานที่ประเภท "ร้านอาหาร" "เบเกอรี่" และ "คาเฟ่" ไว้ในคำตอบ หรือยกเว้นสถานที่ประเภท "โรงเรียน" ทั้งหมด

คำขอการค้นหาในบริเวณใกล้เคียง (ใหม่)

ส่งคําขอการค้นหาใกล้เคียง (ใหม่) โดยเรียกใช้ PlacesClient.searchNearby โดยส่งออบเจ็กต์ SearchNearbyRequest ที่กําหนดพารามิเตอร์คําขอ

ออบเจ็กต์ SearchNearbyRequest จะระบุพารามิเตอร์ที่จำเป็นและที่ไม่บังคับทั้งหมดสำหรับคำขอ พารามิเตอร์ที่จําเป็น ได้แก่

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

ตัวอย่างคำขอค้นหาในพื้นที่นี้ระบุว่าออบเจ็กต์ Place ของการตอบกลับต้องมีฟิลด์สถานที่ Place.Field.ID และ Place.Field.DISPLAY_NAME สำหรับออบเจ็กต์ Place แต่ละรายการในผลการค้นหา นอกจากนี้ ยังกรองการตอบกลับให้แสดงเฉพาะสถานที่ประเภท "restaurant" และ "cafe" เท่านั้น แต่จะยกเว้นสถานที่ประเภท "pizza_restaurant" และ "american_restaurant"

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

การตอบกลับของผลการค้นหาในบริเวณใกล้เคียง (ใหม่)

คลาส SearchNearbyResponse แสดงการตอบกลับจากคําขอค้นหา ออบเจ็กต์ SearchNearbyResponse ประกอบด้วย

  • รายการออบเจ็กต์ Place ที่แสดงสถานที่ที่ตรงกันทั้งหมด โดยมีออบเจ็กต์ Place 1 รายการต่อสถานที่ที่ตรงกัน
  • ออบเจ็กต์ Place แต่ละรายการจะมีเฉพาะฟิลด์ที่กําหนดโดยรายการฟิลด์ที่ส่งมาในคําขอ

ตัวอย่างเช่น ในคำขอ คุณได้กำหนดรายการช่องเป็น 

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

รายการฟิลด์นี้หมายความว่าออบเจ็กต์ Place แต่ละรายการในการตอบกลับจะมีเฉพาะรหัสสถานที่และชื่อของสถานที่ที่ตรงกันแต่ละแห่ง จากนั้นคุณจะใช้เมธอด Place.getId() และ Place.getName() เพื่อเข้าถึงช่องเหล่านี้ในออบเจ็กต์ Place แต่ละรายการได้

ดูตัวอย่างการเข้าถึงข้อมูลในออบเจ็กต์ Place เพิ่มเติมได้ที่เข้าถึงช่องข้อมูลออบเจ็กต์สถานที่

พารามิเตอร์ที่จำเป็น

ใช้ออบเจ็กต์ SearchNearbyRequest เพื่อระบุพารามิเตอร์ที่จําเป็นสําหรับการค้นหา

  • รายการช่อง

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

    ระบุฟิลด์ต่อไปนี้อย่างน้อย 1 ฟิลด์

    • ฟิลด์ต่อไปนี้จะทริกเกอร์การค้นหาในพื้นที่ใกล้เคียง (พื้นฐาน) SKU

      Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • ฟิลด์ต่อไปนี้จะทริกเกอร์การค้นหาในพื้นที่ (ขั้นสูง) SKU

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI

    • ฟิลด์ต่อไปนี้จะทริกเกอร์การค้นหาในพื้นที่ (แนะนำ) SKU

      Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

    หากต้องการตั้งค่าพารามิเตอร์รายการช่อง ให้เรียกใช้เมธอด setPlaceFields() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

    ตัวอย่างต่อไปนี้กำหนดรายการค่าช่อง 2 รายการเพื่อระบุว่าออบเจ็กต์ Place ที่ส่งคืนโดยคำขอมีช่อง Place.Field.ID และ Place.Field.DISPLAY_NAME

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

  • ข้อจำกัดด้านสถานที่ตั้ง

    ออบเจ็กต์ที่กําหนดขอบเขตการค้นหาที่ระบุเป็นวงกลม ซึ่งกําหนดโดยจุดศูนย์กลางและรัศมีเป็นเมตร LocationRestriction รัศมีต้องมากกว่า 0.0 และน้อยกว่าหรือเท่ากับ 50000.0 โปรดทราบว่าการระบุรัศมีที่เล็กเกินไปจะแสดงผลเป็น ZERO_RESULTS

    หากต้องการตั้งค่าพารามิเตอร์ข้อจํากัดสถานที่ตั้ง ให้เรียกใช้เมธอด setLocationRestriction() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

พารามิเตอร์ที่ไม่บังคับ

ใช้ออบเจ็กต์ SearchNearbyRequest เพื่อระบุพารามิเตอร์ที่ไม่บังคับสำหรับการค้นหา

  • ประเภทและประเภทหลัก

    ให้คุณระบุรายการประเภทจากประเภทในตาราง ก ที่ใช้กรองผลการค้นหา ระบุประเภทได้สูงสุด 50 ประเภทในแต่ละหมวดหมู่ข้อจำกัดประเภท

    สถานที่มีประเภทหลักได้เพียงประเภทเดียวจากประเภทต่างๆ ในตาราง กที่เชื่อมโยงกับสถานที่นั้น เช่น ประเภทหลักอาจเป็น "mexican_restaurant" หรือ "steak_house" ใช้ includedPrimaryTypes และ excludedPrimaryTypes เพื่อกรองผลลัพธ์ตามประเภทหลักของสถานที่

    สถานที่หนึ่งๆ อาจมีค่าประเภทหลายค่าจากประเภทต่างๆ ที่เชื่อมโยงกับ ตาราง ก เช่น ร้านอาหารอาจมีประเภทต่อไปนี้ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ใช้ includedTypes และ excludedTypes เพื่อกรองผลการค้นหาในรายการประเภทที่เชื่อมโยงกับสถานที่

    เมื่อคุณระบุประเภทหลักทั่วไป เช่น "restaurant" หรือ "hotel" การตอบกลับอาจมีสถานที่ที่มีประเภทหลักที่เฉพาะเจาะจงกว่าประเภทที่ระบุ เช่น คุณได้ระบุให้รวม"restaurant"ประเภทหลัก จากนั้นการตอบกลับอาจมีสถานที่ประเภทหลักเป็น "restaurant" แต่การตอบกลับอาจมีสถานที่ประเภทหลักที่เฉพาะเจาะจงมากขึ้น เช่น "chinese_restaurant" หรือ "seafood_restaurant"

    หากระบุการค้นหาที่มีข้อจำกัดหลายประเภท ระบบจะแสดงเฉพาะสถานที่ที่ตรงกับข้อจำกัดทั้งหมด ตัวอย่างเช่น หากคุณระบุ includedTypes = Arrays.asList("restaurant") และ excludedPrimaryTypes = Arrays.asList("steak_house") สถานที่ที่แสดงผลจะให้บริการที่เกี่ยวข้องกับ "restaurant" แต่ไม่ได้ดำเนินการเป็น "steak_house" เป็นหลัก

    ดูตัวอย่างวิธีใช้ includedTypes และ excludedTypes ได้ที่คำขอการค้นหาในพื้นที่ใกล้เคียง (ใหม่)

    ประเภทที่รวมอยู่

    รายการประเภทสถานที่จากตาราง กที่จะค้นหา หากไม่ระบุพารามิเตอร์นี้ ระบบจะแสดงสถานที่ทุกประเภท

    หากต้องการตั้งค่าพารามิเตอร์ประเภทที่รวม ให้เรียกใช้เมธอด setIncludedTypes() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

    ประเภทที่ยกเว้น

    รายการประเภทสถานที่จากตาราง กที่จะยกเว้นจากการค้นหา

    หากคุณระบุทั้ง includedTypes (เช่น "school") และ excludedTypes (เช่น "primary_school") ในคำขอ การตอบกลับจะรวมสถานที่ที่จัดอยู่ในหมวดหมู่ "school" แต่ไม่ใช่ "primary_school" การตอบกลับจะมีสถานที่ที่ตรงกับ includedTypes อย่างน้อย 1 แห่ง และไม่มี excludedTypes

    หากมีประเภทที่ขัดแย้งกัน เช่น ประเภทที่ปรากฏทั้งใน includedTypes และ excludedTypes ระบบจะแสดงข้อผิดพลาด INVALID_REQUEST

    หากต้องการตั้งค่าพารามิเตอร์ประเภทที่ยกเว้น ให้เรียกใช้เมธอด setExcludedTypes() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

    ประเภทหลักที่รวมอยู่

    รายการประเภทสถานที่หลักจากตาราง กที่จะรวมในการค้นหา

    หากต้องการตั้งค่าพารามิเตอร์ประเภทหลักที่รวมอยู่ ให้เรียกใช้เมธอด setIncludedPrimaryTypes() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

    ประเภทหลักที่ยกเว้น

    รายการประเภทสถานที่หลักจากตาราง กที่จะยกเว้นจากการค้นหา

    หากมีประเภทหลักที่ขัดแย้งกัน เช่น ประเภทที่ปรากฏทั้งใน includedPrimaryTypes และ excludedPrimaryTypes ระบบจะแสดงข้อผิดพลาด INVALID_ARGUMENT

    หากต้องการตั้งค่าพารามิเตอร์ประเภทหลักที่ยกเว้น ให้เรียกใช้เมธอด setExcludedPrimaryTypes() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

  • จํานวนผลลัพธ์สูงสุด

    ระบุจำนวนผลลัพธ์สถานที่สูงสุดที่จะแสดง ต้องอยู่ระหว่าง 1 ถึง 20 (ค่าเริ่มต้น)

    หากต้องการตั้งค่าพารามิเตอร์จํานวนผลลัพธ์สูงสุด ให้เรียกใช้เมธอด setMaxResultCount() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

  • ค่ากําหนดอันดับ

    ประเภทการจัดอันดับที่จะใช้ หากไม่ระบุพารามิเตอร์นี้ ระบบจะจัดอันดับผลการค้นหาตามความนิยม อาจเป็นค่าใดค่าหนึ่งต่อไปนี้

    • POPULARITY (ค่าเริ่มต้น) จัดเรียงผลการค้นหาตามความนิยม
    • DISTANCE จัดเรียงผลลัพธ์จากน้อยไปมากตามระยะทางจากสถานที่ที่ระบุ

    หากต้องการตั้งค่าพารามิเตอร์ค่ากําหนดการจัดอันดับ ให้เรียกใช้เมธอด setRankPreference() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

  • รหัสภูมิภาค

    รหัสภูมิภาคที่ใช้จัดรูปแบบการตอบกลับ ซึ่งระบุเป็นค่า รหัส CLDR 2 อักขระ ไม่มีค่าเริ่มต้น

    หากชื่อประเทศของช่อง FORMATTED_ADDRESS ในการตอบกลับตรงกับ regionCode ระบบจะไม่ใส่รหัสประเทศใน FORMATTED_ADDRESS

    รหัส CLDR ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1 โดยมีข้อยกเว้นบางประการ ตัวอย่างเช่น ccTLD ของสหราชอาณาจักรคือ "uk" (.co.uk) ส่วนรหัส ISO 3166-1 คือ "gb" (ในทางเทคนิคสำหรับนิติบุคคล "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ") พารามิเตอร์นี้อาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง

    หากต้องการตั้งค่าพารามิเตอร์รหัสภูมิภาค ให้เรียกใช้เมธอด setRegionCode() เมื่อสร้างออบเจ็กต์ SearchNearbyRequest

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

เมื่อแอปแสดงข้อมูลที่ได้จาก PlacesClient เช่น รูปภาพและรีวิว แอปจะต้องแสดงการระบุแหล่งที่มาที่จําเป็นด้วย

ดูข้อมูลเพิ่มเติมได้ที่นโยบายสำหรับ Places SDK สำหรับ Android