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

คำขอการค้นหาใกล้เคียง (ใหม่) จะรับประเภทสถานที่อย่างน้อย 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: *

  ระบุฟิลด์ต่อไปนี้อย่างน้อย 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 และไม่มีค่าใช้จ่าย ซึ่งหมายความว่าการเรียกเก็บเงินจะเป็น $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

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

  หากคุณระบุทั้ง 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

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

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

1. เลือกไอคอน API api ทางด้านขวาของหน้า

2. แก้ไขพารามิเตอร์คำขอ (ไม่บังคับ)

3. เลือกปุ่มดำเนินการ ในกล่องโต้ตอบ ให้เลือกบัญชีที่ต้องการใช้ส่งคำขอ

4. ในแผงโปรแกรมสำรวจ API ให้เลือกไอคอนแบบเต็มหน้าจอ fullscreen เพื่อขยายหน้าต่างโปรแกรมสำรวจ API