はじめに
定期券
交通費精算(定期区間控除)
通勤費管理(定期代支給)
探索
運賃
探索結果
探索条件
地点
路線
路線図

二区間定期券利用時の運賃計算

二区間定期券による定期区間控除を行います。


 Attention!

定期情報を利用することが出来る経路は鉄道のみです。

関連URL

手順

1. 経路探索に用いる条件を生成する

探索条件生成のnikukanteikiパラメータに、二区間定期券の利用フラグを指定します。

GET /v1/xml/toolbox/course/condition?key=アクセスキーを入力してください&nikukanteiki=true
<ResultSet apiVersion="1.26.0.0" engineVersion="201601_02a">
<Condition>T3221233232319:F332112222000:A23121141:</Condition>
</ResultSet>

2. 定期情報を取得する

詳しくは、定期情報の取得をご確認ください。

※ リクエスト例では日本語で記述しておりますが、リクエストパラメータに日本語が含まれる場合には、日本語の部分をUTF8でURLエンコード(パーセントエンコード)してください。

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=池袋:練馬&searchType=plain&conditionDetail=T3221233232319:F332112222000:A23121141:

3. 経路探索を行う

2で取得または作成した定期情報を用いて、経路探索/search/course/extremeを行います。

2のレスポンスで出力される、ResultSet/Course/PassStatusで、二区間定期券を表している要素のindexResultSet/Course/PassStatus/indexを、assignNikukanteikiIndexパラメータの値に利用します。


  note

定期区間控除時にaddAssignStatusパラメータにtrueを指定すると、定期区間控除定期情報の状態を表すResultSet/Course/AssignStatus要素が返ります。

定期割り当てステータスコードResultSet/Course/AssignStatus/codeは、探索結果に定期経路が割り当てられたか、割り当たらなかった場合はその理由を表しています。 この値を参照することで、ユーザーに適切なアラートを出すことができます。

また、定期情報の更新判定ステータスコードResultSet/Course/AssignStatus/coderequireUpdateは、割り当てた定期情報に更新の必要があるか、更新の必要がある場合はその理由を表しています。 この値を参照することで、必要な時にユーザーへ定期情報の更新を促すことができます。

それぞれのステータスコードが表す意味については、それぞれのDictionaryページ定期割り当てステータスコード定期情報の更新判定ステータスコードをご参照ください。


 Attention!

※ 現在、定期区間控除の計算において、bringAssignmentErrorによるエラーハンドリングは非推奨としています。これから開発を始める方は、addAssignStatusをご利用ください。

※リクエスト例では日本語で記述しておりますが、リクエストパラメータに日本語が含まれる場合には、日本語の部分をUTF8でURLエンコード(パーセントエンコード)してください。

「定期経路シリアライズデータ」の場合

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=池袋:椎名町&searchType=plain&assignTeikiSerializeData={{2で取得した定期経路シリアライズデータ}}&assignNikukanteikiIndex=2

「定期経路文字列」の場合

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=池袋:椎名町&searchType=plain&assignDetailRoute=池袋:東京メトロ有楽町線(和光市-新木場):Up:小竹向原:西武有楽町線:Down:練馬&assignNikukanteikiIndex=2
<ResultSet apiVersion="1.26.0.0" engineVersion="201602_02a">
:
<Price fareRevisionStatus="none" toLineIndex="1" fromLineIndex="1" kind="Fare" index="1" selected="true">
<Type>WithTeiki</Type>
<Oneway>0</Oneway>
<Round>0</Round>
</Price>
:

探索した経路内で定期券が利用されている事がわかります。


  note

実際に定期区間控除二区間定期券を利用して行われているのかは、3のリクエスト例からassignNikukanteikiIndexパラメータを除いて確かめることができます。

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=池袋:椎名町&searchType=plain&assignDetailRoute=池袋:東京メトロ有楽町線(和光市-新木場):Up:小竹向原:西武有楽町線:Down:練馬
<ResultSet apiVersion="1.26.0.0" engineVersion="201602_02a">
<Error code="E153">
<Message>定期券で利用できる経路がありません。</Message>
</Error>
</ResultSet>

assignRoute, assignDetailRouteは、デフォルトで普通定期を利用しているため、西武池袋線を利用する池袋-椎名町の経路では、定期券を利用することができなかったことが分かります。


 Attention!

定期券利用時の運賃計算を行う際にassignRouteパラメータを利用することも出来ますが、一部の環状線は逆方向も控除されてしまう事があるため、経路の厳密性を担保するために、路線の方向を考慮するassignDetailRouteパラメータの利用を推奨しています。 方向(上り・下り)の要素も付加したassignDetailRouteパラメータを指定することで、より正確に定期区間控除を行うことが可能となります。