Rozszerzenia dotyczące sprzedaży biletów w środkach transportu publicznego Google

Ta strona definiuje podzbiór specyfikacji biletów GTFS, który znajduje się na etapie składania oferty podczas tworzenia tego dokumentu. Na tej stronie znajduje się też kilka dodatkowych ograniczeń Google.

Wymagania

Pole departure_time w tabeli stop_times.txt jest wymagane.

Dodatkowe typy pól

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

• Identyfikator URI: w pełni i jednoznaczny identyfikator URI zawierający schemat. Wszystkie znaki specjalne w identyfikatorze URI muszą używać odpowiednich znaków zmiany znaczenia. Opis tworzenia w pełni kwalifikowanych wartości identyfikatorów URI znajdziesz w dokumencie RFC 3986 Uniform Resource Identifier (identyfikator URI): składnia ogólna.

Rozszerzenia plików lub dodatki

Pliki tekstowe ze stanem Rozszerzenie to już istniejące i które trzeba rozszerzyć. Musisz dodać nowe pola zdefiniowane w tabeli poniżej.

Pliki tekstowe ze stanem Addition (dodawanie) to nowe pliki wprowadzone przez rozszerzenia Google do sprzedaży biletów na przejazdy transportem publicznym. Musisz utworzyć te pliki zgodnie z definicjami pól podanymi po poniższej tabeli. Pamiętaj, aby uwzględnić te pliki w swoim pliku danych.

Nazwa pliku	Stan	Definiuje
agency.txt	Rozszerzenie	Dodaje agency.ticketing_deep_link_id.
routes.txt	Rozszerzenie	Dodaje routes.ticketing_deep_link_id.
trips.txt	Rozszerzenie	Dodaje trips.trip_ticketing_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 sekcji Definicje pól.
ticketing_deep_links.txt	Dodanie	Nowy plik. Więcej informacji znajdziesz w sekcji Definicje 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, którego chcesz używać w przypadku tej agencji. Można ją zastąpić w polu routes.txt. Uwaga: aby zastosować sprzedaż biletów do całego statycznego pliku danych, ustaw tę samą wartość w polu ticketing_deep_link_id dla wszystkich agencji w pliku agency.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 w przypadku tej trasy. Jeśli istnieje, zastępuje pole w agency.txt.

trips.txt (plik rozszerzony)

Nazwa pola	Obecność	Szczegóły
ticketing_trip_id	Opcjonalnie	(Identyfikator) Identyfikator przekazywany w precyzyjnym linku. Nie musi być niepowtarzalna. Jeśli pole ticketing_trip_id jest puste, system używa w zamian 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: Pole 0 lub puste: Jeśli określisz właściwość ticketing_deep_link_id dla trasy lub agencji, jest ona dostępna. W innym przypadku niedostępne. 1: niedostępne.

stop_times.txt (plik rozszerzony)

Nazwa pola	Obecność	Szczegóły
ticketing_type	Opcjonalnie	(Enum) Określa, czy w danym czasie zatrzymania jest dostępna sprzedaż biletów za pomocą precyzyjnego linku. Jeśli określisz właściwość stop_times.ticketing_type, zastąpi ona wartość ustawioną w trip.ticketing_type. Brak wartości: używana jest wartość z trip.ticketing_type. 0: Jeśli określisz właściwość ticketing_deep_link_id dla trasy lub agencji, jest ona dostępna. W innym przypadku niedostępne. 1: niedostępne. Ważne: jeśli któryś z elementów stop_times ma wartość ticketing_type=1, to wszystkie pozostałe stop_times także muszą zawierać ticketing_type=1. stop_id

ticketing_identifiers.txt (dodano plik)

Najczęstszym przypadkiem sprzedaży biletów jest to, że każdy przystanek ma identyfikator przetwarzający płatność. Różne agencje mogą używać tego samego identyfikatora dla każdego przystanku. Jeśli wiele agencji obsługuje to samo przystanek, powtórz to mapowanie dla każdej z nich.

Nazwa pola	Obecność	Szczegóły
ticketing_stop_id	Wymagany	(ID) Definiuje domyślny identyfikator biletów dla tego przystanku dla tej agencji.
stop_id	Wymagany	(Identyfikator z stops.txt) Przystanek, dla którego zdefiniowano domyślną wartość 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 otworzyć, aby utworzyć precyzyjne linki. Tego pola nie można przetłumaczyć w języku translations.txt. Ważne: nie ma obsługi tłumaczenia adresu URL tego pola, więc wykrycie języka musi zostać wykonane przez witrynę lub aplikację docelową.
android_intent_uri	Opcjonalnie	(Identyfikator URI) Identyfikator URI przekazywany do natywnej aplikacji na Androida z intencją android.intent.action.VIEW. Jeśli pole jest puste, nie można utworzyć precyzyjnego linku do natywnej aplikacji na Androida. Ważne: nie ma obsługi tłumaczenia adresu URL tego pola, więc wykrycie języka musi zostać wykonane przez witrynę lub aplikację docelową. Więcej informacji o precyzyjnych linkach na Androidzie znajdziesz w artykule Tworzenie precyzyjnych linków do treści aplikacji. Zalecenie: używaj linków aplikacji na Androida, które są bezpieczniejsze i działają lepiej, gdy pasażer nie ma na swoim urządzeniu natywnej aplikacji na Androida. Tego pola nie można przetłumaczyć w języku translations.txt.
ios_universal_link_url	Opcjonalnie	(URL) Uniwersalny adres URL linku do wywołania w iOS. Ważne: nie ma obsługi tłumaczenia adresu URL tego pola, więc wykrycie języka musi zostać wykonane przez witrynę lub aplikację docelową. Jeśli pole jest puste, precyzyjne linki nie wyświetlają się w iOS. Więcej informacji znajdziesz w artykule Uniwersalne linki na iOS. Tego pola nie można przetłumaczyć w języku translations.txt.

Uwaga: jeśli wiele agencji lub tras ma te same adresy URL precyzyjnych linków w pliku danych, zdecydowanie zalecamy zdefiniowanie tylko 1 precyzyjnego linku i połączenie wszystkich tych agencji lub tras do tego samego precyzyjnego linku. Więcej informacji znajdziesz w sekcji Zalecane metody.

Zmienne pól w wywołaniu interfejsu API

Google wywołuje adresy URL zdefiniowane w zasadzie ticketing_deep_links.txt za pomocą tych parametrów:

Nazwa pola	Szczegóły
service_date	(Data, powtarzalny) Dzień obsługi klienta podczas podróży. Użyj tego pola w przypadku daty rozpoczęcia podróży z pierwszego przystanku. To pole formatuje się jako tablica JSON.
ticketing_trip_id	(Identyfikator z trips.txt, powtarzalny) Identyfikator podróży. To pole formatuje się jako tablica JSON.
from_ticketing_stop_time_id	(Powtarzalny) Identyfikator stop_time, w którym zaczyna się noga. Określony czas zakończenia ma taką wartość: ticketing_stop_id zdefiniowana w polu ticketing_identifiers.txt dla właściwości agency_id i stop_id elementu stop_time. Ważne: używany jest tylko ticketing_identifiers dla samego przystanku. Nawet jeśli przystanek ma przystanek nadrzędny, ignorujemy ticketing_identifiers jego przystanku. W przeciwnym razie przypada na stop_sequence. To pole formatuje się jako tablica JSON.
to_ticketing_stop_time_id	(Powtarzalny) Identyfikator stop_time, w którym kończy się noga. Wyjaśnienie dotyczące pochodnej wartości znajdziesz w sekcji from_ticketing_stop_time_id. To pole formatuje się jako tablica JSON.
boarding_time	(ISO 8601, powtarzalny) Godzina wyjazdu, departure_time, stop_time, o którym zaczyna się etap. W tym polu podaj rzeczywistą datę i godzinę wejścia do pojazdu przez pasażera. Wartość czasu w tym polu jest zgodna z normą 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 i dotyczą różnych stref czasowych: W Londynie, w Wielkiej Brytanii: 2019-07-29T18:26:00+01:00 Z Nowego Jorku, USA: 2019-07-29T13:26:00-04:00 W Tokio, Japonia: 2019-07-30T02:26:00+09:00 Ważne: strefa czasowa podana w pliku danych nie musi być taka sama jak strefa czasowa agencji. Strefa czasowa jest podana w strefie czasowej UTC. To pole formatuje się jako tablica JSON.
arrival_time	(ISO 8601, powtarzalny) Godzina przyjazdu, godzina przyjazdu w punkcie_stop_stopnia, w którym kończy się etap. Wartość czasu w tym polu jest zgodna z normą ISO 8601 o następującym formacie ciągu znaków: YYYY-MM-DDThh:mm:ss±,hh:mm Wszystkie podane niżej godziny są takie same i dotyczą różnych stref czasowych: W Londynie, Wielka Brytania: 2019.07-29T18:46:00+01:00 W Nowym Jorku, USA: 2019-07-29T13:46:00-04:00 W Tokio, Japonia: 2019-07-30T02:46:00+09:00 Ważne: strefa czasowa podana w pliku danych nie musi być taka sama jak strefa czasowa agencji. Strefa czasowa jest podana w strefie czasowej UTC. To pole formatuje się jako tablica JSON.

Przykłady

W tym przykładzie są to etapy podróży pasażera:

• W dniu świadczenia usługi 20190716 identyfikator biletu na podróż ti1 rozpoczyna się od identyfikatora biletu w czasie zatrzymania 11, aby zatrzymać sprzedaż biletów o identyfikatorze 12. Pasażer wsiądzie na pokład o 14:00 UTC i przylatuje o 14:50 czasu UTC.
• W dniu świadczenia usługi 20190716 identyfikator biletu na podróż ti2 rozpoczyna się od identyfikatora biletu w czasie zatrzymania 21, aby zatrzymać sprzedaż biletów o identyfikatorze 22. Pasażer wsiądzie na pokład o 15:00 UTC i przylatuje o 15:50 czasu UTC.

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

Biorąc pod uwagę wszystkie te informacje, użyj tych wartości parametrów pliku danych w przypadku 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 atrybutu ticketing_stop_id

Przystanki mogą mieć różne identyfikatory na potrzeby sprzedaży biletów w polu ticketing_identifiers.txt. Pogrubione wartości to wartości znalezione w wywołaniu internetowym opisanym po plikach.

stop.txt
stop_id,stop_name si1,„Paryż Gare-de-Lyon” si2, „Lyon Part-Dieu”

routes.txt
route_id,route_long_name,ticketing_deep_link_id ri1,„TGV w Oui Paryż-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,agencja1,4924 si2,agencja1,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 żądanie zostało przesłane 19 lipca 2019 r., a godziny GTFS są podane według strefy czasowej UTC+1, wywołanie dotyczy witryny:

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

Ważne: pamiętaj, że wartości w polach boarding_time i arrival_time, które są podane w czasie UTC, nie muszą być zgodne ze strefą czasową w GTFS (UTC+1), co powoduje zmianę wartości HH:MM:SS.

Zalecane metody

Aby wdrożyć rozszerzenia sprzedaży biletów w Transport publiczny Google, postępuj zgodnie z tymi zaleceniami:

Wytyczne
Jeśli to możliwe, udostępniaj precyzyjne linki między agencjami lub trasami.	Jeśli w statycznym pliku danych wiele agencji lub tras ma te same adresy URL precyzyjnych linków, muszą mieć tę samą wartość w polu ticketing_deep_link_id. Umożliwia to transfery między agencjami lub trasami. Uwaga: jeśli nie, pasażerowie muszą kupić 2 oddzielne bilety ze względu na różne wartości w: ticketing_deep_link_id.
Ustaw spójne wartości dla parametru ticketing_type.	Wartość ticketing_type konkretnego przystanku musi być taka sama we wszystkich wierszach w pliku stop_times.txt. Uwaga: wartość ticketing_type wynosząca 1 wyłącza sprzedaż biletów na wszystkie przejazdy z danym przystankiem.
Mapuj ticketing_stop_id dla przystanków nadrzędnych i podrzędnych.	Przeprowadź mapowanie wszystkich przystanków nadrzędnych i podrzędnych, które wymagają biletów. W pliku ticketing_identifiers.txt wartości ticketing_stop_id nie są rozpowszechniane między przystankiem nadrzędnym a podrzędnymi.
Zmapuj element ticketing_stop_id dla każdej agencji, która korzysta z tego samego przystanku w pliku danych.	Jeśli w statycznym pliku danych wiele agencji udostępniających bilety udostępnia ten sam przystanek, mapowanie musi być dostępne dla każdej z nich. Więcej informacji znajdziesz w sekcji Definicje pól na stronie ticketing_identifiers.txt.
Używaj linków aplikacji na Androida, gdy wymagany jest precyzyjny link do aplikacji na Androida.	Jeśli partner chce otworzyć aplikację na Androida za pomocą precyzyjnego linku, skonfiguruj precyzyjny link jako link do aplikacji na Androida. Uwaga: jeśli partner chce otworzyć tylko witrynę z obsługą urządzeń mobilnych, wpisz bezpośrednio jej adres URL.
Jeśli wymagany jest precyzyjny link do aplikacji na iOS, używaj uniwersalnych linków na iOS.	Jeśli partner chce otworzyć aplikację na iOS za pomocą precyzyjnego linku, skonfiguruj precyzyjny link jako uniwersalny link na iOS.