鉄道会社ごとの定期券払い戻し額を調べる
複数の鉄道会社にまたがる定期券について、経路を分割しそれぞれの区間ごとに払い戻し額を計算します。
※API利用時のイメージ図 (駅すぱあと API HTML5 インターフェースサンプル)
関連URL
- 経路探索 /search/course/extreme
- 経路簡易探索 /search/course
- 平均待ち時間探索 /search/course/plain
- 定期券の払い戻し計算 /course/repayment
手順
1. 経路探索を行う
経路探索 /search/coruse/extreme などで経路探索を行い、対象定期券の経路シリアライズデータを取得します。
リクエスト例では経路探索を利用していますが、
ダイヤによる探索か平均待ち時間による探索かは問わないので、経路簡易探索や平均待ち時間探索も利用可能です。
ここでは高円寺駅から銀座駅までの経路を例とします。
※API利用時のイメージ図 (駅すぱあと for web)
GET /v1/xml/search/course/extreme?viaList=22671:22641
<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
<Course searchType="departure" dataType="onTimetable">
<SerializeData>
経路シリアライズデータ
</SerializeData>
:
</Course>
:
</ResultSet>
2. 経路を分割するセパレータを求める
定期券の払い戻し計算 /course/repaymentを利用して、対象の定期券の経路がどのように分割できるのかを求めます。serializeDataパラメータには1で取得した経路シリアライズデータを利用します。必要に応じて、changeSectionなどその他のパラメータも指定してください。
1の例のように、定期券の経路が複数の鉄道会社をまたがる場合、レスポンスにResultSet/TeikiRoute/SectionSeparator要素が追加されます。
GET /v1/xml/course/repayment?serializeData=1で取得した経路シリアライズデータ
<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
<TeikiRoute>
<TeikiRouteSection ...>...</TeikiRouteSection>
<SectionSeparator index="1" divided="false" changeable="true"/>
<TeikiRouteSection ...>...</TeikiRouteSection>
</TeikiRoute>
<RepaymentList ...>
:
</RepaymentList>
</ResultSet>
3. 経路を分割し払い戻し額を求める
定期券の払い戻し計算 /course/repaymentでは、separatorパラメータを用いることで、全ての区間について払い戻す場合と、経路を分割しそれぞれを別の区間として払い戻す場合とを切り替えることができます。separatorパラメータには2で取得した、分割したい場所を示すSectionSeparator要素のindexを指定します。
なお区間変更時の払い戻し額を取得したい場合は、払い戻しを区間変更として計算するかを設定するchangeSectionパラメータに、trueを指定します。必要に応じてその他のパラメータも指定してください。
※ 区間変更の払い戻し額を求める際の注意事項は、定期券の払い戻し額を調べるおよび、区間変更をご覧ください。
GET /v1/xml/course/repayment?separator=1,true&serializeData=1で取得した経路シリアライズデータ
<ResultSet apiVersion="1.27.0.0" engineVersion="201809_02a">
<TeikiRoute>
<TeikiRouteSection ...>...</TeikiRouteSection>
<SectionSeparator index="1" divided="false" changeable="true"/>
<TeikiRouteSection ...>...</TeikiRouteSection>
</TeikiRoute>
<RepaymentList ...>
<RepaymentTicket repayPriceValue="24250" ... changeableSection="true"/>
<RepaymentTicket repayPriceValue="35300" ... changeableSection="true"/>
</RepaymentList>
</ResultSet>
