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

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

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

מסלולי תחבורה ציבורית, שמבקשים על ידי הגדרת 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, כולל השעה מוצגת כחותמת זמן בפורמט 'Zulu' של UTC‏ RFC3339. מידע נוסף
הכללת מסלולים חלופיים	"computeAlternativeRoutes": true	זה שינוי אופציונלי. מגדירים את הערך כ-true כדי לאפשר ל-Routes API לחשב עד 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
          }
        },
        {},
        {},
        {},
        {},
        {},
        {}
        ]
      }
    ]
  }
]
}