メインコンテンツまでスキップ

リアルタイム便情報機能を利用して便の遅延情報などを取得する

リアルタイム便情報機能 (realtime/trip) は、便や列車ごとのリアルタイムな情報が取得できるAPIです。「トリップコード」によって便を指定し、各交通事業者(鉄道・バス)が配信する便の現在の情報を取得することができます。

本Tipsでは特に、便の遅延情報や現在位置情報を取得する方法を解説します。これらの情報を経路検索結果画面や時刻表画面に反映することで、便ごとの状況をよりリッチに表示する機能を実装することが可能です。

なお本機能を利用するには、mixway APIの契約に加え各交通事業者のリアルタイム情報を利用するための許諾が必要です。詳細はお問い合わせフォームへご連絡ください。

関連する機能​

機能パス
リアルタイム便情報/v1/json/realtime/trip

各リクエストパラメータについて​

リアルタイム便情報を取得するためには、以下の2つのパラメータを指定しリクエストする必要があります。

パラメータ考え方
tripCodeトリップコード。ダイヤデータの中で便(鉄道・船・空路・海路)を一意に特定するためのコードです。:で繋ぐことで最大30件まで指定することができます。
engineVersionエンジンバージョン。経路探索エンジンやダイヤデータのバージョン(版)です。エンジンバージョンが進むとトリップコードは採番し直されます。よって異なるエンジンバージョンをまたいでトリップコードを利用することはできません。

トリップコードは経路探索系機能や鉄道駅時刻表で取得することができます。取得した結果経路群や時刻表には複数のトリップコードが含まれます。tripCode パラメータに:繋ぎで複数指定することで、複数のリアルタイム便情報を一括で取得することができます。

なお1回のリクエストで指定できるトリップコードは30件までです。これを超える件数を取得したい場合は、30件ごとに分割してリクエストするなどの実装を行う必要があります。

それぞれの値が取得できる主な機能

トリップコード​

機能トリップコードの取得位置
経路探索ResultSet.Course[].Route.Line[].tripCode
経路探索（リアルタイム）
前後のダイヤ探索
鉄道駅時刻表
※stationCodeとcode指定時		ResultSet.TimeTable[].HourTable[].MinuteTable[*].Stop.tripCode

エンジンバージョン​

機能エンジンバージョンの取得位置
経路探索ResultSet.engineVersion
経路探索（リアルタイム）
前後のダイヤ探索
鉄道駅時刻表
バージョン情報

レスポンスから便の遅延・現在位置情報を取得する​

リアルタイム便情報機能のレスポンスから便の遅延情報・現在位置情報を取得することができます。

返却される情報の範囲​

リクエスト時に指定したトリップコードが指し示す便のうち、以下の条件に当てはまる便の情報が取得できます。

  • 実行時点でリアルタイム情報が配信されていること。おおむね「その瞬間に運行されている」か「その日に運行される」必要があります。
  • 指定したアクセスキーで情報利用の許諾を得た交通事業者の便であること。
ヒント

条件に当てはまらない便の情報は返却されません。 指定値の全てに対応する情報が取得できるわけではなく、また場合によっては1つも返却されないこともあることに留意してください。

返却されるレスポンスの解釈​

リアルタイム便情報では、以下のようなレスポンスが返却されます(一部抜粋)。 Trip 配列には取得できた便のリアルタイム情報が格納され、 Trip[*].tripCodeによってどの便の情報であるかが判別できます。

{
    "ResultSet": {
        "Trip": [
            {
                "tripCode": "4124961", // トリップコード4124961が指し示す便は、A駅を定刻通り出発しB駅に定刻通り到着する見込み、またB駅を定刻通り出発する見込み
                "operationDate": "20241210",
                "position": "between",
                "From": {
                    "Station": {"code": "99991", "Name": "A駅"},
                    "Departure": {"Delay": {"unit": "seconds", "text": "0"}}
                },
                "To": {
                    "Station": {"code": "99992", "Name": "B駅"},
                    "Arrival": {"Delay": {"unit": "seconds", "text": "0"}
                    },
                    "Departure": {"Delay": {"unit": "seconds", "text": "0"}}
                }
            },
            {
                "tripCode": "4089633", // トリップコード4089633が指し示す便は、C駅に60秒遅れで到着し、C駅を60秒遅れで出発見込みまたは出発済み
                "operationDate": "20241210",
                "position": "from",
                "From": {
                    "Station": {"code": "99993", "Name": "C駅"},
                    "Arrival": {"Delay": {"unit": "seconds", "text": "60"}},
                    "Departure": {"Delay": {"unit": "seconds", "text": "60"}}
                }
            }
        ]
    }
}

position要素の解釈​

各便の情報 ResultSet.Trip[*] 配下の position 要素は、その列車・便が停車または走行している位置の状態を表します。現時点では from または between が返却され、それぞれ以下の状態を表します。なおこの返却値は、将来的に増える可能性があります。

positionの値表している状態備考
between便・列車が、 From と To に表される駅の間を走行している。通過駅がある列車において、駅間の発着端が通過駅を含めた駅によって表されるか、停車駅のみで表されるかは、交通事業者によって異なります。
from便・列車が、Fromに表される駅に停車しているか、その駅を発車し次駅に向かっている。Fromに表される駅に到着済みであることを表現しており、その駅に停車中なのか出発済みなのかは判別できない点に留意してください。

※「駅」には鉄道駅に加え、バス停・港・空港が含まれます。詳しくはdictionary-駅を参照してください。

列車・便の状態とそれを表すレスポンス形態​

リアルタイム便情報のレスポンスから、列車・便の遅延情報・現在位置情報をどのように解釈できるかを解説します。

便・列車の状態レスポンス例読み取れる情報

① A駅に停車している

A駅B駅
{
    "tripCode": "1234567",
    "operationDate": "20241210",
    "position": "from",
    "From": {
        "Station": {
            "code": "nnnnn",
            "Name": "A駅"
        },
        "Departure": {
            "Delay": {
                "unit": "seconds",
                "text": "60"
            }
        },
        "Arrival": {
            "Delay": {
                "unit": "seconds",
                "text": "0"
            }
        }
    }
}

・A駅に定刻通り到着したこと(その便の始発駅であるなどの理由で、From.Arrival要素が返却されないことがある)

・A駅を60秒遅れで出発する見込みであること

② A駅とB駅の間を走行している

A駅B駅
{
    "tripCode": "1234567",
    "operationDate": "20241210",
    "position": "from",
    "From": {
        "Station": {
            "code": "nnnnn",
            "Name": "A駅"
        },
        "Departure": {
            "Delay": {
                "unit": "seconds",
                "text": "60"
            }
        },
        "Arrival": {
            "Delay": {
                "unit": "seconds",
                "text": "0"
            }
        }
    }
}

※ ①と同じ形態で返却される

{
    "tripCode": "22232609",
    "operationDate": "20241010",
    "position": "between",
    "From": {
        "Station": {
            "code": "nnnnn",
            "Name": "A"
        },
        "Departure": {
            "Delay": {
                "unit": "seconds",
                "text": "60"
            }
        }
    },
    "To": {
        "Station": {
            "code": "mmmmm",
            "Name": "B"
        },
        "Arrival": {
            "Delay": {
                "unit": "seconds",
                "text": "120"
            }
        }
    }
}

・A駅に定刻通り到着したこと

・A駅を60秒遅れで出発する見込みであるか、60秒遅れで出発したこと

・(右のレスポンスのように To要素が返却された場合) B駅に120秒遅れで到着する見込みであること

③ B駅に到着した

A駅B駅
{
    "tripCode": "4080161",
    "operationDate": "20241010",
    "position": "from",
    "From": {
        "Station": {
            "code": "nnnnn",
            "Name": "B"
        },
        "Departure": {
            "Delay": {
                "unit": "seconds",
                "text": "120"
            }
        },
        "Arrival": {
            "Delay": {
                "unit": "seconds",
                "text": "0"
            }
        }
    }
}

・B駅に定刻通り到着したこと

・B駅を120秒遅れで出発する見込みであること(その便の終着駅であるなどの理由で、From.Departure要素が返却されないことがある)

上記は鉄道を例としていますが、バスにおいても同様です。 その時点のレスポンスから推測できる便・列車の状態に応じてUIを変化させることで、ユーザーにリアルタイムな情報を伝えることができます。

その他の留意点​

運行日(operationDate)の利用​

「運行日」はその便が何月何日運行分の便であるかを示す概念です。例えば「1/10 10:00に出発したある便」の運行日は1月10日です。都市部の鉄道などでは24時を超えて運行されている路線があります。このような路線において「1/11 0:01(= 1/10 24:01)に出発したある便」は、1月10日分の終電より前であるため、その運行日は1月10日として取り扱われます。

探索結果経路や鉄道駅時刻表に含まれる各便の運行日は、それぞれのレスポンスから把握することができます。またリアルタイム便情報では ResultSet.Trip[*].operationDate に、そのTrip要素が表す便の運行日がyyyyMMddの形で格納されています。

両者を突き合わせることで、異なる運行日の情報を反映してしまうことが防止できます。

ヒント

同じダイヤの2つの便には、運行日が異なっていても同じトリップコードが付与されることがあります。例えば1/1の「列車番号123C」の列車と翌1/2の同列車番号の列車は、いずれも同じトリップコードが付与される可能性があります。また同じ列車でも日によってトリップコードが変わることもあります。

便の情報を特定する実装では、運行日とトリップコードをセットで取り扱うことで便を一意に定めることができます。

悲観的な実装​

各交通事業者から配信されるリアルタイム情報はフォーマット・項目・格納される情報が様々です。リアルタイム便情報機能は、これらを「なるべく同一なフォーマット」として取得できるAPIです。そのため、他の機能を利用する実装と比較し、より悲観的に実装することをおすすめします。

例えば本機能のレスポンスには必須要素(返却されることが保証される要素)が少なく、多くがoptionalです。そのため画面上の表示に利用する要素を取り出す際は、存在チェックを行ってから取り出すことで安全性が高まります。

また交通事業者の新規対応・配信フォーマットの変更等により、「これまで仕様上ありえたが、実際のデータは存在しなかった」ような要素の組み合わせが返却され始めることがあります。あらかじめ設計上想定するレスポンス形態を定め、本機能から取得したレスポンスが想定する形態と異なる場合は、画面に表示しないフォールバックを設けるなどの工夫をすることで、ユーザーに誤った情報を伝えることを予防できます。

対応事業者​

リアルタイム便情報機能を利用するには、mixway APIの契約に加え各交通事業者のリアルタイム情報を利用するための許諾が必要です。どの交通事業者に対応しているか知りたい場合や実際に利用したい場合はお問い合わせフォームへご連絡ください。