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

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

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

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

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

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

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

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

ตัวอย่างคำขอค้นหาใกล้เคียงนี้ระบุว่าออบเจ็กต์ Place ของการตอบกลับมีช่องสถานที่ Place.Field.ID และ Place.Field.NAME สำหรับออบเจ็กต์ 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);

// 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 ได้ที่เข้าถึงช่องข้อมูลออบเจ็กต์ 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 เพื่อกรองผลลัพธ์ตามประเภทหลักของสถานที่

    สถานที่อาจมีค่าหลายประเภทจากประเภทตาราง A ที่เชื่อมโยงอยู่ด้วย เช่น ร้านอาหารอาจมีประเภทต่อไปนี้ "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 (ใหม่)

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

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

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

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

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

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

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

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

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

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

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

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

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

    หากมีประเภทหลักที่ขัดแย้งกัน เช่น ประเภทหนึ่งๆ ปรากฏอยู่ทั้งใน 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