Method: geocode.destinations.searchDestinations

השיטה הזו מבצעת חיפוש של יעד ומחזירה רשימה של יעדים.

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של gRPC Transcoding.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
שדות
travelModes[]

enum (NavigationPoint.TravelMode)

אופציונלי. אמצעי התחבורה לסינון נקודות הניווט. הפעולה הזו משפיעה על השדה navigationPoints שמוחזר בתגובה. אם המערך ריק, אפשר להחזיר נקודות ניווט של כל אמצעי התחבורה.
languageCode

string

אופציונלי. השפה שבה התוצאות צריכות להיות מוצגות.
regionCode

string

אופציונלי. קוד אזור. קוד האזור, שמוגדר כערך של שני תווים של ccTLD (דומיין ברמה העליונה). הפרמטר משפיע על התוצאות בהתאם לדין החל. הפרמטר הזה גם משפיע על התוצאות מהשירות, אבל לא מגביל אותן באופן מלא.

שדה איחוד primary_query. שליחת שאילתה ליעד הראשי. יכול להיות שמדובר במקום, בכתובת מלאה או במיקום LatLng. לא ניתן להפוך ליעד חלק מהמקומות והכתובות שיש לגביהם מידע מינימלי.

היעדים מבוססים על השאילתה הראשית שצוינה.

הערה: יש תמיכה רק במקומות ובכתובות שיכולים להיות יעד לניווט. לדוגמה, אפשר להשתמש במקום שמייצג בית או מתחם דירות כשאילתת החיפוש הראשית, אבל אי אפשר להשתמש במקומות שמייצגים יישוב או אזור אדמיניסטרטיבי כשאילתת החיפוש הראשית. הערך primary_query יכול להיות רק אחד מהבאים:
place

string

שם המשאב של המקום, בפורמט places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

כתובת רחוב.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

מיקום מדויק.

גוף התשובה

הודעת תגובה ל-DestinationService.SearchDestinations.

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
שדות
destinations[]

object (Destination)

רשימה של יעדים.

השירות מחזיר תוצאה אחת אם אפשר לזהות באופן חד-משמעי יעד ראשי מתוך השאילתה הראשית. אחרת, השירות עשוי להחזיר כמה תוצאות כדי להסביר את ההבדל בין האפשרויות, או לא להחזיר תוצאות בכלל.

היקפי הרשאה

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

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

SearchDestinationsRequest.AddressQuery

כתובת הרחוב שרוצים לחפש. צריך לציין את הכתובות בהתאם לפורמט שבו משתמשים בשירות הדואר הלאומי של המדינה הרלוונטית.

ייצוג ב-JSON 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
שדות
שדה איחוד kind. שאילתת הכתובת. הערך kind יכול להיות רק אחד מהבאים:
address

object (PostalAddress)

כתובת רחוב בפורמט של כתובת למשלוח דואר.
addressQuery

string

כתובת רחוב בפורמט של שורה אחת.

SearchDestinationsRequest.LocationQuery

שאילתת מיקום כדי לזהות יעד ראשי בקרבת מקום.

הערה: אם שאילתת המיקום היא בתוך בניין שמכיל שטחי משנה, יכול להיות שהמקום הראשי שיוחזר הוא שטח משנה. במקרים כאלה, השדה containingPlaces יכלול את הבניין.

ייצוג ב-JSON 
{

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
שדות
שדה איחוד kind. שאילתת המיקום. הערך kind יכול להיות רק אחד מהבאים:
location

object (LatLng)

מיקום מדויק של קו רוחב וקו אורך.

יעד

יעד. המידע הזה כולל את המקום הראשי, מקומות קשורים, כניסות ונקודות ניווט.

ייצוג ב-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,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  }
}
שדות
place

string

שם המשאב של המקום הזה, בפורמט places/{placeId}.
displayName

object (LocalizedText)

תיאור קריא של המקום. לדוגמה, 'שער ב', 'מקדונלדס'
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 תומך ב-MultiPolygons, כך שאובייקט displayPolygon אחד יכול לייצג כמה מצולעים.

PlaceView.StructureType

סוג המבנה שהמקום הזה מייצג.

טיפוסים בני מנייה (enum)
STRUCTURE_TYPE_UNSPECIFIED לא בשימוש.
POINT מיקום נקודתי.
SECTION חלק ממבנה.
BUILDING בניין.
GROUNDS אזור גדול שבדרך כלל מכיל כמה בניינים, כמו קמפוס אוניברסיטאי, מתחם דירות או קניון.

ציון דרך

ציוני דרך משמשים כדי לציין איפה היעד נמצא או כדי לעזור להגיע ליעד.

ייצוג ב-JSON 
{
  "tags": [
    enum (Landmark.Tag)
  ],

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
שדות
tags[]

enum (Landmark.Tag)

תגים שמתארים איך אפשר להשתמש בציון הדרך בהקשר של היעד.
שדה איחוד landmark. ציון הדרך. הערך landmark יכול להיות רק אחד מהבאים:
place

object (PlaceView)

המקום שמייצג את ציון הדרך הזה.

Landmark.Tag

רשימה של כל התגים האפשריים שמתארים איך אפשר להשתמש בנקודת ציון בהקשר של יעד.

אם לכתובת יש גם את התג ADDRESS וגם את התג ARRIVAL, המשמעות היא שציון הדרך בולט בסביבה וגם קרוב ליעד.

טיפוסים בני מנייה (enum)
TAG_UNSPECIFIED לא בשימוש.
ADDRESS מקום בולט באזור שאפשר להשתמש בו כדי לזהות את המיקום הכללי של היעד. בדרך כלל בטווח של כמה מאות מטרים מהיעד. הם דומים לנקודות הציון שמחזירה התכונה Address Descriptors (תיאורי כתובות) של Geocoding API: ‏ https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL מקום שיכול לעזור להגיע ליעד. התכונה הזו שימושית לניווט כשמתקרבים ליעד. לדוגמה, ציון הדרך יכול להיות מקום שנמצא בצד השני של הרחוב מהיעד. בדרך כלל, נקודת ציון עם התג הזה קרובה יותר ליעד מאשר נקודות ציון עם התג ADDRESS.

כניסה

כניסה היא זוג קואורדינטות יחיד של קו רוחב וקו אורך שמגדיר את המיקום של נקודת כניסה ויציאה למקום.

ייצוג ב-JSON 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
שדות
location

object (LatLng)

המיקום של הכניסה.
tags[]

enum (Entrance.Tag)

רשימת תגים שמתארים את הכניסה.
place

string

המבנה שבו הכניסה ממוקמת פיזית, בפורמט places/{placeId}.

Entrance.Tag

מאפיינים שמתארים כניסה.

טיפוסים בני מנייה (enum)
TAG_UNSPECIFIED לא בשימוש.
PREFERRED

הכניסה כנראה מספקת גישה פיזית למקום הראשי ביעד שהוחזר. יכולים להיות למקום כמה כניסות מועדפות. אם אין תג כזה לכניסה, זה אומר שהכניסה נמצאת פיזית באותו בניין כמו המקום הראשי, אבל לא בהכרח מאפשרת גישה למקום.

לדוגמה, אם המקום הראשי הוא מסעדה בקניון, הכניסות שיוחזרו עם הערך 'מועדפות' הן כנראה הכניסות שמובילות ישירות למסעדה, ואילו הכניסות האחרות שיוחזרו הן כניסות אחרות לבניין, כמו כניסות למסעדות אחרות בקניון.

אם המקום הראשי הוא בניין, PREFERRED הכניסות יהיו אלה שמובילות לחלק ה "ראשי" של הבניין. לדוגמה, במרכז קניות, PREFERRED הכניסות הן אלה שמאפשרות גישה לאזור הלובי הראשי, אבל אם כניסה מסוימת מאפשרת גישה רק לחנות בצד הבניין, היא לא תהיה PREFERRED כניסה.

הערה: יכול להיות שPREFERRED כניסה לא תאפשר גישה למקום הראשי, ויכול להיות שPREFERRED כניסה כן תאפשר גישה למקום הראשי.