دریافت مسیر حمل‌ونقل عمومی

توسعه‌دهندگان منطقه اقتصادی اروپا (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) به‌عنوان مرجع، تنظیم کنید:
  • تا ۷ روز قبل‌از now (شامل خود روز هفتم)
  • تا ۱۰۰ روز پس‌از now (شامل خود روز صدم)
زمان به‌صورت مُهر زمان در قالب RFC3339 UTC «Zulu» بیان می‌شود. بیشتر بدانید

توجه: برنامه‌های زمانی حمل‌ونقل عمومی مرتباً تغییر می‌کنند، سفرهای حمل‌ونقل عمومی دردسترس ممکن است به‌مرور زمان تغییر کنند و هیچ تضمینی برای ارائه نتایج یکسان برای پیش‌بینی‌های خیلی زودتر از موعد وجود ندارد.
مسیرهای جایگزین را اضافه کنید "computeAlternativeRoutes": true اختیاری. اگر روی true تنظیم شود، Compute Routes تا ۳ مسیر دیگر را درصورت دردسترس بودن محاسبه می‌کند. بیشتر بدانید
اولویت‌های نوع حمل‌ونقل عمومی را مشخص کنید "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
          }
        },
        {},
        {},
        {},
        {},
        {},
        {}
        ]
      }
    ]
  }
]
}