Rozszerzenia Google Transit dotyczące sprzedaży biletów

Ta strona definiuje podzbiór specyfikacji GTFS-Ticketing, która w momencie tworzenia tego dokumentu jest na etapie propozycji. Na tej stronie znajdziesz też kilka dodatkowych ograniczeń narzuconych przez Google.

Wymagania

Pole departure_time w sekcji stop_times.txt jest wymagane.

Dodatkowe typy pól

W tej sekcji opisujemy dodatkowe typy pól i pola z rozszerzeniami Google. Niektóre pola wymagają wartości w postaci identyfikatora URI.

  • Identyfikator URI: pełny identyfikator URI, który zawiera schemat. Znaki specjalne w URI muszą zawierać odpowiednie kody zmiany znaczenia. Aby dowiedzieć się, jak tworzyć wartości pełnych adresów URI, zapoznaj się z dokumentem RFC 3986 Uniform Resource Identifier (URI): Generic Syntax (Identyfikator Uniform Resource Identifier (URI): składnia ogólna).

Rozszerzenia plików lub dodatki

Pliki tekstowe o stanie Rozszerzenie to pliki, które już istnieją i które trzeba rozszerzyć. Musisz dodać nowe pola zdefiniowane w tabeli poniżej.

Pliki tekstowe ze stanem Dodawanie to nowe pliki wprowadzone przez rozszerzenia Google Transit Ticketing. Te pliki musisz utworzyć zgodnie z definicjami pól podanymi w tabeli poniżej. Pamiętaj, aby uwzględnić te pliki w pliku danych.

Nazwa pliku Stan Określa
agency.txt Rozszerzenie Dodaje agency.ticketing_deep_link_id.
routes.txt Rozszerzenie Dodaje routes.ticketing_deep_link_id.
trips.txt Rozszerzenie Dodaje trips.ticketing_trip_id i trips.ticketing_type.
stop_times.txt Rozszerzenie Dodaje stop_times.ticketing_type.
ticketing_identifiers.txt Dodanie Nowy plik. Więcej informacji znajdziesz w definicjach pól.
ticketing_deep_links.txt Dodanie Nowy plik. Więcej informacji znajdziesz w definicjach pól.

Definicje pól

agency.txt (plik rozszerzony)

Nazwa pola Obecność Szczegóły
ticketing_deep_link_id Opcjonalnie

(Identyfikator z ticketing_deep_links.txt) Określa precyzyjny link do użycia w przypadku tej agencji. Można je zastąpić w routes.txt.

routes.txt (plik rozszerzony)

Nazwa pola Obecność Szczegóły
ticketing_deep_link_id Opcjonalnie (identyfikator z ticketing_deep_links.txt) Określa precyzyjny link do użycia na potrzeby tej trasy. Jeśli jest podany, zastępuje pole w agency.txt.

trips.txt (plik rozszerzony)

Nazwa pola Obecność Szczegóły
ticketing_trip_id Opcjonalnie

(ID) Identyfikator do przekazania w precyzyjnym linku. Nie musi być unikalna.

Jeśli wartość ticketing_trip_id jest pusta, system używa zamiast niej wartości trip_id.
ticketing_type Opcjonalnie

(Enum) Określ, czy w przypadku tej podróży dostępna jest sprzedaż biletów za pomocą precyzyjnego linku:

  • 0 lub puste:
    • Jeśli zdefiniujesz ticketing_deep_link_id dla trasy lub agencji, będzie to możliwe.
    • W innym przypadku niedostępny.
  • 1: niedostępne.

stop_times.txt (plik rozszerzony)

Nazwa pola Obecność Szczegóły
ticketing_type Opcjonalnie

(Wyliczenie) Określa, czy w przypadku tego czasu przystanku dostępne są bilety przez precyzyjny link. Jeśli zdefiniujesz parametr stop_times.ticketing_type, zastąpi on wartość ustawioną w parametrze trip.ticketing_type.

  • Pusty: używa wartości z trip.ticketing_type.
  • 0:
    • Jeśli zdefiniujesz ticketing_deep_link_id dla trasy lub agencji, będzie to możliwe.
    • W innym przypadku niedostępny.
  • 1: niedostępne.

ticketing_identifiers.txt (dodano plik)

Najczęstszym przypadkiem dotyczącym biletów jest to, że każde zatrzymanie ma identyfikator do przetwarzania płatności. Różne agencje mogą używać tego samego identyfikatora w przypadku dowolnego przystanku. Jeśli wiele agencji obsługuje to samo miejsce docelowe, powtórz to mapowanie dla każdej agencji.

Nazwa pola Obecność Szczegóły
ticketing_stop_id Wymagany (ID) Definiuje domyślny identyfikator biletu dla tego przystanku w przypadku tej agencji.
stop_id Wymagany (Identyfikator z stops.txt) Punkt, dla którego zdefiniowano domyślny parametr ticketing_stop_id.
agency_id Wymagany (Identyfikator z agency.txt) Agencja przystanku, dla którego zdefiniowano domyślną wartość ticketing_stop_id.

ticketing_deep_links.txt (dodano plik)

Nazwa pola Obecność Szczegóły
ticketing_deep_link_id Wymagany (ID) Określa identyfikator precyzyjnego linku.
web_url Opcjonalnie

(URL) Adres URL, który należy odwiedzić, aby utworzyć precyzyjny link.

Tego pola nie można przetłumaczyć za pomocą funkcji translations.txt.
android_intent_uri Opcjonalnie

(URI) Identyfikator URI do przekazania do natywnej aplikacji na Androida z zastosowaniem intencji android.intent.action.VIEW.

Jeśli jest pusty, oznacza to, że nie możesz utworzyć precyzyjnego linku do natywnej aplikacji na Androida.

Więcej informacji o precyzyjnych linkach na Androida znajdziesz w artykule Tworzenie precyzyjnych linków do treści w aplikacji.

Tego pola nie można przetłumaczyć za pomocą funkcji translations.txt.
ios_universal_link_url Opcjonalnie

(URL) Adres URL uniwersalnego linku do wywołania na iOS.

Jeśli jest pusty, precyzyjne linki nie będą wyświetlane w iOS.

Więcej informacji znajdziesz w artykule Linki uniwersalne na iOS.

Tego pola nie można przetłumaczyć za pomocą funkcji translations.txt.

Obiekty zastępcze pól w wywołaniu interfejsu API

Google wywołuje adresy URL zdefiniowane w parametrze ticketing_deep_links.txt z tymi parametrami:

Nazwa pola Szczegóły
service_date

(Data, powtarzalna) Dzień wykonania usługi w ramach podróży.

Użyj tego pola, aby podać datę wyjazdu z pierwszego przystanku.

To pole jest formatowane jako tablica JSON.
ticketing_trip_id

(identyfikator z trips.txt, powtarzalny) Identyfikator podróży.

To pole jest formatowane jako tablica JSON.
from_ticketing_stop_time_id

(powtarzalny) Identyfikator stop_time, od którego rozpoczyna się etap.

W przypadku konkretnego czasu zatrzymania wartość jest następująca:

  • ticketing_stop_id zdefiniowany w ticketing_identifiers.txt dla agency_id i stop_id w stop_time.

  • W przeciwnym razie używa wartości stop_sequence.

To pole jest formatowane jako tablica JSON.
to_ticketing_stop_time_id

(powtarzalny) Identyfikator stop_time, w którym kończy się etap.

Wyjaśnienie pochodzenia wartości znajdziesz w sekcji from_ticketing_stop_time_id.

To pole jest formatowane jako tablica JSON.
boarding_time

(ISO 8601, powtarzalny) Czas wylotu, departure_time, lotu stop_time, w którym rozpoczyna się odcinek.

Użyj tego pola, aby podać rzeczywistą datę i godzinę, kiedy pasażer wsiadł do pojazdu.

Wartość czasu w tym polu jest zgodna ze standardem ISO 8601 i ma następujący format ciągu znaków:

YYYY-MM-DDThh:mm:ss±hh:mm

Wszystkie podane niżej godziny są takie same, ale w różnych strefach czasowych:

  • W Londynie (Wielka Brytania): 2019-07-29T18:26:00+01:00
  • W Nowym Jorku, stan Nowy Jork, USA: 2019-07-29T13:26:00-04:00
  • W Tokio, Japonia: 2019-07-30T02:26:00+09:00

To pole jest formatowane jako tablica JSON.
arrival_time

(ISO 8601, powtarzalny) Czas przybycia, arrival_time w stop_time, w którym kończy się odcinek.

Wartość czasu w tym polu jest zgodna ze standardem ISO 8601 i ma postać ciągu znaków:

YYYY-MM-DDThh:mm:ss±,hh:mm

Wszystkie podane niżej godziny są takie same, ale w różnych strefach czasowych:

  • W Londynie (Wielka Brytania): 2019-07-29T18:46:00+01:00
  • W Nowym Jorku, Stany Zjednoczone: 2019-07-29T13:46:00-04:00
  • W Tokio (Japonia): 2019-07-30T02:46:00+09:00

To pole jest formatowane jako tablica JSON.

Przykłady

W tym przykładzie przejazd pasażera składa się z tych odcinków:

  • W dniu świadczenia usługi 20190716 identyfikator biletu na przejazd ti1 zaczyna się od identyfikatora czasu zatrzymywania 11 do identyfikatora czasu zatrzymywania 12. Pasażer wsiada o 20:00 czasu UTC i dojeżdża o 20:50 czasu UTC.
  • W dniu świadczenia usługi 20190716 identyfikator biletu na przejazd ti2 zaczyna się od identyfikatora czasu zatrzymywania 21 do identyfikatora czasu zatrzymywania 22. Pasażer wsiada o 15:00 UTC i dojeżdża o 15:50 UTC.

W tym przykładzie web_url to https://examplepetstore.com.

Mając te wszystkie informacje, użyj tych wartości w parametrach pliku danych dla tej podróży:

Nazwa pola Szczegóły
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"]

Oto końcowy identyfikator URI po zakodowaniu:

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

Przykłady różnych wartości parametru ticketing_stop_id

Przystanki mogą mieć różne identyfikatory na potrzeby wystawiania biletów za pomocą pola ticketing_identifiers.txt. Wartości w grubej czcionce pochodzą z wywołania internetowego opisanego po plikach.

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

Jeśli prośba została wysłana 19 lipca 2019 r., a czas w GTFS jest podany w strefie czasowej UTC+1, wywołanie w internecie będzie wyglądać tak:

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

Aby wdrożyć rozszerzenia Google Transit dotyczące biletów:

Wytyczne
W miarę możliwości udostępniaj precyzyjne linki między agencjami lub trasami.

W pliku danych statycznych, gdy wiele agencji lub tras ma te same adresy URL linków szczegółowych, muszą one mieć tę samą wartość w polu ticketing_deep_link_id. Umożliwia to przenoszenie między agencjami lub trasami.
Ustaw spójne wartości atrybutu ticketing_type.

Wartość ticketing_type dla danego przystanku musi być taka sama we wszystkich wierszach pliku stop_times.txt.
Mapuj ticketing_stop_id zarówno dla przystanków nadrzędnych, jak i podrzędnych. Przeprowadź mapowanie wszystkich przystanków nadrzędnych i podrzędnych, które wymagają biletowania. W pliku ticketing_identifiers.txt wartości ticketing_stop_id nie są propagowane między przystankiem nadrzędnym a jego podrzędnymi.
Zamapuj ticketing_stop_id dla każdej agencji, która używa tego samego przystanku w pliku danych.

Jeśli w pliku danych statycznych wiele agencji, które umożliwiają sprzedaż biletów, udostępnia ten sam przystanek, mapowanie musi być obecne w przypadku każdej z tych agencji.

Więcej informacji znajdziesz w sekcji Definicje pól dotyczącej pola ticketing_identifiers.txt.
Używaj linków aplikacji na Androida, gdy potrzebny jest precyzyjny link do aplikacji na Androida.

Jeśli partner chce otworzyć aplikację na Androida z poziomu precyzyjnego linku, skonfiguruj precyzyjny link jako link do aplikacji na Androida.
Używaj uniwersalnych linków iOS, gdy potrzebny jest precyzyjny link do aplikacji na iOS. Jeśli partner chce otworzyć aplikację na iOS za pomocą precyzyjnego linku, skonfiguruj precyzyjny link jako uniwersalny link na iOS.