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

เลือกแพลตฟอร์ม: Android iOS JavaScript Web Service

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

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

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ Nearby Search Pro SKU

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
          * ใช้แทน Place.Field.NAME ซึ่งเลิกใช้งานไปแล้ว
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * ใช้แทน Place.Field.ICON_URL ซึ่งเลิกใช้งานแล้ว
      Place.Field.ID
      Place.Field.LAT_LNG
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.RESOURCE_NAME
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT
      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ Nearby Search Enterprise SKU

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * ใช้แทน Place.Field.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.USER_RATINGS_TOTAL ซึ่ง เลิกใช้งานแล้ว
      Place.Field.WEBSITE_URI

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ Nearby Search Enterprise Plus 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);

  • การจำกัดสถานที่

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

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

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

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

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

    ช่วยให้คุณระบุรายการประเภทจาก types ตาราง A ที่ใช้ในการกรอง ผลการค้นหา ระบุประเภทได้สูงสุด 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" การตอบกลับจะรวมสถานที่ที่ตรงกับอย่างน้อย 1 รายการใน includedTypes และไม่มีรายการใดใน 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