定期情報の更新
定期情報の更新を行います。
駅や路線は、新設や廃止があるため、定期情報の定期的な更新を推奨しております。
関連URL
- 経路探索 /search/course/extreme
- 経路情報の更新判定 /toolbox/course/update
- 経路簡易探索 /search/course
- 平均待ち時間探索 /search/course/plain
定期情報を更新する手順
定期情報は、以下の手順で更新します。
1. 定期情報の更新が必要かチェックする
定期情報の更新が必要かどうか、チェックするタイミングによって、使用するAPIが異なります
- 交通費精算(定期区間控除)などで随時チェックする
- 通勤費管理(定期代支給)などで定期的にチェックする
2. 定期情報を更新する
定期情報の更新を行う際、更新する対象のデータによって、使用するパラメータが異なります
- 「定期経路シリアライズデータ」と「定期経路の表示用文字列」を再取得する
- 「定期経路文字列」を再取得する
1. 定期情報の更新が必要かチェックする
交通費精算(定期区間控除)などで随時チェックする
経路探索で定期区間の控除を行うタイミングでチェックします。
割り当て対象種別ResultSet/Course/AssignStatus/kindがteikiの定期割り当てステータスを表す要素ResultSet/Course/AssignStatusのうち、定期情報の更新判定ステータスコードを表すrequireUpdateにより、割り当てた経路情報に更新の必要があるかを確認できます。
ここでは浅草:東武伊勢崎線区間準急:Down:業平橋という定期経路文字列を例としています。
※ リクエスト例では日本語で記述しておりますが、リクエストパラメータに日本語が含まれる場合には、日本語の部分をUTF8でURLエンコード(パーセントエンコード)してください。
GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&addAssignStatus=true&viaList=浅草:とうきょうスカイツリー&assignDetailRoute=浅草:東武伊勢崎線区間準急:Down:業平橋&time=1000
<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.27.0.0" engineVersion="201810_01a">
<Course searchType="departure" dataType="onTimetable">
:
<!-- requireUpdate属性には、定期経路文字列に旧名称の駅名が指定されていることを表す1が返っています。これは定期経路文字列のうち、業平橋駅がとうきょうスカイツリー駅と改称されたためです。 -->
<AssignStatus requireUpdate="1" kind="teiki" code="0" />
<Route ...>
:
<Point index="2">
<Station code="22859">
<Name>とうきょうスカイツリー</Name>
:
</Station>
:
</Point>
</Route>
</Course>
</ResultSet>
定期情報の更新判定ステータスコードには、定期情報の更新が必須であることを示すものと、早めの更新が推奨されることを示すものがあります。
それぞれのステータスコードが表す意味については定期情報の更新判定ステータスコードをご覧ください。
通勤費管理(定期代支給)などで定期的にチェックする
経路情報の更新判定を使って、定期的にチェックします。
ここでは、浅草:東武伊勢崎線区間準急:Down:業平橋という定期経路文字列を例としています。
※ リクエスト例では日本語で記述しておりますが、リクエストパラメータに日本語が含まれる場合には、日本語の部分をUTF8でURLエンコード(パーセントエンコード)してください。
GET /v1/xml/toolbox/course/update?key=アクセスキーを入力してください&stationNameList=浅草:業平橋&railNameList=東武伊勢崎線区間準急
<ResultSet apiVersion="1.27.0.0" engineVersion="202005_04a">
<Update>
<Type>station</Type>
<Point index="1">
<Station code="22495">
<Name>浅草</Name>
<Type>train</Type>
<Yomi>あさくさ</Yomi>
</Station>
<Status code="0" />
</Point>
<Point index="2">
<Station code="22859">
<OldName>業平橋</OldName>
<Name>とうきょうスカイツリー</Name>
<Type>train</Type>
<Yomi>とうきょうすかいつりー</Yomi>
</Station>
<Status code="1" />
</Point>
</Update>
<Update>
<Type>rail</Type>
<Line index="1">
<Name>東武伊勢崎線区間準急</Name>
<Status code="0" />
</Line>
</Update>
</ResultSet>
ステータスコードが「0:更新なし」以外の場合は、更新することが推奨されます。 それぞれのステータスコードが表す意味については経路情報の更新判定のステータスコードをご確認ください。
2. 定期情報を更新する
「定期経路シリアライズデータ」と「定期経路の表示用文字列」を再取得する
定期経路シリアライズデータが再現できなくなる場合があります。
定期経路シリアライズデータを取得する際に保存した、定期経路の表示用文字列ResultSet/Course/Teiki/DetailRouteの発着駅を利用して、再度経路探索を行います。
定期情報の取得については定期情報の取得をご覧ください。
GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=高円寺:渋谷
「定期経路文字列」を再取得する
定期経路文字列が再現できなくなる場合があります。
再現ができなくなる場合には、定期経路文字列を更新する必要があります。
路線・方向を固定して再取得する場合
経路探索/search/course/extremeのfixedRailListパラメータとfixedRailDirectionListパラメータを利用することで、路線と方向を固定して平均探索を行うことができます。
■ 定期経路文字列例
高円寺:ＪＲ中央線快速:Up:新宿:ＪＲ山手線内回り:Down:渋谷
定期経路文字列を以下のように分解して再探索します。
viaList=高円寺:新宿:渋谷fixedRailList=ＪＲ中央線快速:ＪＲ山手線内回りfixedRailDirectionList=Up:Down
※リクエスト例では日本語で記述しておりますが、リクエストパラメータに日本語が含まれる場合には、日本語の部分をUTF8でURLエンコード(パーセントエンコード)してください。
GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=高円寺:新宿:渋谷&searchType=plain&fixedRailList=ＪＲ中央線快速:ＪＲ山手線内回り&fixedRailDirectionList=Up:Down
