קבלת מסלול בתחבורה ציבורית

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

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

מה ההבדל בין מסלולי תחבורה ציבורית לבין מסלולים אחרים

מסלולי תחבורה ציבורית, שמתקבלים כשמגדירים את travelMode כ-TRANSIT, שונים ממסלולים שמתקבלים כשמגדירים אפשרויות שונות של travelMode. אי אפשר לבקש את כל אותם אובייקטים ואפשרויות, והתגובה מחזירה שדות שונים בהשוואה למסלולים אחרים.

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

הבדלים בבקשות הבדלים בתשובות
אי אפשר לציין נקודות ציון ביניים. כולל פרטי תחבורה ציבורית.
אי אפשר לקבל מסלולים ידידותיים לסביבה כולל מטא-נתונים לכל אמצעי תחבורה שמכילים את סיכום השלבים של אמצעי התחבורה הזה, ב-`stepsOverview` (כדי לבקש את המטא-נתונים האלה, צריך להשתמש במסכת השדות `routes.legs.stepsOverview`).
אי אפשר לציין איך לכלול נתוני תנועה או אם לכלול אותם
אי אפשר לציין תכונות של מסלול כדי להימנע מהן
אפשר לציין רק transitPreferences עבור routingPreference. פרטים נוספים זמינים בכתובת TransitPreferences.

מידע נוסף על התגובה שמוחזרת מ-Routes API זמין במאמר בנושא בדיקת תגובות של מסלולי תחבורה ציבורית.

כדי לקבל מסלול לתחבורה ציבורית

  1. מגדירים את נקודת המוצא ואת היעד.

  2. מגדירים את אמצעי התחבורה לתחבורה ציבורית:

    travelMode: "TRANSIT"

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

  4. אם צריך, מגדירים פרמטרים אופציונליים. מידע נוסף זמין במאמר הגדרת פרמטרים למסלול תחבורה ציבורית.

שליחת בקשה לקבלת השדות של מסלול התחבורה הציבורית שאתם צריכים

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

כדי לבקש את המידע הזה שימוש במסכת השדות הזו
כל פרטי המסלול routes.*
כל פרטי התחבורה הציבורית routes.legs.steps.transitDetails
המיקום ההתחלתי של כל קטע במסלול routes.legs.steps.startLocation
מיקום הסיום של כל קטע במסלול routes.legs.steps.endLocation
קו פוליגון של המסלול לכל שלב routes.legs.steps.polyline
סוג התחבורה הציבורית שמשמשת בכל שלב routes.legs.steps.travelMode
המחיר המשוער לכל שלב ולמסלול, וגם המחיר המשוער בלוקליזציה routes.travel_advisory.transitFare localized routes.localizedValues.transitFare

הערה: הערך transitFare מסופק רק אם ה-API יכול לקבוע את פרטי התעריף של כל השלבים.
טקסט מותאם לשוק המקומי לציון משך ומרחק routes.localizedValues

מידע נוסף על הגדרת מסכות שדות זמין במאמר בחירת שדות להחזרה.

הגדרת פרמטרים לנתיב תחבורה ציבורית

אלה הפרמטרים הרלוונטיים למסלולי תחבורה ציבורית:

כדי לעשות את זה שימוש בפרמטר הזה הערות
בחירת אמצעי תחבורה travelMode: "TRANSIT" חובה. מידע נוסף
הגדרת שעת הגעה או שעת יציאה "arrivalTime": "yyyy-mm-ddThh:mm:ssZ"

או

"departureTime": "yyyy-mm-ddThh:mm:ssZ"		 אופציונלי. אפשר לציין את שעת ההגעה (arrival_time) או את שעת היציאה (departure_time). אם לא מציינים את שני הזמנים, ברירת המחדל של departure_time היא זמן הביצוע הנוכחי (now). אפשר להגדיר את זמני ההגעה והיציאה רק בחלון הזמן הבא, עם זמן הביצוע הנוכחי (now) כנקודת ההתייחסות:
  • עד 7 ימים לפני now, כולל
  • עד 100 ימים אחרי now (כולל)
השעה מיוצגת כחותמת זמן בפורמט RFC3339 UTC ‏'Zulu'. מידע נוסף

הערה: לוחות הזמנים של התחבורה הציבורית משתנים לעיתים קרובות, ויכול להיות שעם הזמן ישתנו גם הנסיעות בתחבורה הציבורית שזמינות. אין אפשרות להבטיח תוצאות עקביות לגבי תחזיות לטווח ארוך.
כולל מסלולים חלופיים "computeAlternativeRoutes": true אופציונלי. הגדרה ל-true תאפשר ל-Compute Routes לחשב עד 3 מסלולים נוספים, אם הם זמינים. מידע נוסף
ציון העדפות לסוג התחבורה "transitPreferences": { allowedTravelModes: ["BUS","SUBWAY","TRAIN","LIGHT_RAIL","RAIL"]}

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

 אופציונלי. מציינים את אמצעי התחבורה המועדפים. מידע נוסף
ציון העדפות למסלול תחבורה ציבורית "transitPreferences": {routingPreference: "LESS_WALKING|FEWER_TRANSFERS"} אופציונלי. מציינים את העדפות הניתוב לתחבורה ציבורית. מידע נוסף

דוגמה: קבלת מסלול בתחבורה ציבורית

בדוגמה הבאה מוצגת קבלת מסלול בתחבורה ציבורית עם הפרמטרים הבאים:

  • העדפות נסיעה ברכבת ופחות הליכה.

  • מבקש מסלולים חלופיים.

  • מספק אנונימיזציה של השדה שמחזירה את פרטי המעבר:

curl -X POST -H 'content-type: application/json' -d '{
  "origin": {
    "address": "Humberto Delgado Airport, Portugal"
  },
  "destination": {
    "address": "Basílica of Estrela, Praça da Estrela, 1200-667 Lisboa, Portugal"
  },
  "travelMode": "TRANSIT",
  "computeAlternativeRoutes": true,
  "transitPreferences": {
     routingPreference: "LESS_WALKING",
     allowedTravelModes: ["TRAIN"]
  },
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.legs.steps.transitDetails' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

בתשובה מוצגים השדות route.legs.steps.transitDetails של שני המסלולים:

{
  "routes": [
    {
    "legs": [
        {
        "steps": [
          {},
          {},
          {},
          {
          "transitDetails": {
            "stopDetails": {
            "arrivalStop": {
              "name": "Saldanha",
              "location": {
                "latLng": {
                  "latitude": 38.73532,
                  "longitude": -9.14543
                }
              }
            },
            "arrivalTime": "2023-08-26T10:49:42Z",
            "departureStop": {
              "name": "Aeroporto",
              "location": {
                "latLng": {
                  "latitude": 38.769047799999996,
                  "longitude": -9.1284593
                }
              }
            },
            "departureTime": "2023-08-26T10:32:10Z"
              },
              "localizedValues": {
              "arrivalTime": {
                  "time": {
                    "text": "11:49"
                  },
                  "timeZone": "Europe/Lisbon"
              },
              "departureTime": {
                "time": {
                  "text": "11:32"
                },
                "timeZone": "Europe/Lisbon"
              }
            },
              "headsign": "São Sebastião",
              "transitLine": {
                "agencies": [
                  {
                    "name": "Metropolitano de Lisboa, E.P.E.",
                    "phoneNumber": "+351 21 350 0115",
                    "uri": "https://www.metrolisboa.pt/"
                  }
                ],
                "name": "Vermelha",
                "color": "#f23061",
                "nameShort": "Vm",
                "textColor": "#000000",
                "vehicle": {
                  "name": {
                    "text": "Metrô"
                  },
                "type": "SUBWAY",
                "iconUri": "//maps.gstatic.com/mapfiles/transit/iw2/6/subway2.png"
                }
              },
              "stopCount": 11
            }
          },
        {},
        {
          "transitDetails": {
            "stopDetails": {
              "arrivalStop": {
                "name": "Rato",
                "location": {
                  "latLng": {
                    "latitude": 38.7201022,
                    "longitude": -9.1540562
                  }
              }
            },
            "arrivalTime": "2023-08-26T11:01:37Z",
            "departureStop": {
              "name": "Saldanha",
                "location": {
                  "latLng": {
                    "latitude": 38.73527,
                    "longitude": -9.1455200000000012
                  }
                }
              },
              "departureTime": "2023-08-26T10:57:57Z"
            },
            "localizedValues": {
              "arrivalTime": {
                "time": {
                  "text": "12:01"
                },
                "timeZone": "Europe/Lisbon"
              },
              "departureTime": {
                "time": {
                  "text": "11:57"
                },
                "timeZone": "Europe/Lisbon"
              }
            },
            "headsign": "Rato",
            "transitLine": {
              "agencies": [
                {
                "name": "Metropolitano de Lisboa, E.P.E.",
                "phoneNumber": "+351 21 350 0115",
                "uri": "https://www.metrolisboa.pt/"
                }
              ],
              "name": "Amarela",
              "color": "#f2c200",
              "nameShort": "Am",
              "textColor": "#000000",
              "vehicle": {
                "name": {
                  "text": "Metrô"
                },
                "type": "SUBWAY",
                "iconUri": "//maps.gstatic.com/mapfiles/transit/iw2/6/subway2.png"
              }
            },
            "stopCount": 4
          }
        },
        {},
        {},
        {},
        {},
        {},
        {}
        ]
      }
    ]
  }
]
}