Google 대중교통 티켓 판매 확장

이 페이지에는 GTFS 티켓 판매 사양의 세부 항목이 정의되어 있습니다(사양은 본 문서 작성 시 제안 단계에 있음). 또한 Google의 추가 제한사항도 포함되어 있습니다.

요구사항

stop_times.txt의 departure_time 필드는 필수 항목입니다.

추가 필드 유형

이 섹션에서는 추가 필드 유형과 Google의 확장 프로그램 유형을 설명합니다. 일부 필드에는 URI 형식의 값이 필요합니다.

• URI: 스키마가 포함된 정규화된 URI(Uniform Resource Identifier)입니다. URI의 특수문자는 올바른 이스케이프를 사용해야 합니다. 정규화된 URI 값을 만드는 방법에 대한 설명은 RFC 3986 URI(Uniform Resource Identifier): 일반 구문을 참고하세요.

파일 확장 또는 추가

확장 상태의 텍스트 파일은 이미 존재하며 확장해야 하는 파일입니다. 다음 표에 정의된 새 필드를 추가해야 합니다.

추가 상태의 텍스트 파일은 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의 ID) 특정 기관에 사용할 딥 링크를 정의합니다. routes.txt에서 덮어쓸 수 있습니다. 참고: 전체 정적 피드에 티켓 피드를 적용하려면agency.txt 파일의 모든 기관에 대해 ticketing_deep_link_id 필드에 동일한 값을 설정하세요.

routes.txt(파일 확장됨)

필드 이름	상태	세부정보
ticketing_deep_link_id	선택사항	(ticketing_deep_links.txt의 ID) 특정 경로에 사용할 딥 링크를 정의합니다. 있는 경우, agency.txt에 있는 필드를 덮어씁니다.

trips.txt(파일 확장됨)

필드 이름	상태	세부정보
ticketing_trip_id	선택사항	(ID) 딥 링크에서 전달할 식별자입니다. 고유한 식별자가 아니어도 됩니다. ticketing_trip_id가 비어 있으면 시스템에서 trip_id의 값을 대신 사용합니다.
ticketing_type	선택사항	(enum) 이 여정에 대해 딥 링크를 통한 티켓 판매가 가능한지 정의합니다. 0 또는 비어 있음: 경로 또는 기관의 ticketing_deep_link_id를 정의하는 경우 사용할 수 있습니다. 그 외에는 사용할 수 없습니다. 1: 사용 불가

stop_times.txt(파일 확장됨)

필드 이름	상태	세부정보
ticketing_type	선택사항	(enum) 이 정차 시간에 대해 딥 링크를 통한 티켓 판매가 가능한지 정의합니다. stop_times.ticketing_type를 정의하면 trip.ticketing_type에 설정된 값이 재정의됩니다. 비어 있음: trip.ticketing_type의 값을 사용합니다. 0: 경로 또는 기관의 ticketing_deep_link_id를 정의하는 경우 사용할 수 있습니다. 그 외에는 사용할 수 없습니다. 1: 사용 불가 중요: 특정 stop_id의 경우, 해당 stop_times에 ticketing_type=1이 있으면 다른 모든 stop_times에도 ticketing_type=1이 있어야 합니다.

ticketing_identifiers.txt(파일 추가됨)

티켓 판매에서 가장 일반적인 사례는 모든 정류장에 결제 처리를 위한 식별자가 있는 것입니다. 여러 기관에서 특정 정류장에 동일한 식별자를 사용할 수 있습니다. 여러 기관이 같은 정류장에서 서비스를 제공하는 경우 각 기관에 대해 이 매핑을 반복하세요.

필드 이름	상태	세부정보
ticketing_stop_id	필수	(ID) 특정 기관에 대해 해당 정류장의 기본 티켓 판매 ID를 정의합니다.
stop_id	필수	(stops.txt의 ID) 기본 ticketing_stop_id가 정의된 정류장입니다.
agency_id	필수	(agency.txt의 ID) 기본 ticketing_stop_id가 정의된 정류장의 기관입니다.

ticketing_deep_links.txt(파일 추가됨)

필드 이름	상태	세부정보
ticketing_deep_link_id	필수	(ID) 딥 링크의 ID를 정의합니다.
web_url	선택사항	(URL) 딥 링크의 방문 URL입니다. 이 필드는 translations.txt를 통해 번역할 수 없습니다. 중요: 이 필드의 URL 번역은 지원되지 않으므로 수신 웹사이트 또는 앱에서 언어를 감지할 수 있어야 합니다.
android_intent_uri	선택사항	(URI) android.intent.action.VIEW 인텐트가 포함된 네이티브 Android 앱에 전달할 URI입니다. 비어 있으면 네이티브 Android 앱에 딥 링크할 수 없습니다. 중요: 이 필드의 URL 번역은 지원되지 않으므로 수신 웹사이트 또는 앱에서 언어를 감지할 수 있어야 합니다. Android의 딥 링크에 관한 자세한 내용은 앱 콘텐츠 딥 링크 만들기를 참고하세요. 권장사항: 승객이 기기에 네이티브 Android 앱을 설치하지 않은 경우 안전성이 더 높고 대체 동작이 더 좋은 Android App Links를 사용하세요. 이 필드는 translations.txt를 통해 번역할 수 없습니다.
ios_universal_link_url	선택사항	(URL) iOS에서 호출할 범용 링크 URL입니다. 중요: 이 필드의 URL 번역은 지원되지 않으므로 수신 웹사이트 또는 앱에서 언어를 감지할 수 있어야 합니다. 비어 있으면 iOS에 딥 링크가 표시되지 않습니다. 자세한 내용은 iOS의 범용 링크를 참고하세요. 이 필드는 translations.txt를 통해 번역할 수 없습니다.

참고: 여러 기관 또는 경로에서 피드에 동일한 딥 링크 URL을 공유하는 경우 하나의 딥 링크만 정의하고 모든 기관 또는 경로를 동일한 딥 링크에 연결할 것을 적극 권장합니다. 자세한 내용은 권장사항 섹션을 참고하세요.

API 호출의 필드 자리표시자

Google은 다음 매개변수를 사용하여 ticketing_deep_links.txt에 정의된 URL을 호출합니다.

필드 이름	세부정보
service_date	(날짜, 반복 가능) 여정의 서비스 일자입니다. 이 필드의 형식은 JSON 배열입니다.
ticketing_trip_id	(trips.txt의 ID, 반복 가능) 여정의 식별자입니다. 이 필드의 형식은 JSON 배열입니다.
from_ticketing_stop_time_id	(반복 가능) 구간이 시작되는 stop_time의 식별자입니다. 특정 정차 시간의 값은 다음과 같습니다. stop_time의 agency_id 및 stop_id에 대해 ticketing_identifiers.txt에 정의된 ticketing_stop_id입니다. 중요: 해당 정류장 자체에 대해서만 ticketing_identifiers를 사용합니다. 상위 정류장이 있더라도 상위 정류장의 ticketing_identifiers는 무시됩니다. 그밖에는 stop_sequence가 사용됩니다. 이 필드의 형식은 JSON 배열입니다.
to_ticketing_stop_time_id	(반복 가능) 구간이 끝나는 stop_time의 식별자입니다. 값 파생에 대한 설명은 from_ticketing_stop_time_id를 참고하세요. 이 필드의 형식은 JSON 배열입니다.
boarding_time	(ISO 8601, 반복 가능) 구간이 시작되는 stop_time의 출발 시간(departure_time)입니다. 이 필드의 시간 값은 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	(ISO 8601, 반복 가능) 구간이 끝나는 stop_time의 도착 시간(arrival_time)입니다. 이 필드의 시간 값은 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, 정차 시간 티켓 판매 ID 11에서 정차 시간 티켓 판매 ID 12까지 여정 티켓 판매 ID ti1이 시작됩니다. 승객은 오후 2시(UTC)에 탑승하고 오후 2시 50분(UTC)에 도착합니다.
• 서비스 날짜 20190716, 정차 시간 티켓 판매 ID 21에서 정차 시간 티켓 판매 ID 22까지 여정 티켓 판매 ID ti2가 시작됩니다. 승객은 오후 3시(UTC)에 탑승하고 오후 3시 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 필드를 사용해 정류장의 ID를 서로 다르게 할 수 있습니다. 굵게 표시된 값은 파일 뒤에 설명되는 웹 호출에서 확인할 수 있는 값입니다.

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

요청이 2019-07-19에 발생하고 GTFS 시간이 UTC+1 시간대인 경우 웹 호출은 다음과 같습니다.

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에 대해 일관된 값을 설정합니다.	특정 정류장의 ticketing_type 값은 stop_times.txt 파일의 모든 행 간에 일치해야 합니다. 참고: ticketing_type 값이 1이면 해당 정류장을 사용하는 모든 여정의 티켓 판매가 사용 중지됩니다.
상위 정류장과 하위 정류장 모두의 ticketing_stop_id를 매핑합니다.	티켓 판매가 필요한 모든 상위 및 하위 정류장에 대해 매핑을 실행합니다. ticketing_identifiers.txt 파일에서 ticketing_stop_id 값은 상위 정류장과 하위 정류장 사이에 반영되지 않습니다.
피드에서 동일한 정류장을 사용하는 각 기관에 대해 ticketing_stop_id를 매핑합니다.	정적 피드에서 티켓 판매를 사용 설정한 여러 기관이 동일한 정류장을 공유하는 경우 각 기관에 대한 매핑이 있어야 합니다. 자세한 내용은 ticketing_identifiers.txt의 필드 정의 섹션을 참고하세요.
Android 앱으로 연결되는 딥 링크가 필요한 경우 Android App Links를 사용합니다.	파트너가 딥 링크에서 Android 앱을 열려고 하는 경우 딥 링크를 Android 앱 링크로 설정합니다. 참고: 파트너가 모바일 지원 웹사이트만 열려고 하는 경우 웹사이트 URL을 직접 사용하세요.
iOS 앱으로 연결되는 딥 링크가 필요한 경우 iOS 범용 링크를 사용합니다.	파트너가 딥 링크에서 iOS 앱을 열려고 하는 경우 딥 링크를 iOS 범용 링크로 설정합니다.