GTFS リアルタイム リファレンス

交通機関は GTFS リアルタイム フィードを利用して、運行の障害(駅の閉鎖、運転見合わせ、重大な遅れなど)、車両の現在地、予定到着時刻に関するリアルタイムの情報を利用客に提供することができます。

このサイトでは、このフィード仕様のバージョン 1.0 について取り上げ、説明しています。

用語の定義

  • required(必須): 1 回のみ指定
  • repeated(繰り返し): ゼロ回以上指定
  • message(メッセージ): 複合型
  • enum(列挙型): 固定値のリスト

要素の目次

要素

message FeedMessage

フィード メッセージの内容です。フィードを流れていく各メッセージは適切な HTTP GET リクエストに対するレスポンスとして取得されます。リアルタイム フィードは常に、既存の GTFS フィードとの関連で定義されます。エンティティ ID はすべて GTFS フィードに対応して解決されます。

フィードは、いくつかの外部構成に左右されます:

  • 対応する GTFS フィード。
  • フィードの用途(最新情報、位置情報、運行情報)。フィードには、目的の用途に関するアイテムのみを含めます。その他のエンティティはすべて無視されます。
  • ポーリング間隔。min_update_delay、max_update_delay で制御されます。

フィールド

フィールド名 タイプ 指定回数 説明
header FeedHeader 必須 このフィードとフィード メッセージに関するメタデータ。
entity FeedEntity 繰り返し フィードの内容。

message FeedHeader

フィードに関するメタデータ(フィード メッセージに含まれる)。

フィールド

フィールド名 タイプ 指定回数 説明
gtfs_realtime_version string 必須 このフィード仕様のバージョン。最新バージョンは 1.0 です。
incrementality Incrementality 省略可能
timestamp uint64 省略可能 このタイムスタンプでは、このフィードの内容が作成された(サーバーの時間での)時刻を POSIX 時間(1970 年 1 月 1 日 00:00:00 UTC からの経過秒数)で表します。リアルタイム情報を生成するシステムと利用するシステムとの間に時間差が生じないようにするために、タイムサーバーからタイムスタンプを取得することを強くおすすめします。数秒の時間差は許容範囲ですので、Stratum 3 またはそれより下位のサーバーを使用してもまったく問題はありません。

enum Incrementality

最新の取得値が増分データかどうかを指定します。

  • FULL_DATASET: このフィードの更新情報は、フィードについての先行するすべてのリアルタイム情報を上書きします。したがって、この更新情報は既知のリアルタイム情報すべての完全なスナップショットと見なすことができます。
  • DIFFERENTIAL: 現在のところ、このモードはサポートされていません。このモードを使用するフィードの動作は未確定です。DIFFERENTIAL モードの動作の全面的な定義については、GTFS リアルタイムのメーリングリストで議論されています。この議論が決着すれば、このドキュメントも更新される予定です。

FULL_DATASET
DIFFERENTIAL

message FeedEntity

乗換案内フィード内のエンティティの定義(または更新)。エンティティが削除されていない場合は、「trip_update」、「vehicle」、「alert」のいずれかのフィールドにデータが設定される必要があります。

フィールド

フィールド名 タイプ 指定回数 説明
id string 必須 このエンティティの、フィード固有の ID。この ID は、増分データをサポートする目的でのみ使用されます。フィードで参照される実際のエンティティは、明示的なセレクタで指定する必要があります(詳しくは、後続の「EntitySelector」をご覧ください)。
is_deleted bool 省略可能 このエンティティが削除されるかどうか。増分データを取得する場合のみ関係します。
trip_update TripUpdate 省略可能 旅程の、リアルタイムの出発時間の遅れに関するデータ。
vehicle VehiclePosition 省略可能 車両のリアルタイムの現在地に関するデータ。
alert Alert 省略可能 リアルタイムの運行情報に関するデータ。

message TripUpdate

旅程を走行中の車両の進捗状況に関するリアルタイムの情報。ルート最新情報フィード タイプの概要については、こちらをご覧ください。

ScheduleRelationship の値に応じて、TripUpdate では次のことを指定できます:

  • 時刻表に従って進行している旅程。
  • ルートに沿って進行しているが、時刻表がない旅程。
  • 時刻表に追加された、または時刻表から削除された旅程。
この最新情報は、将来の予測される到着/出発イベント、または既に発生した過去のイベントに対応できます。ほとんどの場合、過去のイベントについての情報は測定値であるため、不確実度の値は 0 にすることをおすすめします。ただしこれが当てはまらない場合もあるので、過去のイベントの不確実度を必ずしも 0 にしなくてもかまいません。不確実度が 0 ではない場合、その最新情報は、完了していない旅程または測定値が正確ではない旅程に対するおおよその予測であるか、あるいはイベント発生後の検証が行われていない過去についての予測のいずれかです。

この最新情報では、既に終了している旅程について説明することができます。そのため、旅程の最後の停車地に関する更新情報を提供すれば十分です。最後の停車地の到着時刻が過去の時間であれば、その旅程全体が過去のことだとクライアント側で判断できるためです(ただし、それより前の停車地の更新情報を提供することも、重要ではないにせよ不可能ではありません)。このオプションの対象として最も関係があるのは時刻表の時間より早く終了した旅程ですが、時刻表に従えば、この旅程はその時点でもまだ進行していることになります。この旅程の最新情報を削除してしまうと、クライアント側では旅程がまだ進行中であると見なす可能性があります。したがって、フィード提供者は過去の最新情報を削除することもできますが(削除した方が実用的である場合など)、必ずしも削除する必要はないことに注意してください。

フィールド

フィールド名 タイプ 指定回数 説明
trip TripDescriptor 必須 このメッセージが適用される旅程。実際の 1 つの旅程インスタンスに対して指定できる TripUpdate エンティティは 1 つ以下です。指定がない場合は、利用できる予測情報がないことを意味します。その旅程が時刻表どおりに進行しているという意味ではありません。
vehicle VehicleDescriptor 省略可能 この旅程を走行している車両に関する追加情報。
stop_time_update StopTimeUpdate 繰り返し 旅程の停車時刻(将来の(予想)時刻、また場合によっては過去の(既に停車した)時刻の両方)の最新情報。これらの情報は stop_sequence に従って並べ替えられ、次に指定されている停車地に到着するまでは旅程の後続の停車地すべてに適用されます。

message StopTimeEvent

1 つの予測イベント(到着または出発)の時間情報。時間情報は、遅延時間または予定時刻(あるいはその両方)と不確実度で構成されます。

  • delay(遅延時間)は、GTFS での既存の時刻表との関連で予測が行われる場合に使用します。
  • time(予定時刻)では、予想時刻があるかどうかを指定します。time と delay の両方が指定されている場合は time が優先します(時刻表がある旅程であれば time の値は通常、GTFS での時刻表の時間に delay を加えた値と等しくなるはずです)。


不確実度(uncertainty)は、time と delay のどちらにも等しく適用されます。不確実度では、実際の遅延時間で予想される誤差を大まかに指定します(正確な統計的意味はまだ定義されていません)。不確実度を 0 にすることもあり得ます。コンピュータによる時間制御の下で運転されている列車の場合などです。

フィールド

フィールド名 タイプ 指定回数 説明
delay int32 省略可能 遅延時間(秒単位)は、正の値をとる(車両が遅れていることを表す)ことも負の値をとる(車両が定刻より早く発着していることを表す)こともできます。遅延時間が 0 の場合は、定刻どおり運行していることを表します。
time int64 省略可能 イベントの絶対時間。POSIX 時間(1970 年 1 月 1 日 00:00:00 UTC からの経過秒数)で表します。
uncertainty int32 省略可能 uncertainty を省略すると、「不明」として解釈されます。確実な予測であることを表す場合は、uncertainty を 0 に設定します。

message StopTimeUpdate

旅程の特定の停車地に関する到着/出発イベントのリアルタイムの更新情報。停車時刻の更新情報の概要については、TripDescriptorルート最新情報フィード タイプもご覧ください。

過去と未来どちらのイベントについても更新情報を提供できます。フィード制作者は過去のイベントを削除できますが、必ずしも削除する必要はありません。
この更新情報は stop_sequence または stop_id により特定の停車地と関連付けられるので、必ずいずれかのフィールドを設定しなければなりません。

フィールド

フィールド名 タイプ 指定回数 説明
stop_sequence uint32 省略可能 対応する GTFS フィードの stop_times.txt 内での設定と同じ値にします。
stop_id string 省略可能 対応する GTFS フィードの stops.txt 内での設定と同じ値にします。
arrival StopTimeEvent 省略可能
departure StopTimeEvent 省略可能
schedule_relationship ScheduleRelationship 省略可能

enum ScheduleRelationship

この停車時刻と定期便時刻表との関係。

コメント
SCHEDULED 車両は、必ずしも定刻どおりではありませんが、予定された各停車地を回っています。到着時刻と出発時刻を少なくとも 1 つ指定する必要があります。この停車地の時刻表に到着時刻も出発時刻も含まれている場合は、この更新情報も同様にする必要があります。時刻表にこの両方の時刻が設定されている場合に到着時刻の更新情報しかないときは、この途中の停車地で運行が中止されたことを意味します。
SKIPPED この停車地は通過されます(車両は停まりません)。到着時刻と出発時刻は省略可能です。
NO_DATA この停車地に関するデータは提供されません。つまり、利用できるリアルタイム情報はありません。NO_DATA の設定は後続の停車地にも反映されます。そのため、どの停車地からリアルタイム情報がないのか指定することをおすすめします。NO_DATA に設定すると、到着と出発どちらの時刻も指定できません。

message VehiclePosition

特定の車両に関するリアルタイムの現在地情報。

フィールド

フィールド名 タイプ 指定回数 説明
trip TripDescriptor 省略可能 この車両が走行している旅程。車両を特定の旅程インスタンスで特定できない場合は、旅程の一部だけでも、または指定しなくてもかまいません。
vehicle VehicleDescriptor 省略可能 この旅程を走行している車両に関する追加情報。各エントリに、固有の車両 ID を指定する必要があります。
position Position 省略可能 この車両の現在地。
current_stop_sequence uint32 省略可能 現在の停車地の stop_sequence。current_stop_sequence の意味(つまり参照される停車地)は current_status によって決まります。current_status の指定がない場合は IN_TRANSIT_TO であると見なされます。
stop_id string 省略可能 現在の停車地を表す ID。この値は、対応する GTFS フィードの stops.txt 内での設定と同じ値にします。
current_status VehicleStopStatus 省略可能 現在の停車地に対する、車両の正確な状況。current_stop_sequence が指定されていない場合は無視されます。
timestamp uint64 省略可能 車両の位置情報が測定された日時。POSIX 時間(1970 年 1 月 1 日 00:00:00 UTC からの経過秒数)で表します。
congestion_level CongestionLevel 省略可能

enum VehicleStopStatus

コメント
INCOMING_AT 車両はまもなく停車地に到着します(停車地の表示では通常、車両マークが点滅します)。
STOPPED_AT 車両は停車地に停車中です。
IN_TRANSIT_TO 車両は次の停車地に向けて現在走行中です。

enum CongestionLevel

この車両に影響を及ぼす渋滞のレベル。

UNKNOWN_CONGESTION_LEVEL
RUNNING_SMOOTHLY
STOP_AND_GO
CONGESTION
SEVERE_CONGESTION

message Alert

公共交通機関でのある種の事故を示す運行情報。

フィールド

フィールド名 タイプ 指定回数 説明
active_period TimeRange 繰り返し この運行情報をユーザーに表示する期間。指定されていない場合は、その運行情報がフィードに含まれている限りは表示されます。複数の期間が指定されている場合は、そのすべての期間中表示されます。
informed_entity EntitySelector 繰り返し この運行情報を知らせるべきユーザーが利用するエンティティ。
cause Cause 省略可能
effect Effect 省略可能
url TranslatedString 省略可能 この運行情報に関する詳しい情報を提供するサイトの URL。
header_text TranslatedString 省略可能 運行情報の見出し。このプレーンテキストの文字列は、太字などで強調表示されます。
description_text TranslatedString 省略可能 運行情報の説明。このプレーンテキストの文字列は、運行情報の本文として書式設定されます(またはユーザーが明示的に「展開」をリクエストしたときに表示されます)。説明文の情報は、見出しの情報に追加する形にします。

enum Cause

この運行情報の原因。

UNKNOWN_CAUSE
OTHER_CAUSE
TECHNICAL_PROBLEM
STRIKE
DEMONSTRATION
ACCIDENT
HOLIDAY
WEATHER
MAINTENANCE
CONSTRUCTION
POLICE_ACTIVITY
MEDICAL_EMERGENCY

enum Effect

関連するエンティティに対してこの問題が及ぼす影響。

NO_SERVICE
REDUCED_SERVICE
SIGNIFICANT_DELAYS
DETOUR
ADDITIONAL_SERVICE
MODIFIED_SERVICE
OTHER_EFFECT
UNKNOWN_EFFECT
STOP_MOVED

message TimeRange

時間間隔。この間隔は、時間 t が開始時間と同じまたはそれより遅く終了時間より早い場合に、t の時点で有効であると見なされます。

フィールド

フィールド名 タイプ 指定回数 説明
start uint64 省略可能 開始時間。POSIX 時間(1970 年 1 月 1 日 00:00:00 UTC からの経過秒数)で表します。指定されていない場合、時間間隔は負の無限大から開始します。
end uint64 省略可能 終了時間。POSIX 時間(1970 年 1 月 1 日 00:00:00 UTC からの経過秒数)で表します。指定されていない場合、時間間隔は正の無限大で終了します。

message Position

車両の地理的な位置。

フィールド

フィールド名 タイプ 指定回数 説明
latitude float 必須 WGS-84 測地系で表した北緯。
longitude float 必須 WGS-84 測地系で表した東経。
bearing float 省略可能 真北から時計回りの角度で表した方角。つまり、0 は北、90 は東です。これはコンパス方位でも、次の停車地や中間地点に向いた方向でもかまいません。先行する一連の位置情報から推定される値にはしないでください(クライアント側では前のデータを基にしてこの位置を計算できます)。
odometer double 省略可能 メートル単位で表した走行距離計の値。
speed float 省略可能 車両で計測された瞬間速度(メートル毎秒)。

message TripDescriptor

GTFS の旅程の 1 つのインスタンス、またはルートに沿った旅程のすべてのインスタンスを表す記述子。単独の旅程インスタンスを指定するには、trip_id を(また、必要に応じて start_time も)設定します。route_id も設定する場合は、指定された旅程に対応する route_id と同じにする必要があります。特定のルートに沿ったすべての旅程を指定するには、route_id のみを設定します。trip_id が不明な場合、TripUpdate での連続する停車地の ID では不十分であるため、stop_id も指定しなければなりません。さらに、到着/出発の絶対時間も指定する必要があります。

フィールド

フィールド名 タイプ 指定回数 説明
trip_id string 省略可能 このセレクタが参照する GTFS フィードの trip_id。運行間隔が変わらない旅程の場合、このフィールドだけで旅程を一意に特定できます。運行間隔が変わる場合は、start_time と start_date も必要になります。
route_id string 省略可能 このセレクタが参照する GTFS の route_id。
start_time string 省略可能 この旅程インスタンスの予定開始時間。このフィールドは、GTFS フィードで旅程の運行間隔が変わる場合にのみ指定します。この値は、GTFS フィードで旅程に対して指定された start_time に headway_secs の倍数を加えた値と一致する必要があります。このフィールドの形式は GTFS の frequencies.txt で指定する start_time の形式と同じ(たとえば「11:15:35」や「25:15:35」)です。
start_date string 省略可能 この旅程インスタンスの予定開始日。このフィールドは、旅程に大幅な遅れが生じたため翌日に予定されている旅程と運行時間が重なった場合のあいまいさをなくす目的で設定します。たとえば、毎日 8:00 と 20:00 に出発する列車の場合、12 時間の遅れが生じると、同じ時刻に異なる 2 つの旅程が発生することになります。こうした事態にはなり得ない時刻表であれば、このフィールドは設定してもかまいませんが必須ではありません。たとえば、1 時間おきに運行しているサービスで、ある車両が 1 時間遅れになっても時刻表には関係しないと考えられます。形式は YYYYMMDD を使用します。
schedule_relationship ScheduleRelationship 省略可能

enum ScheduleRelationship

この旅程と定期便時刻表との関係。臨時の時刻表に従って運行され、GTFS に反映されない場合は、SCHEDULED ではなく ADDED として設定しなければなりません。

コメント
SCHEDULED GTFS の時刻表に従って、またはそれとほぼ同じスケジュールで進行している旅程。
ADDED 故障した車両の代わりとして、または急な乗客増加に対応するためなどの理由で、現行の時刻表に追加された臨時の旅程。
UNSCHEDULED 運行されているものの関連する時刻表がない旅程(運行時刻が決まっていない場合など)。
CANCELED 時刻表に記載されていたが削除された旅程。
REPLACEMENT 定期便時刻表の一部の代わりとなる旅程。旅程セレクタが特定の旅程インスタンスを指定している場合は、そのインスタンスのみが置き換えられます。特定のルートを指定している場合は、そのルートに沿ったすべての旅程が置き換えられます。

この置き換えは、指定された旅程の一部にのみ適用されます。たとえば、停車地 A、B、C、D、E、F に停車するルートがあり、REPLACEMENT の旅程では停車地 A、B、C のデータが提供されるとします。その場合、停車地 D、E、F の停車時刻は、定期便時刻表どおりとなります。

1 つのフィードで REPLACEMENT の旅程を複数設定することができます。この場合、定期便時刻表の中の置き換えられる部分は、これらすべての旅程で定義される部分です。通常は、REPLACEMENT のすべての旅程が同一のルートに対応するか、または個別の旅程インスタンスに対応するようにしなければなりません。

message VehicleDescriptor

旅程を走行する車両の識別情報。

フィールド

フィールド名 タイプ 指定回数 説明
id string 省略可能 車両の社内系統の ID。車両固有の ID でなければなりません。この ID は、車両がその系統を走行する際の追跡確認に使用されます。この ID はエンドユーザーに表示するものではありません。ユーザーに表示するテキストについては、label フィールドを使用します。
label string 省略可能 ユーザーに表示する(乗客が車両を正しく識別できるように掲示される)なんらかのラベル。
license_plate string 省略可能 車両のナンバープレート。

message EntitySelector

GTFS フィード内の特定のエンティティを選択するセレクタ。各フィールドの値は、GTFS フィードのそれぞれ対応するフィールドと同じ値にします。少なくとも 1 つの指定子を使用する必要があります。指定子が複数ある場合は、それらすべての指定子に対して照合が行われます。

フィールド

フィールド名 タイプ 指定回数 説明
agency_id string 省略可能
route_id string 省略可能
route_type int32 省略可能
trip TripDescriptor 省略可能
stop_id string 省略可能

message TranslatedString

テキストまたは URL の言語別スニペットが含まれる国際化されたメッセージ。メッセージからいずれか 1 つの文字列が選択されます。この文字列の選択は次のように処理されます。すなわち、UI の言語がある翻訳の言語コードと一致する場合は、その一致する最初の翻訳が選択されます。デフォルトの UI 言語(たとえば英語)がある翻訳の言語コードと一致する場合は、その一致する最初の翻訳が選択されます。言語コードが指定されていない翻訳の場合は、その翻訳が選択されます。

フィールド

フィールド名 タイプ 指定回数 説明
translation Translation 繰り返し 少なくとも 1 つの翻訳を指定する必要があります。

message Translation

特定の言語に関連付けられているローカライズされた文字列。

フィールド

フィールド名 タイプ 指定回数 説明
text string 必須 メッセージが含まれている UTF-8 の文字列。
language string 省略可能 BCP-47 言語コード。言語が不明である場合や、フィードが国際化されていない場合は省略可能です。翻訳が 1 つ以下であれば言語タグを指定しなくてもかまいません。