二区間定期券などの特殊な定期券利用時の運賃計算

定期券利用時の運賃計算を行う際に、定期経路に定期券の種類として複数の選択肢が存在する場合があります。
例えば、「一般定期」と「だぶるーと」がある場合、「一般定期」と「全線定期」がある場合、等です。

「一般定期」だと利用できない区間も、特殊な定期券であれば利用できる場合があります。
そのため、ユーザが所有している定期券の種類に適宜切り替えて、定期区間控除を行う必要があります。

ここでは、定期券の種類のうち、二区間定期券として定期区間控除を行う方法を記載します。

Attention!

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

手順

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

二区間定期券は、デフォルトでは経路探索結果に返りません。
二区間定期券の利用を有効にするには、探索条件生成のnikukanteikiパラメータに、二区間定期券の利用フラグを指定します。
なお、定期券の種類のうち、二区間定期券に分類されるもの以外は、探索条件での利用フラグの指定によらず、経路探索結果から取得できます。

GET /v1/xml/toolbox/course/condition?key=アクセスキーを入力してください&nikukanteiki=true

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.27.0.0" engineVersion="202010_02a">
  <Condition>T3221233232319:F3321122220000:A23121141:</Condition>
</ResultSet>

2. 定期情報を取得する

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

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

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

3. 経路探索を行う

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

2のレスポンスのResultSet/Course/PassStatusのうち、二区間定期券を表しているPassStatus（kind="nikukanteiki"）のindexの値を、assignPassClassIndexパラメータの値に指定して、定期券の種類を切り替えます。

Attention!

※ 現在、定期券の種類の選択において、assignNikukanteikiIndexの利用は非推奨としています。これから開発を始める方は、assignPassClassIndexをご利用ください。

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で取得した定期経路シリアライズデータ}}&assignPassClassIndex=2

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

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=池袋:椎名町&searchType=plain&assignDetailRoute=池袋:東京メトロ有楽町線(和光市－新木場):Up:小竹向原:西武有楽町線:Down:練馬&assignPassClassIndex=2

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.26.0.0" engineVersion="201602_02a">
    :
    <Price toLineIndex="1" fromLineIndex="1" kind="Fare" index="1" selected="true" ...>
      <Type>WithTeiki</Type>
      <Oneway>0</Oneway>
      <Round>0</Round>
    </Price>
     :
</ResultSet>

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

note

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

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=池袋:椎名町&searchType=plain&assignDetailRoute=池袋:東京メトロ有楽町線(和光市－新木場):Up:小竹向原:西武有楽町線:Down:練馬

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.26.0.0" engineVersion="201602_02a">
  <Error code="E153">
    <Message>定期券で利用できる経路がありません。</Message>
  </Error>
</ResultSet>

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

Attention!

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