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

定期券利用時の運賃計算

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

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


 Attention!

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

関連URL

手順

経路探索を行う

定期情報を用いて、経路探索 /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=高円寺:JR中央線快速:Up:新宿:JR山手線内回り: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>JR湘南新宿ライン・逗子行</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>JR湘南新宿ライン・逗子行</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 / TypeWithTeikiとなっており、FareSummaryが定期区間分の運賃が控除がされた値になっています。


  note

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

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


 Attention!

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