Лучшие практикиGTFS Realtime¶

Введение¶

Это рекомендуемая практика для описания информации об общественном транспорте Realtime в формате данных GTFS Realtime.

Структура документа¶

Рекомендуемые практики организованы в два основных раздела

Практические рекомендации организованы по сообщениям: Рекомендации организованы по сообщениям и полям в том же порядке, который описан в официальном справочнике GTFS Realtime.
Практические рекомендации, организованные по случаям: В конкретных случаях, таких как обслуживание на основе частоты (в сравнении с обслуживанием Schedule), может потребоваться применение практик в нескольких сообщениях и полях, а также в соответствующих данных GTFS Schedule. Такие рекомендации объединены в данном разделе.

Публикация фидов и общая практика¶

Фиды должны публиковаться на общедоступном, постоянном URL-адресе
URL должен быть доступен напрямую, не требуя входа в систему для доступа к фиду. При желании можно использовать API-ключи, но регистрация для получения API-ключей должна быть автоматической и доступной для всех.
Поддерживать постоянные идентификаторы (поля id) в фиде GTFS Realtime (например, FeedEntity.id, VehicleDescriptor.id, CarriageDetails.id) на протяжении всех итераций фида.
Обновление фидовGTFS Realtime должно происходить не реже одного раза в 30 секунд или при изменении информации, представленной в фиде (положение транспортного средства), в зависимости от того, что происходит чаще. VehiclePositions обычно изменяются чаще, чем другие объекты фида, поэтому их следует обновлять как можно чаще. Если содержимое не изменилось, фид должен быть обновлен новой временной меткой FeedHeader.timestamp, отражающей, что информация все еще актуальна на эту временную метку.
Данные в канале GTFS Realtime не должны быть старше 90 секунд для обновлений поездок и позиций транспортных средств и не старше 10 минут для сервисных предупреждений. Например, даже если производитель постоянно обновляет временную метку FeedHeader.timestamp каждые 30 секунд, возраст VehiclePositions в этом фиде не должен быть старше 90 секунд.
Сервер, на котором размещаются данные GTFS Realtime, должен быть надежным и постоянно возвращать правильно отформатированные ответы в кодировке protobuf-. Менее 1% ответов должны быть недействительными (ошибки протобуфа или ошибки выборки).
Веб-сервер, на котором размещаются данные GTFS Realtime, должен быть настроен на корректное сообщение даты модификации файла (см. HTTP/1.1 - Запрос на комментарии 2616, раздел 14.29), чтобы потребители могли использовать HTTP-заголовок If-Modified-Since. Это экономит пропускную способность производителей и потребителей, позволяя избежать передачи содержимого фида, которое не изменилось.
Фиды должны предоставлять содержимое фида в кодировке буфера протокола по умолчанию при запросе через HTTP по заданному URL - потребителям не нужно определять специальные заголовки HTTP accept для получения содержимого в кодировке буфера протокола.
В связи с тем, как буферы протокола кодируют необязательные значения, перед чтением данных из фида GTFS Realtime потребители должны проверить наличие значений с помощью методов hasX(), генерируемых буфером протокола, прежде чем использовать это значение, и должны использовать значение только в том случае, если hasX() истинно (где X - имя поля). Если hasX() возвращает false, должно быть принято значение по умолчанию для этого поля, определенное в значении GTFS.proto. Если потребитель использует значение без предварительной проверки метода hasX(), он может читать данные по умолчанию, которые не были намеренно опубликованы производителем.
Фиды должны использовать HTTPS вместо HTTP (без шифрования) для обеспечения целостности фида.
Фиды должны охватывать подавляющее большинство поездок, включенных в сопутствующий статический набор данных GTFS. В частности, они должны включать данные о районах города с высокой плотностью и интенсивным движением, а также об оживленных маршрутах.

Рекомендации по практике, организованные по сообщениям¶

FeedHeader¶

Имя поля	Рекомендация
`gtfs_realtime_version`	Текущая версия - "2.0". Все фиды GTFS Realtime должны быть версии "2.0" или выше, так как ранняя версия GTFS Realtime не требовала всех полей, необходимых для адекватного представления различных транзитных ситуаций.
`timestamp`	Эта временная метка не должна уменьшаться между двумя последовательными итерациями фида.
	Значение временной метки должно всегда меняться при изменении содержимого фида - содержимое фида не должно меняться без обновления заголовка. `timestamp`. Общие ошибки - Если существует несколько экземпляров GTFS Realtime feed за балансировщиком нагрузки, каждый экземпляр может получать информацию из источника данных Realtime и публиковать ее потребителям немного не синхронно. Если потребитель GTFS Realtime делает два запроса подряд, и каждый запрос обслуживается разными экземплярами фида GTFS Realtime, то одно и то же содержимое фида может быть возвращено потребителю с разными временными метками. Возможное решение - Производители должны предоставлять `Last-Modified` HTTP-заголовок, а потребители должны передавать свой самый последний `If-Modified-Since` HTTP-заголовок, чтобы избежать получения устаревших данных. Возможное решение - Если HTTP-заголовки не могут быть использованы, можно использовать такие опции, как "липкие" сессии, чтобы гарантировать, что каждый потребитель направляется на один и тот же сервер производителя.

FeedEntity¶

Все объекты должны быть удалены из фида GTFS Realtime только тогда, когда они больше не актуальны для пользователей. Фиды считаются безстатусными, что означает, что каждый фид отражает все состояние транзитной системы в реальном времени. Если объект предоставляется в одном экземпляре фида, но исчезает в последующем обновлении фида, следует считать, что для этого объекта нет информации в реальном времени.

Имя поля	Рекомендация
`id`	Должна поддерживаться стабильной на протяжении всей поездки

TripUpdate¶

Общие рекомендации по отмене поездок:

При отмене поездок в течение нескольких дней производители должны предоставлять TripUpdates, ссылающиеся на данные trip_ids и start_dates как CANCELED, а также Alert с NO_SERVICE, ссылающиеся на те же trip_ids и TimeRange, которые могут быть показаны пассажирам с объяснением отмены (например, объезд).
Если ни одна остановка в поездке не будет посещена, поездку следует ОТМЕНИТЬ, а не отмечать все обновления времени остановок как SKIPPED.

Имя поля	Рекомендация
`trip`	Ссылаться на сообщение TripDescriptor.
	Если отдельный `VehiclePosition` и `TripUpdate` предоставляются, TripDescriptor и VehicleDescriptor Сопоставление значений ID должно совпадать между двумя фидами. Например, a `VehiclePosition` организация имеет `vehicle_id:A` и `trip_id:4`, то соответствующий `TripUpdate` сущность также должна иметь `vehicle_id:A` и `trip_id:4`. Если любой `TripUpdate` организация имеет `trip_id:4` и любой `vehicle_id` отличное от 4, это ошибка.
`vehicle`	Ссылаться на сообщение VehicleDescriptor.
	Если `VehiclePosition` и `TripUpdate` предоставляются отдельные фиды, TripDescriptor и VehicleDescriptor Сопоставление значений ID должно совпадать между двумя фидами. Например, у `VehiclePosition` объект имеет `vehicle_id:A` и `trip_id:4`, тогда соответствующая `TripUpdate` сущность также должна иметь `vehicle_id:A` и `trip_id:4`. если любой `TripUpdate` сущность имеет `trip_id:4` и любой `vehicle_id` отличных от 4, то это ошибка.
`stop_time_update`	`stop_time_updates` для данного `trip_id` должен быть строго упорядочен по возрастанию `stop_sequence` и не `stop_sequence` должно повторяться.
	Пока поездка находится в процессе, все `TripUpdates` должны включать, по крайней мере, один `stop_time_update` с прогнозируемым временем прибытия или отправления в будущем. Обратите внимание, что спецификацияGTFS Realtime гласит, что производители не должны сбрасывать прошедшее `StopTimeUpdate` если она относится к остановке с запланированным временем прибытия в будущем для данной поездки (т.е. транспортное средство проехало остановку раньше Schedule), поскольку в противном случае будет сделан вывод об отсутствии обновления для этой остановки.
`timestamp`	Должно отражать время обновления прогноза для данной поездки.
`delay`	`TripUpdate.delay` должно представлять отклонение от Schedule, т.е. наблюдаемое в прошлом значение того, насколько транспортное средство опережает/задерживается от Schedule. Прогнозы для будущих остановок должны быть предоставлены через `StopTimeEvent.delay` или `StopTimeEvent.time`.

TripDescriptor¶

Если предоставляются отдельные фиды VehiclePosition и TripUpdate, пары значений TripDescriptor и VehicleDescriptor ID должны совпадать между двумя фидами.

Например, объект VehiclePosition имеет vehicle_id:A и trip_id:4, тогда соответствующий объект TripUpdate также должен иметь vehicle_id:A и trip_id:4.

Имя поля	Рекомендация
`schedule_relationship`	Поведение `ADDED` поездки не определено, и использование этого перечисления не рекомендуется.

VehicleDescriptor¶

Если предоставляются отдельные каналы VehiclePosition и TripUpdate, сопряжение значений TripDescriptor и VehicleDescriptor ID должно совпадать между этими двумя каналами.

Например, сущность VehiclePosition имеет vehicle_id:A и trip_id:4, тогда соответствующая сущность TripUpdate также должна иметь vehicle_id:A и trip_id:4.

Имя поля	Рекомендация
`id`	Должен однозначно и стабильно идентифицировать транспортное средство в течение всего времени поездки

StopTimeUpdate¶

Имя поля	Рекомендация
`stop_sequence`	Указывать `stop_sequence` по возможности, так как оно однозначно разрешается на время остановки в GTFS в `stop_times.txt` в отличие от `stop_id`которые могут встречаться более одного раза за поездку (например, петлевой маршрут).
`arrival`	Время прибытия между последовательными остановками должно увеличиваться - оно не должно быть одинаковым или уменьшаться.
	Прибытие `time` (указано в StopTimeEvent) должно быть раньше отправления `time` для той же остановки, если ожидается стоянка или время пребывания - в противном случае, прибытие `time` должно быть таким же, как и отправление `time`.
`departure`	Время отправления между последовательными остановками должно увеличиваться - оно не должно быть одинаковым или уменьшаться.
	Время отправления `time` (указанное в StopTimeEvent) должно быть таким же, как и прибытие `time` для той же остановки, если не ожидается стоянка или время пребывания - в противном случае, отправление `time` должно быть после прибытия `time` .

StopTimeEvent¶

Имя поля Рекомендация

delay Если только delay предоставляется в stop_time_update arrival или departure (а не time), то GTFS stop_times.txt должна содержать arrival_times и/или departure_times для этих соответствующих остановок. A delay значение в фиде Realtime не имеет смысла, если у вас нет времени, к которому его можно добавить в GTFS. stop_times.txt файл.

VehiclePosition¶

Ниже перечислены рекомендуемые поля, которые должны быть включены в фид VehiclePostions для обеспечения потребителей высококачественными данными (например, для создания прогнозов).

Название поля	Примечания
`entity.id`	Должна поддерживаться стабильной в течение всего времени поездки
`vehicle.timestamp`	Настоятельно рекомендуется предоставлять метку времени, в которую было измерено положение транспортного средства. В противном случае потребители должны использовать временную метку сообщения, что может привести к недостоверным результатам для велосипедистов, если последнее сообщение обновлялось чаще, чем индивидуальное положение.
`vehicle.vehicle.id`	Должен однозначно и стабильно идентифицировать транспортное средство на протяжении всей поездки.

Положение¶

Положение транспортного средства должно находиться в пределах 200 метров от данных GTFS shapes.txt для текущей поездки, если только для этого trip_id нет предупреждения с эффектом DETOUR.

Оповещение¶

Общие рекомендации для оповещений:

Когда trip_id и start_time находятся в интервале exact_time=1, start_time должно быть позже начала интервала на величину, кратную headway_secs.
При отмене поездок в течение нескольких дней производители должны предоставить TripUpdates, ссылающиеся на данные trip_ids и start_dates как CANCELED, а также предупреждение с NO_SERVICE, ссылающееся на те же trip_ids и TimeRange, которое может быть показано пассажирам с объяснением отмены (например, объезд).
Если предупреждение затрагивает все остановки на линии, используйте предупреждение на основе линии вместо предупреждения на основе остановки. Не применяйте предупреждение к каждой остановке линии.
Хотя для сервисных оповещений нет ограничений по количеству символов, пассажиры часто просматривают оповещения на мобильных устройствах. Пожалуйста, будьте лаконичны.

Имя поля	Рекомендация
`description_text`	Используйте переносы строк, чтобы ваше сервисное оповещение было легче читать.

Практические рекомендации, упорядоченные по вариантам использования¶

Поездки на основе частоты¶

Поездка на основе частоты не следует фиксированному Schedule, но пытается поддерживать заранее установленные интервалы движения. Такие поездки обозначаются в файле GTFS.org/reference/static/#frequenciestxt">frequency.txtGTFS установкой exact_times=0 или отсутствием поля exact_times (обратите внимание, что поездки с exact_times=1 НЕ являются поездками на основе частоты - файл frequencies.txt с exact_times=1 просто используется как удобный метод хранения поездок Schedule в более компактной форме). Есть несколько лучших практик, о которых следует помнить при создании GTFS Realtime фидов для поездок на основе частот.

В TripUpdate.StopTimeUpdate событие StopTimeEvent для прибытия и отправления не должно содержать задержку, поскольку поездки на основе частот не следуют фиксированному Schedule. Вместо этого следует указать время для прогноза прибытия/отправления.
Согласно требованиям спецификации, при описании поездки в TripUpdate или VehiclePosition с помощью TripDescriptor, должны быть предоставлены все данные trip_id, start_time и start_date. Кроме того, schedule_relationship должно быть UNSCHEDULED.

(например, повторные поездки).

О данном документе¶

Цели¶

Целями поддержания лучшей практики GTFS Realtime являются:

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

Как предлагать или изменять опубликованные лучшие практики GTFS Realtime.¶

Приложения и практикаGTFS развиваются, поэтому в данный документ время от времени могут вноситься поправки. Чтобы предложить поправку к этому документу, откройте запрос на исправление в репозитории GTFS Realtime Best Practices на GitHub и выступите за изменение.

Ссылка на данный документ¶

Пожалуйста, размещайте здесь ссылки, чтобы предоставить производителям кормов руководство для правильного формирования данных GTFS Realtime. Каждая отдельная рекомендация имеет якорную ссылку. Щелкните на рекомендации, чтобы получить URL-адрес для ссылки на страницу.

Если приложение, Realtime данные GTFS Realtime, предъявляет требования или рекомендации к практике формирования данных GTFS Realtime, которые не описаны здесь, рекомендуется опубликовать документ с такими требованиями или рекомендациями, чтобы дополнить эти общие лучшие практики.