מעבר מתכונות בגרסה 3 לנקודת הקצה (endpoint) SearchDestinations

מפתחים באזור הכלכלי האירופי (EEA)

התכונות הבאות ב-Geocoding API v3 מוחלפות בנקודת הקצה SearchDestinations של Geocoding API v4:

  • כניסות
  • נקודות ניווט
  • יצירת נקודות עיקריות
  • שטחים

אם השתמשתם ב-Geocoding API v3 כדי להשתמש בתכונות שלמעלה, תוכלו להיעזר במסמך הזה כדי להשתמש במקום זאת בנקודת הקצה SearchDestinations ולקבל את התכונות האלה. במסמך הזה מוסבר איפה בתגובה של SearchDestinations API אפשר למצוא את התכונות האלה, ומהם ההבדלים באופן הייצוג של התכונות האלה בתגובות של API בין Geocoding API v3 לבין נקודת הקצה SearchDestinations של Geocoding API v4.

כניסות

כדי לקבל את הכניסות שמשויכות לdestination, משתמשים בשדה destination.entrances.

שימו לב שהפורמט של entrance שונה מעט מפורמט הכניסה ב-Geocoding API v3. כל כניסה ב-destination.entrances כוללת את השדות הבאים:

  • ‫displayName – זהו שדה חדש אופציונלי שבו יופיע שם קריא של הכניסה, לדוגמה: 'שער ב'.
  • ‫location – זהו מיקום מהסוג LatLng, ששונה מהפורמט שבו נעשה שימוש ב-Geocoding API v3.
  • ‫tags – זהה לשדה tags של הכניסות מ-Geocoding API v3.
  • ‫place – מקביל לשדה buildingPlaceId של הכניסות מ-Geocoding API גרסה 3. עם זאת, מזהה המקום בשדה הזה יכול להיות של מקום מכל סוג, לא רק של בניין.

כדי לקבל את נקודות הניווט שמשויכות ל-destination, משתמשים בשדה destination.navigationPoints.

שימו לב שהפורמט של navigationPoint שונה מעט מהפורמט של נקודת ניווט ב-Geocoding API v3. כל נקודת ניווט ב-destination.navigationPoints כוללת את השדות הבאים:

  • ‫displayName – זהו שדה אופציונלי חדש שיכלול שם קריא של נקודת הניווט, לדוגמה 'שדרת האפשרויות'.
  • ‫location – זהו מיקום מהסוג LatLng, ששונה מהפורמט שבו נעשה שימוש ב-Geocoding API v3.
  • ‫travelModes – דומה לשדה restrictedTravelModes של נקודות הניווט מ-Geocoding API גרסה 3. הערכים האפשריים של ה-enum זהים, וההבדל היחיד הוא שעכשיו השדה הזה מייצג את אמצעי התחבורה המקובלים לנקודת הניווט, ולא את אמצעי התחבורה המוגבלים.
  • ‫usage – זהו שדה חדש שמכיל את תרחישי השימוש שנתמכים על ידי נקודת הניווט. שימו לב: לרוב נקודות הניווט יהיה UNKNOWNשימוש, אבל זה לא בהכרח אומר שהשימוש בנקודת הניווט מוגבל בצורה כלשהי.

יצירת נקודות עיקריות

כדי לקבל את קווי המתאר של הבניין שמשויכים ל-destination, צריך להשתמש בשדה displayPolygon של האובייקטים placeView ב-destination שמייצגים בניינים. לכל placeView, אפשר לבדוק אם מדובר בבניין באמצעות השדה placeView.structureType. אם סוג המבנה הוא BUILDING, אפשר לקבל את המתאר מהשדה placeView.displayPolygon. ב-placeView יהיו גם שדות נוספים של הבניין שלא היו ב-Geocoding API v3.

ל-destination יכול להיות אובייקט placeView שמייצג בניין בשדות הבאים:

  • ‫destination.primary – זה המקום העיקרי של היעד.
  • ‫destination.containingPlaces – זהו שדה חוזר שיכול להכיל מקומות גדולים יותר שכוללים את המקום הראשי. לדוגמה, אם המקום הראשי הוא subpremise, בדרך כלל יופיע ב-containingPlaces הערך placeView שמייצג את הבניין.
  • ‫destination.subDestinations – זהו שדה חוזר שיכול להכיל יעדי משנה של המקום הראשי. לדוגמה, יחידות דיור נפרדות בבניין. בדרך כלל לא יופיע בשדה הזה placeView שמייצג בניין.

שימו לב שהפורמט של placeView.displayPolygon זהה לפורמט של קווי המתאר של הבניין ב-Geocoding API v3, שהוא פורמט GeoJSON, באמצעות פורמט RFC 7946.

שטחים

בדומה ליצירת מתארים, כדי לקבל את השטחים שמשויכים ל-destination, צריך להשתמש בשדה displayPolygon של אובייקטים מסוג placeView ב-destination שמייצגים שטחים. לכל placeView, אפשר לבדוק אם הוא עילה באמצעות השדה placeView.structureType. אם סוג המבנה הוא GROUNDS, אפשר לקבל את המתאר מהשדה placeView.displayPolygon. ב-placeView יהיו גם שדות נוספים לסיבות שלא היו ב-Geocoding API v3.

ל-destination יכול להיות אובייקט placeView שמייצג את הבסיס בשדות הבאים:

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

שימו לב שהפורמט של placeView.displayPolygon זהה לפורמט של קווי המתאר של השטח ב-Geocoding API v3, שהוא פורמט GeoJSON, באמצעות פורמט RFC 7946.

שימוש במסכת שדות כדי לבקש את התכונות האלה

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

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations