หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

โปรแกรมสำรวจ API ช่วยให้คุณส่งคําขอแบบเรียลไทม์เพื่อให้คุณคุ้นเคยกับ API และตัวเลือก API ต่อไปนี้

ลองใช้งาน

ลองการสาธิตแบบอินเทอร์แอกทีฟเพื่อดูผลการค้นหาใกล้เคียง (ใหม่) ที่แสดงบนแผนที่

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

คำขอการค้นหาใกล้เคียง (ใหม่) คือคำขอ HTTP POST ที่ส่งไปยัง URL ในรูปแบบต่อไปนี้

https://places.googleapis.com/v1/places:searchNearby

ส่งพารามิเตอร์ทั้งหมดในเนื้อหาคําขอ JSON หรือในส่วนหัวเป็นส่วนหนึ่งของคําขอ POST เช่น

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

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

การค้นหาในพื้นที่ (ใหม่) จะแสดงผลเป็น ออบเจ็กต์ JSON ในการตอบกลับ ในการตอบกลับ

อาร์เรย์ places มีสถานที่ที่ตรงกันทั้งหมด
สถานที่แต่ละแห่งในอาร์เรย์จะแสดงด้วยออบเจ็กต์ Place ออบเจ็กต์ Place มีรายละเอียดเกี่ยวกับสถานที่เดียว
FieldMask ที่ส่งในคําขอจะระบุรายการช่องที่แสดงผลในออบเจ็กต์ Place

ออบเจ็กต์ JSON ที่สมบูรณ์อยู่ในรูปแบบต่อไปนี้

{
  "places": [
    {
      object (Place)
    }
  ]
}

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

FieldMask

ระบุรายการช่องที่จะแสดงในการตอบกลับโดยสร้างมาสก์ช่องคำตอบ ส่งมาสก์ฟิลด์การตอบกลับไปยังเมธอดโดยใช้พารามิเตอร์ URL $fields หรือ fields หรือใช้ส่วนหัว HTTP X-Goog-FieldMask ไม่มีการระบุรายการช่องที่แสดงผลเริ่มต้นในการตอบกลับ หากคุณละเว้นมาสก์ช่อง เมธอดจะแสดงข้อผิดพลาด

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

ระบุรายการประเภทข้อมูลสถานที่ที่คั่นด้วยคอมมาเพื่อแสดงผล เช่น เพื่อดึงข้อมูลชื่อที่แสดงและที่อยู่ของสถานที่
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
หมายเหตุ: ระบบไม่อนุญาตให้เว้นวรรคในรายการช่อง

ใช้ * เพื่อดึงข้อมูลทุกช่อง
```
X-Goog-FieldMask: *
```
ไวลด์การ์ด "*" จะเลือกทุกช่อง อย่างไรก็ตาม แม้ว่าการใช้ไวลด์การ์ดดังกล่าวในการพัฒนาจะเหมาะสม แต่ Google ไม่แนะนําให้ใช้ไวลด์การ์ด (*) กับมาสก์ช่องคำตอบในเวอร์ชันที่ใช้งานจริง เนื่องจากระบบอาจแสดงผลข้อมูลจํานวนมาก

ดูคําแนะนําเพิ่มเติมในการใช้ places.iconMaskBaseUri และ places.iconBackgroundColor ได้ในส่วนไอคอนสถานที่

ระบุฟิลด์ต่อไปนี้อย่างน้อย 1 ฟิลด์
- ฟิลด์ต่อไปนี้จะทริกเกอร์ SKU ของ Search ในพื้นที่ใกล้เคียง (พื้นฐาน)
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks^*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* ช่อง places.googleMapsLinks อยู่ในช่วงก่อน GA Preview และไม่มีการเรียกเก็บเงิน ซึ่งหมายความว่าการเรียกเก็บเงินจะเป็น $0 สำหรับการใช้งานในช่วงทดลองใช้
  
  ^** ช่อง places.name มีชื่อทรัพยากรของสถานที่ในรูปแบบ places/PLACE_ID ใช้ places.displayName เพื่อเข้าถึงชื่อข้อความของสถานที่
- ฟิลด์ต่อไปนี้จะทริกเกอร์ SKU การค้นหาในพื้นที่ (ขั้นสูง)
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.priceRange, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- ฟิลด์ต่อไปนี้จะทริกเกอร์ SKU การค้นหาในพื้นที่ใกล้เคียง (แนะนำ)
  
  places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.routingSummaries,^* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout
  
  ^* การค้นหาข้อความและการค้นหาในพื้นที่เท่านั้น
locationRestriction

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

เช่น
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

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

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

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

หมายเหตุ: ค่าในตาราง ขจะแสดงในการตอบกลับเท่านั้น คุณไม่สามารถใช้ค่าในตาราง ข เป็นตัวกรอง

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

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

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

หากระบุการค้นหาที่มีข้อจำกัดหลายประเภท ระบบจะแสดงเฉพาะสถานที่ที่ตรงกับข้อจำกัดทั้งหมด ตัวอย่างเช่น หากคุณระบุ {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} สถานที่ที่แสดงผลจะให้บริการที่เกี่ยวข้องกับ "restaurant" แต่ไม่ได้ดำเนินการเป็น "steak_house" เป็นหลัก

หากละเว้น includedTypes, excludedTypes, includedPrimaryTypes และ excludedPrimaryTypes ออกจากคำขอ การค้นหาจะแสดงสถานที่ทุกประเภทจากภายในขอบเขตการจำกัดสถานที่

includedTypes

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

excludedTypes

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

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

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

includedPrimaryTypes

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

excludedPrimaryTypes

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

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

ภาษาที่จะแสดงผลลัพธ์
- ดูรายการภาษาที่รองรับ Google อัปเดตภาษาที่รองรับอยู่บ่อยครั้ง รายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
- หากไม่ได้ระบุ languageCode ระบบจะใช้ en เป็นค่าเริ่มต้นของ API หากคุณระบุรหัสภาษาที่ไม่ถูกต้อง API จะแสดงข้อผิดพลาด INVALID_ARGUMENT
- API จะพยายามอย่างเต็มที่เพื่อให้ที่อยู่ซึ่งอ่านได้ทั้งผู้ใช้และคนในพื้นที่ โดยจะแสดงผลที่อยู่เป็นภาษาท้องถิ่น ถอดเสียงเป็นอักษรที่ผู้ใช้อ่านได้หากจำเป็น โดยคำนึงถึงภาษาที่ต้องการ ระบบจะแสดงผลที่อยู่อื่นๆ ทั้งหมดเป็นภาษาที่ต้องการ ระบบจะแสดงผลองค์ประกอบที่อยู่ทั้งหมดเป็นภาษาเดียวกัน ซึ่งเลือกจากคอมโพเนนต์แรก
- หากชื่อไม่พร้อมใช้งานในภาษาที่ต้องการ API จะใช้ชื่อที่ใกล้เคียงที่สุด
- ภาษาที่ต้องการมีอิทธิพลเพียงเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกแสดงและลําดับที่แสดงผล ตัวระบุพิกัดภูมิศาสตร์จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อสำหรับประเภทถนน หรือคำพ้องความหมายที่อาจใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง
maxResultCount

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

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

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

หากชื่อประเทศของช่อง formattedAddress ในการตอบกลับตรงกับ regionCode ระบบจะไม่ใส่รหัสประเทศใน formattedAddress พารามิเตอร์นี้ไม่มีผลกับ adrFormatAddress ซึ่งรวมชื่อประเทศไว้เสมอ หรือกับ shortFormattedAddress ซึ่งไม่มีชื่อประเทศ

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

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

ค้นหาสถานที่ประเภทเดียว

ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาในพื้นที่ใกล้เคียง (ใหม่) สำหรับชื่อที่แสดงของร้านอาหารทั้งหมดภายในรัศมี 500 เมตร ซึ่งกำหนดโดย circle

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

โปรดทราบว่าส่วนหัว X-Goog-FieldMask ระบุว่าการตอบกลับมีช่องข้อมูล places.displayName การตอบกลับจึงอยู่ในรูปแบบ

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

เพิ่มประเภทข้อมูลอื่นๆ ลงในมาสก์ช่องเพื่อแสดงข้อมูลเพิ่มเติม เช่น เพิ่ม places.formattedAddress,places.types,places.websiteUri เพื่อใส่ที่อยู่ ประเภท และที่อยู่เว็บของร้านอาหารในการตอบกลับ

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

คำตอบตอนนี้อยู่ในรูปแบบ

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

ค้นหาสถานที่หลายประเภท

ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาใกล้เคียง (ใหม่) สำหรับชื่อที่แสดงของร้านสะดวกซื้อและร้านขายเหล้าทั้งหมดภายในรัศมี 1,000 เมตรของ circle ที่ระบุ

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

ตัวอย่างนี้จะเพิ่ม places.primaryType และ places.types ลงในมาสก์ช่องเพื่อให้การตอบกลับมีข้อมูลประเภทเกี่ยวกับสถานที่แต่ละแห่ง ซึ่งช่วยให้เลือกสถานที่ที่เหมาะสมจากผลการค้นหาได้ง่ายขึ้น

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

ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาใกล้เคียง (ใหม่) สำหรับสถานที่ทั้งหมดประเภท "school" ยกเว้นสถานที่ทั้งหมดประเภท "primary_school" โดยจัดอันดับผลลัพธ์ตามระยะทาง

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

ค้นหาสถานที่ทั้งหมดที่อยู่ใกล้กับพื้นที่หนึ่งๆ โดยจัดอันดับตามระยะทาง

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

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

ลองใช้งาน

เครื่องมือสำรวจ API ช่วยให้คุณส่งคำขอตัวอย่างเพื่อให้คุ้นเคยกับ API และตัวเลือก API

เลือกไอคอน API api ทางด้านขวาของหน้า
แก้ไขพารามิเตอร์คำขอ (ไม่บังคับ)
เลือกปุ่มดำเนินการ ในกล่องโต้ตอบ ให้เลือกบัญชีที่ต้องการใช้ส่งคำขอ
ในแผงโปรแกรมสำรวจ API ให้เลือกไอคอนแบบเต็มหน้าจอ fullscreen เพื่อขยายหน้าต่างโปรแกรมสำรวจ API

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

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

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

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

FieldMask

locationRestriction

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

includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode

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

ค้นหาสถานที่ประเภทเดียว

ค้นหาสถานที่หลายประเภท

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

ค้นหาสถานที่ทั้งหมดที่อยู่ใกล้กับพื้นที่หนึ่งๆ โดยจัดอันดับตามระยะทาง

ลองใช้งาน