Method: geocode.destinations.searchDestinations

เมธอดนี้จะค้นหาปลายทางและแสดงรายการปลายทาง

คำขอ HTTP

POST https://geocode.googleapis.com/v4beta/geocode/destinations

URL ใช้ไวยากรณ์การแปลงรหัส gRPC

เนื้อความของคำขอ

เนื้อหาของคำขอมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of mutually exclusive fields.
}
ฟิลด์
travelModes[]

enum (NavigationPoint.TravelMode)

ไม่บังคับ รูปแบบการเดินทางเพื่อกรองจุดนำทาง ซึ่งจะส่งผลต่อช่อง navigationPoints ที่แสดงในคำตอบ หากเว้นว่างไว้ ระบบจะแสดงจุดนำทางของรูปแบบการเดินทางทั้งหมด
languageCode

string

ไม่บังคับ ภาษาที่ควรแสดงผลลัพธ์
regionCode

string

ไม่บังคับ รหัสภูมิภาค รหัสภูมิภาคที่ระบุเป็นค่า ccTLD ("โดเมนระดับบนสุด") แบบ 2 อักขระ พารามิเตอร์นี้ส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง พารามิเตอร์นี้ยังส่งผลต่อผลลัพธ์จากบริการด้วย แต่จะไม่จำกัดผลลัพธ์โดยสมบูรณ์

ค้นหาปลายทางหลัก ซึ่งอาจเป็นสถานที่ ที่อยู่ที่ระบุไว้อย่างสมบูรณ์ หรือตำแหน่ง LatLng ก็ได้ สถานที่และที่อยู่บางแห่งที่มีข้อมูลน้อยมากจะไม่สามารถเปลี่ยนเป็นจุดหมายได้

ระบบจะสร้างปลายทางตามการค้นหาหลักที่ระบุ

หมายเหตุ: ระบบรองรับเฉพาะสถานที่และที่อยู่ที่มีจุดหมายปลายทางสำหรับการนำทางเท่านั้น ตัวอย่างเช่น สถานที่ที่แสดงถึงบ้านหรืออพาร์ตเมนต์คอมเพล็กซ์สามารถใช้เป็นคำค้นหาหลักได้ แต่สถานที่ที่แสดงถึงท้องถิ่นหรือเขตบริหารจะใช้เป็นคำค้นหาหลักไม่ได้ ต่อไปนี้คือรายการช่องที่แยกกันโดยสิ้นเชิง ระบบจะตั้งค่าช่องอย่างน้อย 1 ช่องในการตอบกลับ ดังนี้
place

string

ชื่อทรัพยากรของสถานที่ในรูปแบบ places/{placeId}
addressQuery

object (SearchDestinationsRequest.AddressQuery)

ที่อยู่
locationQuery

object (SearchDestinationsRequest.LocationQuery)

ตำแหน่งที่แน่นอน
สิ้นสุดฟิลด์ที่แยกกัน

เนื้อหาการตอบกลับ

ข้อความตอบกลับสำหรับ DestinationService.SearchDestinations

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
ช่อง
destinations[]

object (Destination)

รายการปลายทาง

บริการจะแสดงผลลัพธ์ 1 รายการหากระบุปลายทางหลักได้อย่างชัดเจนจากการค้นหาหลัก มิฉะนั้น บริการอาจแสดงผลลัพธ์หลายรายการเพื่อแก้ความกำกวมหรือแสดงผลลัพธ์เป็น 0 รายการ

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth อย่างใดอย่างหนึ่งต่อไปนี้

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode
  • https://www.googleapis.com/auth/maps-platform.destinations

SearchDestinationsRequest.AddressQuery

ที่อยู่ซึ่งคุณต้องการค้นหา ระบุที่อยู่ตามรูปแบบที่ใช้โดยบริการไปรษณีย์แห่งชาติของประเทศที่เกี่ยวข้อง

การแสดง JSON 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of mutually exclusive fields.
}
ช่อง
การค้นหาที่อยู่ ต่อไปนี้คือรายการช่องที่แยกกันโดยสิ้นเชิง ระบบจะตั้งค่าช่องอย่างน้อย 1 ช่องในการตอบกลับ ดังนี้
address

object (PostalAddress)

ที่อยู่ตามถนนในรูปแบบที่อยู่ทางไปรษณีย์
addressQuery

string

ที่อยู่ซึ่งจัดรูปแบบเป็นบรรทัดเดียว
สิ้นสุดฟิลด์ที่แยกกัน

SearchDestinationsRequest.LocationQuery

คำค้นหาสถานที่เพื่อระบุจุดหมายหลักที่อยู่ใกล้เคียง

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

การแสดง JSON 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "location": {
    object (LatLng)
  }
  // End of mutually exclusive fields.
}
ฟิลด์
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

ไม่บังคับ ตัวกรองที่จะใช้กับปลายทางที่เป็นไปได้
คำค้นหาสถานที่ ต่อไปนี้คือรายการช่องที่แยกกันโดยสิ้นเชิง ระบบจะตั้งค่าช่องอย่างน้อย 1 ช่องในการตอบกลับ ดังนี้
location

object (LatLng)

ตำแหน่ง LatLng ที่แน่นอน
สิ้นสุดฟิลด์ที่แยกกัน

SearchDestinationsRequest.LocationQuery.PlaceFilter

ตัวกรองที่จะใช้กับปลายทางที่เป็นไปได้

การแสดง JSON 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
ฟิลด์
structureType

enum (PlaceView.StructureType)

ไม่บังคับ หากระบุไว้ ระบบจะรับประกันว่าปลายทางทั้งหมดจะมีสถานที่หลักที่มีประเภทโครงสร้างนี้ ซึ่งอาจส่งผลให้มีการกรองจุดหมายบางแห่งออก หรือทำให้จุดหมายที่แสดงผลมีความละเอียดน้อยลง/มากขึ้น

เช่น หากระบุ GROUNDS จุดหมายทั้งหมดที่แสดงผลจะมีสถานที่หลักที่มีประเภทโครงสร้าง GROUNDS ซึ่งอาจส่งผลให้มีการกรองจุดหมายบางแห่งที่ไม่ได้เป็นส่วนหนึ่งของสถานที่ออก หรือทำให้จุดหมายที่แสดงผลมีความละเอียดน้อยลงจนถึงระดับสถานที่

การใช้งานอีกอย่างหนึ่งของช่องนี้คือการแยกรูปหลายเหลี่ยมที่แสดงอาคารได้ง่ายขึ้น เช่น หากระบุ BUILDING รูปหลายเหลี่ยมที่แสดงของสถานที่หลักจะเป็นของอาคารในสถานที่ที่ระบุ
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

ไม่บังคับ หากระบุ ระบบจะแสดงเฉพาะปลายทางที่ตรงตามเกณฑ์ความสามารถในการระบุที่อยู่ที่เกี่ยวข้องเท่านั้น

PlaceView.StructureType

ประเภทของโครงสร้างที่สถานที่นี้แสดง

Enum
STRUCTURE_TYPE_UNSPECIFIED ไม่ได้ใช้
POINT ตำแหน่งจุด
SECTION ส่วนย่อยของอาคาร
BUILDING อาคาร
GROUNDS พื้นที่ขนาดใหญ่ที่มักมีอาคารหลายหลัง เช่น วิทยาเขตของมหาวิทยาลัย อพาร์ตเมนต์คอมเพล็กซ์ หรือศูนย์การค้า

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

กำหนดตัวเลือกสำหรับการกรองความสามารถในการระบุตัวตน ทั้งนี้ อาจมีการเพิ่มค่าใหม่ในอนาคต

Enum
ADDRESSABILITY_UNSPECIFIED เมื่อไม่ได้ระบุ บริการจะเลือกค่าเริ่มต้นที่เหมาะสม
ANY ความสามารถในการระบุตัวตนไม่ใช่เกณฑ์การกรอง ระบบจะแสดงผลปลายทางโดยไม่คำนึงถึงความสามารถในการระบุที่อยู่
PRIMARY จุดหมายทั้งหมดที่แสดงผลจะมีสถานที่หลักพร้อมที่อยู่หรือชื่อระดับถนน
WEAK จุดหมายทั้งหมดที่แสดงผลจะมีสถานที่หลักหรือจุดหมายย่อยที่มีที่อยู่หรือชื่อระดับถนน

ปลายทาง

ปลายทาง ซึ่งรวมถึงสถานที่หลัก สถานที่ที่เกี่ยวข้อง ทางเข้า และจุดนำทาง

การแสดง JSON 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ]
}
ช่อง
primary

object (PlaceView)

สถานที่หลักที่ระบุโดย primary_query ในคำขอ
containingPlaces[]

object (PlaceView)

สถานที่ที่มีความแม่นยำน้อยกว่าซึ่งมีสถานที่หลักอยู่ เช่น อาคารอพาร์ตเมนต์ที่มีอาคารนี้อยู่
subDestinations[]

object (PlaceView)

จุดหมายย่อยที่แม่นยำยิ่งขึ้นของสถานที่หลัก เช่น หน่วยที่อยู่ในอาคาร

หมายเหตุ: เมื่อเทียบกับ SubDestination ที่แสดงผลโดย Places API รายการจุดหมายย่อยนี้จะครอบคลุมมากกว่า และจุดหมายย่อยแต่ละแห่งจะมีข้อมูลมากกว่า
landmarks[]

object (Landmark)

จุดสังเกตที่ใช้สื่อสารได้ว่าจุดหมายอยู่ที่ใดหรือช่วยในการเดินทางไปถึง
entrances[]

object (Entrance)

ทางเข้าสำหรับจุดหมายนี้
navigationPoints[]

object (NavigationPoint)

จุดนำทางสำหรับปลายทางนี้

PlaceView

แสดงมุมมองของสถานที่ใน Places API นอกจากนี้ ยังให้ข้อมูลเพิ่มเติมที่เฉพาะเจาะจงสำหรับจุดหมาย เช่น ประเภทโครงสร้างและรูปหลายเหลี่ยมที่แสดง

ในบางกรณี PlaceView ที่มีรหัสสถานที่เดียวกันอาจแตกต่างจากสิ่งที่ Places API แสดงผลสำหรับช่อง types และ displayName

การแสดง JSON 
{
  "place": string,
  "placeId": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
ช่อง
place

string

ชื่อทรัพยากรของสถานที่นี้ในรูปแบบ places/{placeId} ใช้เพื่อค้นหาสถานที่ได้
placeId

string

ตัวระบุที่ไม่ซ้ำกันของสถานที่
displayName

object (LocalizedText)

คำอธิบายสถานที่ที่มนุษย์อ่านได้ เช่น "ประตู B", "McDonalds"
primaryType

string

ประเภทสถานที่หลักของสถานที่นี้ ดูรายการค่าที่เป็นไปได้ที่ https://developers.google.com/maps/documentation/places/web-service/place-types

หมายเหตุ: ช่องนี้ไม่ได้มีข้อมูลอยู่เสมอ เตรียมพร้อมที่จะใช้ช่อง types ในสถานการณ์ดังกล่าว
types[]

string

ประเภทสถานที่ที่เกี่ยวข้องทั้งหมดของสถานที่นี้ ดูรายการค่าที่เป็นไปได้ที่ https://developers.google.com/maps/documentation/places/web-service/place-types
formattedAddress

string

ที่อยู่แบบบรรทัดเดียว
postalAddress

object (PostalAddress)

ที่อยู่ที่มีโครงสร้าง
structureType

enum (PlaceView.StructureType)

ประเภทของโครงสร้างที่สอดคล้องกับสถานที่นี้
location

object (LatLng)

ตำแหน่งของสถานที่นี้ สำหรับสถานที่ที่มีรูปหลายเหลี่ยมที่แสดงผล จุดนี้อาจเป็นจุดที่เหมาะสำหรับการวางเครื่องหมายบนแผนที่
displayPolygon

object (Struct format)

โครงร่างรูปหลายเหลี่ยมของสถานที่ในรูปแบบ GeoJSON โดยใช้รูปแบบ RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6

หมายเหตุ: รูปแบบ RFC 7946 รองรับ MultiPolygon ดังนั้นออบเจ็กต์ displayPolygon 1 รายการจึงแสดงรูปหลายเหลี่ยมได้หลายรูป
addressComponents[]

object (PlaceView.AddressComponent)

คอมโพเนนต์ที่ซ้ำกันสำหรับระดับสถานที่แต่ละระดับ

PlaceView.AddressComponent

องค์ประกอบที่มีโครงสร้างซึ่งประกอบกันเป็นที่อยู่ที่จัดรูปแบบแล้ว หากมีข้อมูลนี้

การแสดง JSON 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
ช่อง
longText

string

คำอธิบายแบบข้อความเต็มหรือชื่อของคอมโพเนนต์ที่อยู่ ตัวอย่างเช่น องค์ประกอบที่อยู่ของประเทศออสเตรเลียอาจมีชื่อแบบยาวเป็น "ออสเตรเลีย"
shortText

string

ชื่อแบบย่อของคอมโพเนนต์ที่อยู่ (หากมี) ตัวอย่างเช่น คอมโพเนนต์ที่อยู่สำหรับประเทศออสเตรเลียอาจมีชื่อย่อเป็น "AU"
types[]

string

อาร์เรย์ที่ระบุประเภทขององค์ประกอบที่อยู่

ค่าเหล่านี้ดึงมาจากตารางประเภทที่อยู่และประเภทคอมโพเนนต์ที่อยู่ที่ Places API ใช้: https://developers.google.com/maps/documentation/places/web-service/place-types#address-types
languageCode

string

ภาษาที่ใช้จัดรูปแบบคอมโพเนนต์นี้ในรูปแบบ CLDR

สถานที่สำคัญ

จุดสังเกตใช้เพื่อสื่อสารว่าจุดหมายอยู่ที่ใดหรือช่วยในการเดินทางไปยังจุดหมาย

การแสดง JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": {
    object (PlaceView)
  }
  // End of mutually exclusive fields.
}
ช่อง
relationalDescription

object (LocalizedText)

คำอธิบายที่มนุษย์อ่านได้เกี่ยวกับความสัมพันธ์ระหว่างจุดหมายกับจุดสังเกต เช่น "ใกล้ตึกเอ็มไพร์สเตต" หรือ "ตรงข้ามทำเนียบขาว"
tags[]

enum (Landmark.Tag)

แท็กที่อธิบายวิธีใช้จุดสังเกตในบริบทของจุดหมาย
straightLineDistanceMeters

number

เอาต์พุตเท่านั้น ระยะทางแบบเส้นตรงจากจุดสังเกตนี้ไปยังจุดหมายปลายทางเป็นเมตร
travelDistanceMeters

number

เอาต์พุตเท่านั้น ระยะทางเดินเท้าจากจุดสังเกตนี้ไปยังจุดหมายปลายทางเป็นเมตร
จุดสังเกต ต่อไปนี้คือรายการช่องที่แยกกันโดยสิ้นเชิง ระบบจะตั้งค่าช่องอย่างน้อย 1 ช่องในการตอบกลับ ดังนี้
place

object (PlaceView)

สถานที่ที่แสดงถึงจุดสังเกตนี้
สิ้นสุดฟิลด์ที่แยกกัน

Landmark.Tag

รายการแท็กที่เป็นไปได้ทั้งหมดซึ่งอธิบายวิธีใช้จุดสังเกตในบริบทของจุดหมาย

หากที่อยู่มีทั้งแท็ก ADDRESS และ ARRIVAL หมายความว่าสถานที่สำคัญนั้นเป็นที่รู้จักในท้องถิ่นและอยู่ใกล้กับจุดหมาย

Enum
TAG_UNSPECIFIED ไม่ได้ใช้
ADDRESS สถานที่ที่โดดเด่นในท้องถิ่นซึ่งใช้ระบุตำแหน่งทั่วไปของจุดหมายได้ โดยปกติจะอยู่ห่างจากจุดหมายไม่กี่ร้อยเมตร ซึ่งคล้ายกับจุดสังเกตที่แสดงผลโดยฟีเจอร์ตัวบ่งชี้ที่อยู่ของ Geocoding API: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors
ARRIVAL สถานที่ที่ใช้เพื่อช่วยให้ไปถึงจุดหมายได้ มีประโยชน์สำหรับการนำทางเมื่อคุณอยู่ใกล้จุดหมาย เช่น จุดสังเกตนี้อาจเป็นสถานที่ที่อยู่ฝั่งตรงข้ามถนนจากจุดหมาย จุดสังเกตที่มีแท็กนี้มักจะอยู่ใกล้กับจุดหมายมากกว่าจุดสังเกตที่มีแท็ก ADDRESS

ทางเข้า

ทางเข้าคือคู่พิกัดละติจูด/ลองจิจูดเดียวที่กำหนดตำแหน่งของจุดเข้าและออกของสถานที่

การแสดง JSON 
{
  "displayName": {
    object (LocalizedText)
  },
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
ช่อง
displayName

object (LocalizedText)

ชื่อที่มนุษย์อ่านได้ เช่น "ประตู B", "ทางเข้าทิศใต้", "ทางเข้าถนนสายที่ 5"
location

object (LatLng)

ตำแหน่งของทางเข้า
tags[]

enum (Entrance.Tag)

รายการแท็กที่อธิบายทางเข้า
place

string

โครงสร้างที่ทางเข้านี้ตั้งอยู่จริงในรูปแบบ places/{placeId}

Entrance.Tag

ลักษณะที่อธิบายทางเข้า

Enum
TAG_UNSPECIFIED ไม่ได้ใช้
PREFERRED

ทางเข้าน่าจะให้สิทธิ์เข้าถึงสถานที่หลักในจุดหมายที่แสดงผล สถานที่หนึ่งๆ อาจมีทางเข้าที่ต้องการหลายทาง หากทางเข้าไม่มีแท็กนี้ แสดงว่าทางเข้าอยู่ในอาคารเดียวกับสถานที่หลัก แต่ไม่จำเป็นต้องเป็นทางเข้าสถานที่นั้น

ตัวอย่างเช่น หากสถานที่หลักเป็นร้านอาหารในศูนย์การค้า ทางเข้า "ที่ต้องการ" จะเป็นทางเข้าที่น่าจะนำไปสู่ร้านอาหารนั้นๆ ส่วนทางเข้าอื่นๆ ที่แสดงผลจะเป็นทางเข้าอื่นๆ ของอาคาร เช่น ทางเข้าของร้านอาหารอื่นๆ ในศูนย์การค้า

หากสถานที่หลักคือตัวอาคาร ทางเข้า PREFERRED จะเป็นทางเข้าที่นำไปสู่ส่วน "หลัก" ของอาคาร ตัวอย่างเช่น ในศูนย์การค้า ทางเข้าPREFERREDจะเป็นทางเข้าที่อนุญาตให้เข้าถึงพื้นที่ห้องโถงหลัก แต่หากทางเข้าอนุญาตให้เข้าถึงเฉพาะร้านค้าที่อยู่ด้านข้างของอาคาร ทางเข้านั้นจะไม่ใช่ทางเข้าPREFERRED

หมายเหตุ: ทางเข้าPREFERREDอาจไม่ได้ให้สิทธิ์เข้าถึงสถานที่หลัก และทางเข้าที่ไม่ใช่PREFERREDอาจให้สิทธิ์เข้าถึงสถานที่หลัก