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
  • https://www.googleapis.com/auth/maps-platform.destinations

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 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
שדות
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

אופציונלי. מסננים להחלה על מועמדים ליעד.
שדה איחוד kind. שאילתת המיקום. הערך kind יכול להיות רק אחד מהבאים:
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)
    }
  ],
  "parkingOptions": {
    object (Destination.ParkingOptions)
  },
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
שדות
primary

object (PlaceView)

המקום הראשי שזוהה על ידי primary_query בבקשה.
containingPlaces[]

object (PlaceView)

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

object (PlaceView)

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

הערה: בהשוואה לSubDestination שמוחזר על ידי Places API, הרשימה הזו של יעדי משנה מקיפה יותר, וכל יעד משנה מכיל יותר מידע.
landmarks[]

object (Landmark)

ציוני דרך שאפשר להשתמש בהם כדי להסביר איפה היעד נמצא או כדי לעזור להגיע אליו.
entrances[]

object (Entrance)

כניסות ליעד הזה.
navigationPoints[]

object (NavigationPoint)

נקודות ניווט ליעד הזה.
parkingOptions

object (Destination.ParkingOptions)

אפשרויות חנייה ביעד הזה.
arrivalSummary

object (Destination.ArrivalSummary)

סיכום שנוצר על ידי AI של חוויית ההגעה ליעד.

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

ציון דרך

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

ייצוג JSON 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

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

object (LocalizedText)

תיאור קריא לאנשים של הקשר בין היעד לבין נקודת הציון. לדוגמה: 'ליד בניין אמפייר סטייט' או 'מול הבית הלבן'.
tags[]

enum (Landmark.Tag)

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

number

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

number

פלט בלבד. המרחק ברשת הכבישים מנקודת הציון הזו ליעד במטרים.
שדה איחוד 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,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
שדות
location

object (LatLng)

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

enum (Entrance.Tag)

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

string

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

object (StreetViewThumbnail)

תמונה ממוזערת של Street View שבה מוצגת הכניסה. אפשר לבקש את התמונה מ-Street View Static API. מידע נוסף מופיע כאן: https://developers.google.com/maps/documentation/streetview/request-streetview.
streetViewAnnotation

object (ImageAnnotation)

הערה לגבי הכניסה ב-streetViewThumbnail שמוחזר למעלה.

Entrance.Tag

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

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

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

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

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

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

StreetViewThumbnail

פרמטרים לייצוג תמונה ממוזערת של Google Street View. אפשר להשתמש בפרמטרים האלה כדי לבקש תמונה של Street View מ-Street View Static API. מידע נוסף מופיע כאן: https://developers.google.com/maps/documentation/streetview/request-streetview.

ייצוג JSON 
{
  "pano": string,
  "widthPx": integer,
  "heightPx": integer,
  "headingDegree": number,
  "pitchDegree": number,
  "fovDegree": number
}
שדות
pano

string

מזהה פנורמה ספציפי.
widthPx

integer

רוחב התמונה הממוזערת של הפלט בפיקסלים. הערה: כשמבקשים להוסיף הערות לצד התמונה הממוזערת, צריך להשתמש בערכי הגובה והרוחב האלה בבקשת API ל-Street View כדי לוודא שהקואורדינטות של ההערות מיושרות בצורה נכונה עם התמונה.
heightPx

integer

גובה התמונה הממוזערת של הפלט בפיקסלים. הערה: כשמבקשים להוסיף הערות לצד התמונה הממוזערת, צריך להשתמש בערכי הגובה והרוחב האלה בבקשת API ל-Street View כדי לוודא שהקואורדינטות של ההערות מיושרות בצורה נכונה עם התמונה.
headingDegree

number

הכיוון האופקי של המצלמה במעלות. הטווח [0, 360). ‫0 מציין צפון ו-90 מציין מזרח.
pitchDegree

number

הכיוון האנכי של המצלמה במעלות. הטווח הוא [‎-90, 90]. ‫0 הוא קו האופק, ‎+90 הוא ישר למעלה, ‎-90 הוא ישר למטה.
fovDegree

number

שדה הראייה האופקי במעלות. טווח (0, 180]. שליטה ברמת הזום. שדה ראייה קטן יותר מאפשר זום גדול יותר.

ImageAnnotation

הערה על תמונה ממוזערת, למשל מצולע שמתווה כניסה.

ייצוג JSON 
{
  "coordinates": [
    {
      object (ImageAnnotation.Coordinate)
    }
  ]
}
שדות
coordinates[]

object (ImageAnnotation.Coordinate)

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

ImageAnnotation.Coordinate

קואורדינטת ה-Pixel של נקודה בתמונה. נקודת המוצא (0,0) היא הפינה השמאלית העליונה של הפיקסל השמאלי העליון בתמונה, כאשר ציר ה-x מצביע ימינה וציר ה-y מצביע למטה.

ייצוג JSON 
{
  "xPx": number,
  "yPx": number
}
שדות
xPx

number

קואורדינטה X.
yPx

number

קואורדינטת Y.

Destination.ParkingOptions

מידע על אפשרויות חנייה ביעד.

ייצוג JSON 
{
  "availability": enum (Destination.ParkingOptions.Availability),
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
שדות
availability

enum (Destination.ParkingOptions.Availability)

זמינות החניה ביעד הזה.
onsiteParking

boolean

יש חניה במקום היעד.
freeParkingLot

boolean

יש חניונים בחינם.
paidParkingLot

boolean

יש חניונים בתשלום.
freeStreetParking

boolean

יש חניה ברחוב בחינם.
paidStreetParking

boolean

יש חניה ברחוב בתשלום.
valetParking

boolean

יש שירות החניית רכבים.
freeGarageParking

boolean

יש חניון בחינם.
paidGarageParking

boolean

יש חניון בתשלום.

Destination.ParkingOptions.Availability

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

יכול להיות שבעתיד נוסיף ערכים חדשים.

טיפוסים בני מנייה (enum)
AVAILABILITY_UNSPECIFIED אין מידע על זמינות חנייה.
PLENTY יש הרבה מקומות חניה.
SOMEWHAT_DIFFICULT קצת קשה למצוא חניה.
DIFFICULT קשה מאוד למצוא חניה.

Destination.ArrivalSummary

סיכום שנוצר על ידי AI של חוויית ההגעה ליעד.

ייצוג JSON 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
שדות
text

object (LocalizedText)

סיכום של חוויית ההגעה ליעד.
flagContentUrl

string

קישור שדרכו משתמשים יכולים לסמן בעיה בסיכום.
disclosureText

object (LocalizedText)

פלט בלבד. מכיל את טקסט הגילוי הנאות של סיכום ההגעה.