GTFS Realtime¶
はじめに¶
GTFS Realtimeデータフォーマットで、公共交通機関のRealtime情報を記述する際の推奨事項です。
文書構成¶
推奨されるプラクティスは、主に2つのセクションに分かれています。
- __メッセージ別推奨__事項GTFS Realtimeの公式リファレンスに記載されている順番で、メッセージとフィールドごとに整理されています。
- __ケース__別推奨事項：ケース別に推奨事項をまとめました。頻度ベースのサービス(対Scheduleサービス)のような特定のケースでは、複数のメッセージとフィールド、および対応するGTFS Scheduleデータにわたって適用する必要がある場合があります。そのような推奨事項をこのセクションにまとめました。
フィードの公開と一般的なプラクティス¶
- フィードは、公開された恒久的なURLで公開されるべきです。
- この URL は、フィードにアクセスするためにログインすることなく直接アクセスできるようにする必要があります。必要に応じて API キーを使用することもできますが、API キーの登録は自動化され、誰でも使用できるようにする必要があります。
- GTFS Realtimeフィード内の永続的な識別子 (id フィールド) (
FeedEntity.id,VehicleDescriptor.id,CarriageDetails.idなど) は、フィードの繰り返しにわたって維持される。 - GTFS Realtimeフィードは、少なくとも 30 秒に一度、またはフィード内の情報 (車両の位置) が変化するたびに、リフレッシュされる必要があります。VehiclePosition は他のフィードエンティティよりも頻繁に変更される傾向があるため、できるだけ頻繁に更新する必要があります。コンテンツに変更がない場合は、フィードの
FeedHeader.timestampを更新し、 その時点の情報がまだ適切であることを示すようにします。 - GTFS Realtimeフィード内のデータは、Trip Updates と Vehicle Position は 90 秒以上、Service Alerts は 10 分未満である必要があります。例えば、生産者が
FeedHeader.timestampのタイムスタンプを 30 秒ごとに更新し続けている場合でも、そのフィード内の VehiclePosition は 90 秒より古くならないようにする必要があります。 - GTFS Realtimeデータをホストするサーバーは、信頼性が高く、常に有効なフォーマットのprotobuf-encodedレスポンスを返す必要があります。無効なレスポンス（protobufエラーまたはフェッチエラー）は1%未満でなければならない。
- GTFS Realtimeデータをホストするウェブサーバーは、ファイルの修正日を正しく報告するように設定されるべきです。(セクション 14.29 の HTTP/1.1 - Request for Comments 2616 を参照) そのため、消費者は
If-Modified-SinceHTTP header を利用することができます。これにより、プロデューサとコンシューマは、変更されていないフィードコンテン ツの転送を避けることができ、帯域幅を節約することができる。 - フィードは、与えられたURLのHTTPリクエストで照会されたとき、デフォルトでプロトコルバッファでエンコードされたフィードコンテンツを提供すべきです。 - 消費者は、プロトコルバッファでエンコードされたコンテンツを受け取るために特別なHTTP acceptヘッダーを定義する必要はないはずです。
- プロトコルバッファはオプションの値をエンコードするため、GTFS Realtimeフィードからデータを読み込む前に、プロトコルバッファが生成する
hasX()メソッドで値の存在を確認し、hasX()が真の場合のみ値を使用しなければなりません(Xはフィールド名です)。hasX() がfalseを返した場合、GTFS.proto の値で定義されたそのフィールドのデフォルト値が仮定されるべきである。コンシューマがhasX()メソッドを確認せずにその値を使用した場合、プロデューサが意図的に公開したのではないデフォルトデータを読み込んでいる可能性がある。 - フィードは、フィードの完全性を確保するために、HTTPの代わりにHTTPSを使用する必要があります（暗号化なし）。
- フィードは、関連する静的なGTFSデータセットに含まれる旅行の大部分をカバーする必要がある。特に、高密度で交通量の多い市街地や交通量の多い路線のデータを含むべきである。
推奨されるプラクティス（メッセージ別¶
フィードヘッダ¶
| フィールド名 | レコメンデーション |
|---|---|
gtfs_realtime_version |
現在のバージョンは "2.0 "です。 GTFS Realtime Realtime初期バージョンでは、乗り換えの状況を表現するのに必要なフィールドがすべて揃っていないため、すべてのGTFS Realtimeフィードは "2.0" 以降であるべきです。 |
timestamp |
このタイムスタンプは、連続した2回のフィードの間で減少してはならない。 |
フィードの内容が変更された場合は、このタイムスタンプの値も常に変更されるべきである。 timestamp.よくある間違い- ロードバランサーの後ろにGTFS Realtimefeedのインスタンスが複数ある場合、それぞれのインスタンスがRealtimeデータソースから情報を取得し、コンシューマーに公開する際に同期していない可能性があります。GTFS Realtimeコンシューマが2つのリクエストを同時に行った場合、それぞれのリクエストは異なるGTFS Realtimefeedインスタンスによって処理され、同じフィードコンテンツが異なるタイムスタンプでコンシューマに返される可能性があります。 可能な解決策- プロデューサは Last-ModifiedHTTP ヘッダを提供し、コンシューマはその最新の If-Modified-SinceHTTP ヘッダーを渡す必要があります。可能な解決策- HTTPヘッダーを使用できない場合は、スティッキーセッションなどのオプションを使用して、各コンシューマーが同じプロデューサーサーバーにルーティングされるようにすることができます。 |
フィードエンティティ¶
GTFS Realtimeフィードからエンティティを削除するのは、ユーザーとの関連性がなくなったときだけです。フィードはステートレスであると考えられており、各フィードがトランジットシステムのリアルタイムな状態を反映することを意味します。あるフィードのインスタンスで提供されたエンティティが、その後のフィードの更新で削除された場合、そのエンティティにはリアルタイムの情報はないと考えるべきです。
| フィールド名 | レコメンデーション |
|---|---|
id |
旅行期間全体にわたって安定した状態に保たれるべきである |
TripUpdate¶
トリップキャンセルのための一般的なガイドライン。
- 何日もかけてトリップをキャンセルする場合、制作者は、与えられた
trip_idとstart_datesをCANCELEDとして参照するTripUpdateと、キャンセルについてライダーに説明するNO_SERVICEとTimeRangeを参照するAlert（例：迂回）を提供すべきです。 - トリップ内の停留所を訪問しない場合、すべての
stop_time_updateをSKIPPEDとしてマークする代わりに、トリップをCANCELEDにする必要があります。
| フィールド名 | レコメンデーション |
|---|---|
trip |
参照 メッセージ TripDescriptor. |
分離されている場合 VehiclePositionそして TripUpdateフィードが提供されている場合。 TripDescriptorそして 車両記述子（VehicleDescriptorID値のペアは、2つのフィードの間で一致する必要があります。例えば VehiclePositionエンティティは vehicle_id:Aそして trip_id:4である場合，対応する TripUpdateのエンティティも持つべきです。 vehicle_id:Aそして trip_id:4.もし TripUpdateを持つ trip_id:4および任意の vehicle_idが4以外の場合、エラーとなります。 |
|
vehicle |
参照 メッセージ VehicleDescriptor. |
別の VehiclePositionそして TripUpdateフィードが提供されます。 TripDescriptorそして VehicleDescriptorID値のペアは、2つのフィード間で一致させる必要があります。例えば、ある VehiclePositionがあります。 vehicle_id:Aそして trip_id:4がある場合、対応する TripUpdateを持つべきである。 vehicle_id:Aそして trip_id:4.もしあれば TripUpdateを持つエンティティは trip_id:4と任意の vehicle_id4 以外の場合，エラーとする。 |
|
stop_time_update |
stop_time_updatesは、与えられた trip_idは，増加することによって厳密に並べられなければならない。 stop_sequenceであり stop_sequenceは繰り返されるべきです。 |
旅行が進行している間、すべての TripUpdatesには、少なくとも1つの stop_time_updateは、将来の到着時刻または出発時刻が予測されるものでなければならない。なお GTFS Realtime仕様では、プロデューサは過去の StopTimeUpdateを削除してはならない、と述べている。 |
|
timestamp |
このトリップの予測が更新された時間を反映する必要がある。 |
delay |
TripUpdate.delayは、Schedule偏差、すなわち、車両がどの程度Schedule進んでいるか／遅れているかの過去の観測値を表すべきである。将来の停車駅の予測は、以下のように提供されるべきである。 StopTimeEvent.delayまたは StopTimeEvent.time. |
TripDescriptor¶
VehiclePositionと TripUpdateのフィードが別々に提供されている場合、TripDescriptorと VehicleDescriptorのID値の組は2つのフィード間で一致する必要があります。
例えば、VehiclePositionエンティティがvehicle_id:Aとtrip_id:4 を持つ場合、対応するTripUpdateエンティティはvehicle_id:Aとtrip_id:4 も持つべきである。
| フィールド名 | レコメンデーション |
|---|---|
schedule_relationship |
トリップの動作は ADDEDtrip の動作は特定されておらず、この列挙の使用は推奨されない。 |
VehicleDescriptor¶
別々のVehiclePositionおよびTripUpdateフィードが提供される場合、TripDescriptorおよびVehicleDescriptorID値の組合せは、2つのフィード間で一致することが望ましい。
例えば、VehiclePositionエンティティがvehicle_id:Aとtrip_id:4 を持つ場合、対応するTripUpdateエンティティはvehicle_id:Aとtrip_id:4 を持つ必要がある。
| フィールド名 | レコメンデーション |
|---|---|
id |
トリップ期間全体にわたって、車両を一意にかつ安定的に識別する必要がある。 |
StopTimeUpdate¶
| フィールド名 | レコメンデーション |
|---|---|
stop_sequence |
提供する stop_sequenceとは異なり、GTFS停止時刻に一意に解決されるため、可能な限り、この列挙を使用すること。 stop_times.txtとは異なり stop_idループルートなど）。 |
arrival |
連続した停車駅間の到着時間は増加すべきである-同じであってはならないし、減少してもならない。 |
到着時刻 time(で指定 停止時間イベント（StopTimeEventで指定された）到着時刻は、出発時刻より前でなければならない。 time待ち時間または滞在時間が予想される場合は、同じ停留所の到着時刻は出発時刻より前でなければならない。 timeは、出発と同じであるべきである。 time. |
|
departure |
連続する停留所間の出発時間は増加すべきである-同じか減少すべきではない。 |
出発 time(で指定）。 停止時間イベント（StopTimeEventは到着と同じであるべきである。 timeと同じでなければなりません。 timeは到着の後でなければならない。 time. |
ストップタイムイベント（StopTimeEvent¶
| フィールド名 | レコメンデーション |
|---|---|
delay |
もし delayのみが提供される場合 stop_time_update arrivalまたは departure(が指定されている場合（そして time)であれば，GTFSstop_times.txtには arrival_timesと departure_timesを含むべきである。A delayRealtimeフィードの値は、GTFS追加する時刻がない限り意味がありません。 stop_times.txtファイルを作成します。 |
車両位置¶
VehiclePostionsフィードに含まれるべき推奨フィールドは以下のとおりです。
| フィールド名 | 備考 |
|---|---|
entity.id |
旅行期間全体にわたって安定に保たれるべきである |
vehicle.timestamp |
車両位置が測定されたタイムスタンプを提供することを強く推奨する。そうでない場合、消費者はメッセージのタイムスタンプを使用しなければならず、最後のメッセージが個々の位置よりも頻繁に更新された場合、ライダーにとって誤解を招く結果になることがあります。 |
vehicle.vehicle.id |
トリップ期間全体にわたって、車両を一意にかつ安定的に識別する必要がある。 |
位置情報¶
車両位置は、このtrip_id DETOURの効果を持つアラートがない限り、現在のトリップのGTFS shapes.txtデータから200m以内であるべきである。
注意事項¶
アラートに関する一般的なガイドライン
trip_idstart_timeexact_time=1間隔である場合、start_time間隔の始まりよりheadway_secsの倍数だけ遅くなっていなければならない。- 何日もかけて旅行をキャンセルする場合、製作者は、指定された
trip_idとstart_datesをCANCELEDとして参照するTripUpdateを提供するとともに、キャンセルについてライダーに説明するNO_SERVICEとtrip_idおよびTimeRangeを参照するAlert（例：遠回り）を提示しなければなりません。 - 警告がライン上のすべての停留所に影響する場合、停留所ベースの警告の代わりにラインベースの警告を使用します。ラインのすべての停留所に警告を適用しないでください。
- サービスアラートには文字数の制限はありませんが、交通機関の利用者はモバイルデバイスでアラートを見ることが多いでしょう。簡潔な表現にしてください。
| フィールド名 | レコメンデーション |
|---|---|
description_text |
サービスアラートを読みやすくするために、改行を使用してください。 |
ユースケース別に分類された実践的な推奨事項¶
頻度ベースのトリップ¶
頻度ベースのトリップは、固定Schedule従わないが、所定のヘッドウェイを維持しようとする。GTFS.org/reference/static/#frequenciestxt">GTFSfrequency.txtでは、exact_times=0とするか、exact_timesフィールドを省略することでこのようなトリップを表します（exact_times=1のトリップは、frequency-based tripではないことに注意してください -frequent_times=1のfrequencies.txtは単にSchedule旅をよりコンパクトに保存するための便宜上使われています）。頻度ベースのトリップのGTFS Realtimeフィードを構築する際に、留意すべきベストプラクティスがいくつかあります。
-
TripUpdate.StopTimeUpdateでは、
到着と出発のStopTimeEventに遅延を含めないようにします。代わりに、到着/出発予測を示す時間が提供されるべきである。 -
TripUpdateやVehiclePositionでTripDescriptor を用いて
トリップを記述する場合、trip_id,start_time,start_dateの全てを記述することが仕様で規定されている。また、schedule_relationshipはUNSCHEDULEDとする。
(例: 再強化トリップ).
この文書について¶
目的¶
GTFS Realtime維持する目的は、次のとおりです。
- 公共交通アプリケーションにおけるエンドユーザーの顧客体験を向上させる。
- ソフトウェア開発者によるアプリケーション、製品、およびサービスの展開と拡張を容易にする。
公開されているGTFS Realtime提案・修正方法¶
GTFSアプリケーションや運用は進化していくので、このドキュメントも随時修正する必要があります。このドキュメントを修正する場合は、 GTFS RealtimeBest Practices GitHub リポジトリでプルリクエストを作成し、変更を提案してください。
この文書へのリンク¶
GTFS Realtimeデータを正しく形成するためのガイダンスをフィードメーカーに提供するために、ここにリンクを貼ってください。各勧告にはアンカーリンクがあります。推奨事項をクリックすると、ページ内アンカーリンクのURLが表示されます。
GTFS Realtime を使用するアプリケーションが、ここに書かれていないGTFS Realtimeデータに関する要求や推奨をする場合、これらの共通のベストプラクティスを補足するために、それらの要求や推奨を記載したドキュメントを公開することが推奨されます。