Как построить маршрут на общественном транспорте

Разработчики из Европейской экономической зоны (ЕЭЗ)

Маршрут на общественном транспорте содержит инструкции по навигации с использованием общественного транспорта, доступного в регионе. Это могут быть автобусы, метро, поезда и т. д. Маршрут общественного транспорта также обычно включает инструкции по ходьбе до, от и между транзитными станциями. Поскольку маршрут общественного транспорта обычно предполагает использование нескольких видов транспорта, способ запроса маршрута и некоторые части ответа различаются.

Чем маршруты общественного транспорта отличаются от других маршрутов

Маршруты общественного транспорта, которые вы запрашиваете, задав для travelMode значение TRANSIT, отличаются от маршрутов, использующих другие варианты travelMode. Вы не можете запрашивать все те же объекты и параметры, а ответ возвращает другие поля по сравнению с другими маршрутами.

В Routes API шаги всегда представляют собой одну навигационную инструкцию для всех типов путешествий. Каждая инструкция по навигации – это шаг. Ответ с маршрутом на общественном транспорте очень похож на ответ с маршрутом для других способов передвижения, но есть несколько ключевых отличий:

Различия в запросах Различия в ответах
Промежуточные путевые точки указывать нельзя. Включает сведения о транспорте.
Не удалось получить экологичные маршруты. Включает метаданные для каждого режима путешествия, которые содержат сводку шагов для этого режима путешествия, в `stepsOverview` (чтобы запросить эти метаданные, используйте маску поля `routes.legs.stepsOverview` ).
Нельзя указать, нужно ли включать данные о трафике и как это сделать
Нельзя указать, какие особенности маршрута нужно избегать.
Для routingPreference можно указать только transitPreferences. Подробную информацию можно найти в статье 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 вычислял до трех дополнительных маршрутов, если они доступны. Подробнее…
Укажите предпочтения для типа транспорта "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
          }
        },
        {},
        {},
        {},
        {},
        {},
        {}
        ]
      }
    ]
  }
]
}