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

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

นักพัฒนาแอปในเขตเศรษฐกิจยุโรป (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 รายการต่อสถานที่ที่ตรงกัน 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