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

เลือกแพลตฟอร์ม แอนดรอยด์ iOS JavaScript บริการผ่านเว็บ

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

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

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

ส่งคำขอการค้นหาด้วย Nearby (ใหม่) โดยการโทร PlacesClient.searchNearby, การส่งผ่าน SearchNearbyRequest ที่กำหนดพารามิเตอร์คำขอ

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

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

ตัวอย่างคำขอค้นหาใกล้เคียงนี้ระบุว่าออบเจ็กต์ Place ของการตอบกลับ มีฟิลด์สถานที่ Place.Field.ID และ Place.Field.NAME สำหรับแต่ละฟิลด์ Place รายการในผลการค้นหา และยังกรองการตอบสนองเฉพาะ แสดงสถานที่ของประเภท "ร้านอาหาร" และ "คาเฟ่" แต่ยกเว้นสถานที่ประเภท "ร้านอาหารพิซซ่า" และ "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.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 ที่แสดงสถานที่ที่ตรงกันทั้งหมด โดยมี 1 รายการ Place ออบเจ็กต์ต่อสถานที่ที่ตรงกัน
  • ออบเจ็กต์ 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.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.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

    • ช่องต่อไปนี้จะเรียกใช้การค้นหาใกล้เคียง (แนะนำ) SKU

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, 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.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.NAME);

  • การจำกัดตำแหน่ง

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

    หากต้องการตั้งค่าพารามิเตอร์การจำกัดตำแหน่ง ให้เรียกเมธอด setLocationRestriction() เมื่อสร้างวัตถุ SearchNearbyRequest

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

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

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

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

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

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

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

    สำหรับตัวอย่างวิธีใช้ includedTypes และ excludedTypes โปรดดู คำขอการค้นหาด้วย Nearby (ใหม่)

    ประเภทที่รวม

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • อันดับที่ต้องการ

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

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

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

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

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

    หากชื่อประเทศของช่อง formattedAddress ในคำตอบตรงกับ regionCode, รหัสประเทศไม่รวมอยู่ใน formattedAddress

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

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

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

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

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