หน้านี้ได้รับการแปลโดย 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 การค้นหาใกล้เคียง (พื้นฐาน)
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^*, places.photos, places.plusCode, places.primaryType, {18/0}, {3/2}, {3/2}places.nameplaces.primaryTypeDisplayNameplaces.shortFormattedAddressplaces.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 การค้นหาใกล้เคียง (ที่ต้องการ)
  
  places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, {1/2}, {1/2}, {1/2}, {1/2},places.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

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

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

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

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

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

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

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

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

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

FieldMask

locationRestriction

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

includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode