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

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

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

• includeTypes/excludedTypes, includePrimaryTypes/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 ที่ด้านขวาของหน้า
2. (ไม่บังคับ) ขยายแสดงพารามิเตอร์มาตรฐาน แล้วตั้งค่าพารามิเตอร์ fields เป็นมาสก์ฟิลด์
3. แก้ไขเนื้อหาคําขอ (ไม่บังคับ)
4. เลือกปุ่มดำเนินการ ในป๊อปอัป ให้เลือกบัญชีที่ต้องการใช้ส่งคําขอ

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