定期券利用時の運賃計算

経路探索または経路の再現／定期券・指定列車利用を利用して、定期区間控除を行います。

※API利用時のイメージ図 (駅すぱあと API HTML5 インターフェースサンプル)

Attention!

定期区間控除が可能な経路は鉄道のみです。

手順

経路探索を行う

定期情報を用いて、経路探索 /search/course/extreme を行います。
定期情報の取得方法は定期情報の取得をご確認ください。

リクエスト例では経路探索/search/course/extreme を利用していますが、経路の再現／定期券・指定列車利用でも可能です。

note

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

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

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

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

Attention!

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

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

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

定期区間控除を行いたい経路に対して、事前に取得した定期経路シリアライズデータをassignTeikiSerializeDataパラメータに指定して経路探索を行います。

デフォルトでは、定期経路シリアライズデータを取得した時のエンジンバージョンと定期経路再現時のエンジンバージョンが同一でない場合はエラーとなります。
取得時と異なるエンジンバージョンにて定期経路シリアライズデータを利用したい場合は、checkEngineVersionパラメータにfalseを指定することで利用することができます。

ただし、エンジンバージョンが変わることで定期の割り当てが正しく行われない可能性があるため、定期割り当てステータスコードや定期情報の更新判定ステータスコードをチェックし、適切に控除されていることを確認するようにしてください。

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=新宿:恵比寿&checkEngineVersion=false&assignTeikiSerializeData=VkV4QaECp_rHAQEDpgEz7osEk8EBpViPwQGlWNXBAaVYuwWSwwEBA6RtBKVY1cQBAQIBA6RxBKVYuweRxQGlWI8CpVi7AwAEAQUACAEKAQ**--2ffa318938ac7a409fec1643d23af692c573ee53--0--79

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

定期区間控除を行いたい経路に対して、事前に取得した定期経路文字列をassignDetailRouteパラメータに指定して経路探索を行います。

GET /v1/xml/search/course/extreme?key=アクセスキーを入力してください&viaList=新宿:恵比寿&assignDetailRoute=高円寺:ＪＲ中央線快速:Up:新宿:ＪＲ山手線内回り:Down:渋谷

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet apiVersion="1.27.0.0" engineVersion="201803_03a">
   <Course searchType="departure" dataType="onTimetable">
      <Route timeOther="0" timeOnBoard="7" exhaustCO2="110" index="1" exhaustCO2atPassengerCar="840" distance="50" timeWalk="0" transferCount="0">
         <Point index="1">
            <Station code="22741">
               <Name>新宿</Name>
               <Type>train</Type>
               <Yomi>しんじゅく</Yomi>
            </Station>
            :
         </Point>
         <Line fareIndex="1" index="1" ... >
            <ArrivalState>
              <Type>extension</Type>
              <Datetime operation="today">2018-06-25</Datetime>
            </ArrivalState>
            <Name>ＪＲ湘南新宿ライン・逗子行</Name>
            <Type>train</Type>
            <DepartureState>
              <Type>normal</Type>
              <Datetime operation="today">2018-06-25</Datetime>
            </DepartureState>
            :
         </Line>
         <Point index="2">
            <Station code="22715">
               <Name>渋谷</Name>
               <Type>train</Type>
               <Yomi>しぶや</Yomi>
            </Station>
            :
         </Point>
         <Line fareIndex="2" index="2" ...>
            <ArrivalState>
             <Type>normal</Type>
             <Datetime operation="today">2018-06-25</Datetime>
            </ArrivalState>
            <Name>ＪＲ湘南新宿ライン・逗子行</Name>
            <Type>train</Type>
            <DepartureState>
              <Type>extension</Type>
              <Datetime operation="today">2018-06-25</Datetime>
            </DepartureState>
            :
         </Line>
         <Point index="3">
            <Station code="22548">
               <Name>恵比寿</Name>
               <Type>train</Type>
               <Yomi>えびす</Yomi>
            </Station>
            :
         </Point>
      </Route>
      <Price kind="FareSummary">
         <Oneway>140</Oneway>
         <Round>280</Round>
      </Price>
      <Price fareRevisionStatus="none" toLineIndex="1" fromLineIndex="1" kind="Fare" index="1" selected="true">
         <Type>WithTeiki</Type>
         <Oneway>0</Oneway>
         <RevisionStatus>latest</RevisionStatus>
         <Round>0</Round>
      </Price>
      <Price fareRevisionStatus="none" toLineIndex="2" fromLineIndex="2" kind="Fare" index="2" selected="true">
         <Type>Fare</Type>
         <Oneway>140</Oneway>
         <RevisionStatus>latest</RevisionStatus>
         <Round>280</Round>
      </Price>
      :
   </Course>
</ResultSet>

上記のレスポンスを見ると、定期区間のResultSet / Course / Price / TypeがWithTeikiとなっており、FareSummaryが定期区間分の運賃が控除がされた値になっています。

note

新宿～恵比寿はＪＲ山手線が通っており、乗り換えせずに行くことができますが、レスポンスでは渋谷駅で区間が途切れています。

これは、駅の状態(ResultSet/Course/Route/Line/DepartureState/Typeまたは ResultSet/Course/Route/Line/ArrivalState/Type)の値を見ることで、駅に乗り入れているのかそうでないのか判断することができます。新宿〜渋谷間のResultSet/Course/Route/Line/ArrivalState/Typeと、渋谷〜恵比寿間のResultSet/Course/Route/Line/DepartureState/Typeがextensionという値となっています。つまり、渋谷を通過する、という情報を表しているだけで、乗り換えは不要であることが分かります。

Attention!

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

定期情報を「オフピーク定期券」として利用する場合

経路探索や経路の再現／定期券・指定列車利用において、offpeakTeikiModeを指定した場合、既にユーザーで保持している定期券の情報に対して、offpeakTeikiModeを指定することができます。
※定期情報が通常の定期券／オフピーク定期券のどちらの場合でも、offpeakTeikiModeを指定することで、オフピーク定期券として定期券の区間控除を行うことができます。

取得した定期券の情報が、通常の定期券／オフピーク定期券かを区別しておきたい場合には、お客様のアプリケーション側で独自に値を保持するなどの必要があります。

定期券利用時の運賃計算

関連URL

手順

経路探索を行う

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

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

定期情報を「オフピーク定期券」として利用する場合