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에서 덮어쓸 수 있습니다.

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: 사용 불가

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를 통해 번역할 수 없습니다.
android_intent_uri 선택사항

(URI) android.intent.action.VIEW 인텐트가 포함된 네이티브 Android 앱에 전달할 URI입니다.

비어 있으면 네이티브 Android 앱에 딥 링크할 수 없습니다.

Android의 딥 링크에 관한 자세한 내용은 앱 콘텐츠 딥 링크 만들기를 참고하세요.

이 필드는 translations.txt를 통해 번역할 수 없습니다.
ios_universal_link_url 선택사항

(URL) iOS에서 호출할 범용 링크 URL입니다.

비어 있으면 iOS에 딥 링크가 표시되지 않습니다.

자세한 내용은 iOS의 범용 링크를 참고하세요.

이 필드는 translations.txt를 통해 번역할 수 없습니다.

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입니다.

  • 그밖에는 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

이 필드의 형식은 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

이 필드의 형식은 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

Google 대중교통 티켓 판매 확장을 구현하려면 다음 권장사항을 따르세요.

가이드라인
가능하면 기관 또는 경로 간에 딥 링크를 공유합니다.

정적 피드에서 여러 기관 또는 경로의 딥 링크 URL이 동일한 경우 ticketing_deep_link_id 필드에 대해 단일 값을 공유해야 합니다. 이럴 경우 기관 또는 경로 간 환승이 가능합니다.
ticketing_type에 대해 일관된 값을 설정합니다.

특정 정류장의 ticketing_type 값은 stop_times.txt 파일의 모든 행 간에 일치해야 합니다.
상위 정류장과 하위 정류장 모두의 ticketing_stop_id를 매핑합니다. 티켓 판매가 필요한 모든 상위 및 하위 정류장에 대해 매핑을 실행합니다. ticketing_identifiers.txt 파일에서 ticketing_stop_id 값은 상위 정류장과 하위 정류장 사이에 반영되지 않습니다.
피드에서 동일한 정류장을 사용하는 각 기관에 대해 ticketing_stop_id를 매핑합니다.

정적 피드에서 티켓 판매를 사용 설정한 여러 기관이 동일한 정류장을 공유하는 경우 각 기관에 대한 매핑이 있어야 합니다.

자세한 내용은 ticketing_identifiers.txt의 필드 정의 섹션을 참고하세요.
Android 앱으로 연결되는 딥 링크가 필요한 경우 Android App Links를 사용합니다.

파트너가 딥 링크에서 Android 앱을 열려고 하는 경우 딥 링크를 Android 앱 링크로 설정합니다.
iOS 앱으로 연결되는 딥 링크가 필요한 경우 iOS 범용 링크를 사용합니다. 파트너가 딥 링크에서 iOS 앱을 열려고 하는 경우 딥 링크를 iOS 범용 링크로 설정합니다.