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

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

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

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

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

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

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

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

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

คำขอการค้นหาในบริเวณใกล้เคียงตัวอย่างนี้ระบุว่าออบเจ็กต์ Place ในการตอบกลับ จะมีฟิลด์สถานที่ Place.Field.ID และ Place.Field.DISPLAY_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.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 ได้ที่ เข้าถึงฟิลด์ข้อมูลออบเจ็กต์ Place

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

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

  • รายการฟิลด์

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

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

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ การค้นหาในบริเวณใกล้เคียง แบบ 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

      ดูรายการฟิลด์ทั้งหมดและ SKU ที่เกี่ยวข้องได้ที่ ฟิลด์ข้อมูลสถานที่ (ใหม่)

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ การค้นหาในบริเวณใกล้เคียง แบบ 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

      ดูรายการฟิลด์ทั้งหมดและ SKU ที่เกี่ยวข้องได้ที่ ฟิลด์ข้อมูลสถานที่ (ใหม่)

    • ฟิลด์ต่อไปนี้จะทริกเกอร์ การค้นหาในบริเวณใกล้เคียง แบบ 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

      ดูรายการฟิลด์ทั้งหมดและ SKU ที่เกี่ยวข้องได้ที่ ฟิลด์ข้อมูลสถานที่ (ใหม่)

    หากต้องการตั้งค่าพารามิเตอร์รายการฟิลด์ ให้เรียกใช้ 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 เพื่อระบุพารามิเตอร์ที่ไม่บังคับสำหรับการค้นหา

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

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

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

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

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

    รายการประเภทสถานที่จาก ตาราง 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 (ค่าเริ่มต้น) รวมทั้ง 2 ค่า

    หากต้องการตั้งค่าพารามิเตอร์จำนวนผลลัพธ์สูงสุด ให้เรียกใช้เมธอด 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