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

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

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

API Explorer ช่วยให้คุณสามารถสร้างคำขอแบบเรียลไทม์เพื่อทำความคุ้นเคยกับ 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 การค้นหาใกล้เคียง (พื้นฐาน):
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, {1/2} , , , {1/2} {1/2} {1/2} places.nameplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport
  
  places/PLACE_ID ใช้ places.displayName เพื่อเข้าถึงชื่อข้อความของสถานที่
- ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (ขั้นสูง) ให้แสดงขึ้น
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- ช่องต่อไปนี้จะเรียก SKU การค้นหาใกล้เคียง (ที่ต้องการ):
  
  <br-ph - "ph - 2 - x" <br - 2 <br - "1 x x 2 x 2"><br - " TH <br - " <br - " ">places.allowsDogsplaces.curbsidePickupplaces.deliveryplaces.dineInplaces.editorialSummaryplaces.evChargeOptionsplaces.fuelOptionsplaces.goodForChildrenplaces.goodForGroupsplaces.goodForWatchingSportsplaces.liveMusicplaces.menuForChildrenplaces.parkingOptionsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.reviewsplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
locationRestriction

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

ตัวอย่างเช่น
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

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

includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

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

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

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

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

หากระบุการค้นหาโดยมีข้อจำกัดหลายประเภท ระบบจะแสดงผลเฉพาะสถานที่ที่ตรงกับข้อจำกัดทั้งหมดเท่านั้น ตัวอย่างเช่น หากคุณระบุ {"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 ค่าเริ่มต้นของ API จะเป็น en หากคุณระบุรหัสภาษาที่ไม่ถูกต้อง 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 ทางด้านขวาของหน้า
(ไม่บังคับ) ขยายแสดงพารามิเตอร์มาตรฐานและตั้งค่าพารามิเตอร์ fields เป็นฟิลด์มาสก์
(ไม่บังคับ) แก้ไขเนื้อหาคำขอ
เลือกปุ่มดำเนินการ ในป๊อปอัป ให้เลือกบัญชีที่ต้องการใช้ส่งคำขอ
ในแผง API Explorer ให้เลือกไอคอนขยาย เพื่อขยายหน้าต่าง API Explorer

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

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

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

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

FieldMask

locationRestriction

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

includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode