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

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

    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, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
    
    ^* ช่อง places.name มี ชื่อทรัพยากร สถานที่ ในแบบฟอร์ม: 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.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, 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

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

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

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

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

  includedPrimaryTypes

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

  excludedPrimaryTypes

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

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

• languageCode

  ภาษาที่จะแสดงผลการค้นหา

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

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

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