Расширения Google Транспорта для продажи билетов

На этой странице представлена спецификация GTFS Ticketing, которая на момент создания документа рассматривается как предложение. Также, здесь приведены несколько дополнительных ограничений от Google.

Требования

Поле departure_time в файле stop_times.txt является обязательным.

Дополнительные типы полей

В этом разделе описаны дополнительные типы полей, а также поля с расширениями от Google. В некоторых полях требуются значения в форме URI.

• URI – унифицированный идентификатор ресурсов, включающий схему. Любые специальные символы в URI должны быть экранированы. Чтобы узнать, как правильно составить URI, прочитайте документ Унифицированный идентификатор ресурса: общий синтаксис (RFC 3986).

Расширения или добавления в файлах

Текстовые файлы со статусом Расширение – это существующие файлы, которые необходимо расширить. Вы должны добавить новые поля, определенные в таблице ниже.

Текстовые файлы со статусом Добавление – это новые файлы, представленные в расширениях Google Транспорта для продажи билетов. Вы должны создать эти файлы в соответствии с определениями полей, приведенными ниже. Обязательно добавьте эти файлы в свой фид.

Название файла	Статус	Что определяет
agency.txt	Расширение	Добавляет agency.ticketing_deep_link_id.
routes.txt	Расширение	Добавляет routes.ticketing_deep_link_id.
trips.txt	Расширение	Добавляет trips.trip_ticketing_id и trips.ticketing_type.
stop_times.txt	Расширение	Добавляет stop_times.ticketing_type.
ticketing_identifiers.txt	Добавление	Новый файл. См. определения полей.
ticketing_deep_links.txt	Добавление	Новый файл. См. определения полей.

Определения полей

agency.txt (используется расширение)

Название поля	Тип поля	Описание
ticketing_deep_link_id	Необязательное	Идентификатор из файла ticketing_deep_links.txt. Определяет ссылку на контент, используемую для этого агентства. Поле может быть перезаписано в файле routes.txt. Примечание. Чтобы применить функцию продажи билетов ко всему фиду статических данных, укажите в поле ticketing_deep_link_id файла agency.txt одинаковое значение для всех агентств.

routes.txt (используется расширение)

Название поля	Тип поля	Описание
ticketing_deep_link_id	Необязательное	Идентификатор из файла ticketing_deep_links.txt. Определяет ссылку на контент, используемую для этого маршрута. Если присутствует, перезаписывает поле в файле agency.txt.

trips.txt (используется расширение)

Название поля	Тип поля	Описание
ticketing_trip_id	Необязательное	Идентификатор, используемый в ссылке на контент. Не требуется, чтобы он был уникальным. Если значение ticketing_trip_id не задано, вместо него используется trip_id.
ticketing_type	Необязательное	Перечисление, которое определяет, доступна ли для этого рейса продажа билетов по ссылке на контент. 0 или пустое значение: Доступна, если поле ticketing_deep_link_id определено для маршрута или агентства. Недоступна в других случаях. 1: недоступна.

stop_times.txt (используется расширение)

Название поля	Тип поля	Описание
ticketing_type	Необязательное	Перечисление, которое определяет, доступна ли для этого времени остановки продажа билетов по ссылке на контент. Если поле stop_times.ticketing_type используется, оно переопределяет значение, заданное в поле trip.ticketing_type. Пустое значение: используется значение поля trip.ticketing_type. 0: Доступна, если поле ticketing_deep_link_id определено для маршрута или агентства. Недоступна в других случаях. 1: недоступна. Важно! Если у одного из параметров stop_times для stop_id задано значение ticketing_type=1, то и у всех остальных параметров stop_times также должно быть ticketing_type=1.

ticketing_identifiers.txt (используется добавление)

Самый распространенный вариант продажи билетов реализуется следующим образом: для каждой остановки задается идентификатор, используемый для обработки платежей. Если разные агентства используют одинаковый идентификатор для обозначения определенной остановки, то нужно повторить настройку этого параметра для каждого из таких агентств.

Название поля	Тип поля	Описание
ticketing_stop_id	Обязательное	Идентификатор. Определяет идентификатор продажи билетов по умолчанию, используемый для определенной остановки в конкретном агентстве.
stop_id	Обязательное	Идентификатор из файла stops.txt. Обозначает остановку, для которой задан параметр ticketing_stop_id по умолчанию.
agency_id	Обязательное	Идентификатор из файла agency.txt. Обозначает агентство, использующее остановку, для которой задан параметр ticketing_stop_id по умолчанию.

ticketing_deep_links.txt (используется добавление)

Название поля	Тип поля	Описание
ticketing_deep_link_id	Обязательное	Идентификатор. Определяет идентификатор для ссылки на контент.
web_url	Необязательное	URL, который используется для перехода по ссылке на контент. Содержимое этого поля нельзя перевести с помощью файла translations.txt. Важно! Для этого поля не поддерживается функция перевода по URL. Поэтому язык должен быть определен принимающими сайтами или приложениями.
android_intent_uri	Необязательное	Идентификатор URI, используемый для приложений Android с действием android.intent.action.VIEW. Пустое поле означает отсутствие ссылки на контент приложения для Android. Важно! Для этого поля не поддерживается функция перевода по URL. Поэтому язык должен быть определен принимающими сайтами или приложениями. Подробнее о том, как создавать ссылки на контент приложения для Android… Рекомендация. Используйте безопасную функцию Android App Links, в которой успешно реализована защита от сбоев в случае, когда на устройстве пассажира нет приложения для Android. Содержимое этого поля нельзя перевести с помощью файла translations.txt.
ios_universal_link_url	Необязательное	URL универсальной ссылки для iOS. Важно! Для этого поля не поддерживается функция перевода по URL. Поэтому язык должен быть определен принимающими сайтами или приложениями. Если значение не указано, ссылки на контент не показываются на платформе iOS. Подробнее об iOS Universal Links… Содержимое этого поля нельзя перевести с помощью файла translations.txt.

Примечание. Если для нескольких агентств или маршрутов используются одинаковые URL ссылок на контент, мы настоятельно рекомендуем настроить только одну ссылку и привязать к ней все эти агентства и маршруты. Подробная информация приведена в разделе Рекомендации.

Теги полей для вызова API

Google вызывает URL, определенные в файле ticketing_deep_links.txt, со следующими параметрами:

Название поля	Описание
service_date	День обслуживания рейса (дата, повторяющиеся данные). Формат этого поля соответствует массиву JSON.
ticketing_trip_id	Идентификатор рейса из файла trips.txt (повторяющиеся данные). Формат этого поля соответствует массиву JSON.
from_ticketing_stop_time_id	Идентификатор времени остановки (stop_time) в начале отрезка маршрута (повторяющиеся данные). Значение времени остановки задается следующим образом: Используется значение идентификатора ticketing_stop_id, определенное в файле ticketing_identifiers.txt для идентификаторов agency_id и stop_id параметра stop_time. Важно! Параметры ticketing_identifiers используются только для самой остановки. Идентификаторы ticketing_identifiers родительской остановки не будут учитываться. В качестве резервного варианта используется параметр stop_sequence. Формат этого поля соответствует массиву JSON.
to_ticketing_stop_time_id	Идентификатор времени остановки (stop_time) в конце отрезка маршрута (повторяющиеся данные). Значение для этого параметра определяется так же, как и для поля from_ticketing_stop_time_id. Формат этого поля соответствует массиву JSON.
boarding_time	Время отправления (departure_time) для параметра stop_time в начале отрезка пути (ISO 8601, повторяющиеся данные). Значение времени для этого поля соответствует стандарту ISO 8601. Используется следующий формат: YYYY-MM-DDThh:mm:ss±hh:mm Ниже указано одно и то же время для разных часовых поясов: Лондон, Великобритания: 2019-07-29T18:26:00+01:00 Нью-Йорк, США: 2019-07-29T13:26:00-04:00 Токио, Япония: 2019-07-30T02:26:00+09:00 Важно! Часовой пояс не обязательно должен совпадать с тем, который указан для агентства в фиде. Для обозначения времени в разных часовых поясах используется стандарт UTC. Формат этого поля соответствует массиву JSON.
arrival_time	Время прибытия (arrival_time) для параметра stop_time в конце отрезка пути (ISO 8601, повторяющиеся данные). Значение времени для этого поля соответствует стандарту ISO 8601. Используется следующий формат: YYYY-MM-DDThh:mm:ss±,hh:mm Ниже указано одно и то же время для разных часовых поясов: Лондон, Великобритания: 2019-07-29T18:46:00+01:00 Нью-Йорк, США: 2019-07-29T13:46:00-04:00 Токио, Япония: 2019-07-30T02:46:00+09:00 Важно! Часовой пояс не обязательно должен совпадать с тем, который указан для агентства в фиде. Для обозначения времени в разных часовых поясах используется стандарт UTC. Формат этого поля соответствует массиву JSON.

Примеры

Исходные данные по отрезкам маршрута:

• Дата обслуживания – 20190716, идентификатор рейса – ti1, идентификатор времени остановки в начале отрезка маршрута – 11, идентификатор времени остановки в конце отрезка маршрута – 12. Пассажир садится в транспортное средство в 14:00 (UTC) и прибывает в 14:50 (UTC).
• Дата обслуживания – 20190716, идентификатор рейса – ti2, идентификатор времени остановки в начале отрезка маршрута – 21, идентификатор времени остановки в конце отрезка маршрута – 22. Пассажир садится в транспортное средство в 15:00 (UTC) и прибывает в 15:50 (UTC).

Сайт бронирования (web_url): https://examplepetstore.com.

Значения параметров:

Название поля	Описание
service_date	["20190716", "20190716"]
ticketing_trip_id	["ti1", "ti2"]
from_ticketing_stop_time_id	["11", "21"]
to_ticketing_stop_time_id	["12", "22"]
boarding_time	["2019-07-16T14:00:00+00:00", "2019-07-16T15:00:00+00:00"]
arrival_time	["2019-07-16T14:50:00+00:00", "2019-07-16T15:50:00+00:00"]

Конечный URI (после кодирования):

https://examplepetstore.com?service_date=%5B%2220190716%22,%2220190716%22%5D &ticketing_trip_id=%5B%22ti1%22,%22ti2%22%5D&from_ticketing_stop_time_id=%5B%2211%22,%2221%22%5D &to_ticketing_stop_time_id=%5B%2212%22,%2222%22%5D&boarding_time=%5B%222019-07-16T14:00:00%2B00:00 %22,%222019-07-16T15:00:00%2B00:00%22%5D&arrival_time=%5B%222019-07-16T14:50:00%2B00:00 %22,%222019-07-16T15:50:00%2B00:00%22%5D

Примеры разных значений параметра ticketing_stop_id

У остановок могут быть разные идентификаторы при использовании полей из файла ticketing_identifiers.txt. Ниже жирным шрифтом выделены примеры таких значений.

stop.txt
stop_id,stop_name si1,"Paris Gare-de-Lyon" si2,"Lyon Part-Dieu"

routes.txt
route_id,route_long_name,ticketing_deep_link_id ri1,"TGV inOui Paris-Lyon",tdl1

trips.txt
trip_id,service_id,route_id,trip_short_name, ticketing_trip_id ti1,everyday,ri1,"TGV INOUI 6603",FR_SNCF_6603 ti2,everyday,ri1,"TGV INOUI 6681",FR_SNCF_6681 ti3,everyday,ri1,"TGV INOUI 6607",FR_SNCF_6607

stop_times.txt
trip_id,stop_sequence,stop_id,arrival_time, departure_time ti1,1,si1,06:59:00,06:59:00 ti1,2,si2,08:56:00,08:56:00 ti2,1,si1,07:53:00,07:53:00 ti2,2,si2,10:00:00,10:00:00 ti3,1,si1,08:59:00,08:59:00 ti3,2,si2,10:56:00,10:56:00

ticketing_identifiers.txt
stop_id,agency_id,ticketing_stop_id si1,agency1,4924 si2,agency1,4676

ticketing_deep_links.txt
ticketing_deep_link_id, web_url, android_intent_uri, ios_universal_link_url tdl1, https://examplepetstore.com/api/gtfs/web, https://examplepetstore.com/api/gtfs/android, https://examplepetstore.com/api/gtfs/ios

Если запрос выполнен 19 июля 2019 г., а время для GTFS указывается в формате UTC+1, то финальный URL будет иметь следующий вид:

https://examplepetstore.com/api/gtfs/web?service_date=%5B%2220190719%22%5D&ticketing_trip_id= %5B%22FR_SNCF_6603%22%5D&from_ticketing_stop_time_id=%5B%224924%22%5D&to_ticketing_stop_time_id= %5B%224676%22%5D&boarding_time=%5B%222019-07-19T05:59:00%2B00:00%22%5&arrival_time=%5B%222019-07-19T07:56:00%2B00:00%22%5D

Важно! Значения boarding_time и arrival_time, для которых используется UTC, могут не переводиться в часовой пояс GTFS (UTC+1). Это вызовет сдвиг значения HH:MM:SS.

Рекомендации

При внедрении расширений Google Транспорта для продажи билетов следуйте приведенным ниже рекомендациям.

Рекомендации
По возможности используйте одинаковые ссылки на контент для всех агентств и маршрутов.	Если в фиде статических данных для нескольких агентств или маршрутов используются одинаковые URL ссылок на контент, то в поле ticketing_deep_link_id должно быть указано одно и то же значение. Это позволит включать пересадки между агентствами и маршрутами. Примечание. В противном случае из-за разных значений в поле ticketing_deep_link_id пассажир должен будет купить два отдельных билета.
Согласуйте значения ticketing_type.	В файле stop_times.txt во всех строках должно быть указано одно и то же значение поля ticketing_type для определенной остановки. Примечание. Если в поле ticketing_type задано значение 1, то покупка билетов для всех рейсов с этой остановкой будет недоступна.
Сопоставьте значения ticketing_stop_id для родительских и дочерних остановок.	Выполните сопоставление для всех родительских и дочерних остановок, включенных в продажу билетов. В файле ticketing_identifiers.txt значения ticketing_stop_id не передаются между родительскими и их дочерними остановками.
Сопоставьте значения ticketing_stop_id для всех агентств, использующих эту остановку в фиде.	Если несколько агентств с продажей билетов используют в фиде статических данных одну и ту же остановку, то сопоставление должно быть выполнено для всех этих агентств. Подробная информация приведена в разделе Определения полей (ticketing_identifiers.txt).
Если требуется ссылка на контент приложения для Android, используйте Android App Links.	Если партнер хочет, чтобы по ссылке на контент открывалось приложение для Android, настройте ее с помощью Android App Links. Примечание. Если партнер хочет направлять пользователей только на мобильный сайт, укажите URL сайта.
Если требуется ссылка на контент приложения для iOS, используйте iOS Universal Links.	Если партнер хочет, чтобы по ссылке на контент открывалось приложение для iOS, настройте ее с помощью iOS Universal Links.