Method: geocode.destinations.searchDestinations

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

בקשת HTTP

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

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

גוף הבקשה

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

ייצוג ב-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 (דומיין ברמה העליונה) באורך שני תווים. הפרמטר משפיע על התוצאות בהתאם לדין החל. הפרמטר הזה משפיע גם על התוצאות מהשירות, אבל לא מגביל אותן באופן מלא.

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

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

הערה: אפשר להוסיף רק מקומות וכתובות שיכולים להיות יעד לניווט. לדוגמה, אפשר להשתמש במקום שמייצג בית או מתחם דירות כשאילתה ראשית, אבל אי אפשר להשתמש במקומות שמייצגים יישוב או אזור מנהלי כשאילתה ראשית. זו רשימה של שדות שמוציאים זה את זה. בתשובה יוגדר לכל היותר אחד מהשדות הבאים:
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
  • 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.
}
שדות
השאילתה של הכתובת. זו רשימה של שדות שמוציאים זה את זה. בתשובה יוגדר לכל היותר אחד מהשדות הבאים:
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)

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

object (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)

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

פלט בלבד. מרחק ההליכה מנקודת הציון הזו אל היעד, במטרים.
ציון הדרך. זו רשימה של שדות שמוציאים זה את זה. בתשובה יוגדר לכל היותר אחד מהשדות הבאים:
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)

שם קריא לאנשים, למשל "שער ב'", "כניסה דרומית", "כניסה משדרת 5".
location

object (LatLng)

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

enum (Entrance.Tag)

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

string

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

Entrance.Tag

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

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

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

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

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

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