オフピーク定期券の金額取得と払い戻しに対応しました

こんにちは、駅すぱあとWebサービス開発チームの山崎です。

この度「駅すぱあとWebサービス」では、ＪＲ東日本より2023年3月18日に発売されるオフピーク定期券のサービス開始に伴い、オフピーク定期券の金額取得と払い戻し計算に対応しました。

オフピーク定期券とは

オフピーク定期券とは、平日の朝のピーク時間帯以外で定期券として利用できる、通常の通勤定期券より割安な定期券になります。

詳細については以下の公式サイトを御覧ください。 www.jreast.co.jp

オフピーク定期券の金額取得について

まず、オフピーク定期券の金額取得について説明します。

今回、探索条件生成機能にオフピーク定期券の計算設定を行うパラメータが新規に追加されました。

探索条件生成機能でオフピーク定期券の計算を有効にした探索条件を生成し、生成した探索条件で経路探索を行うことで、オフピーク定期券の金額を取得することができます。

探索条件生成機能に新規に追加されたオフピーク定期券の計算設定をするパラメータと仕様は以下のとおりです。

機能名：探索条件生成（/toolbox/course/condition）
パラメータ名： offpeakTeiki
値
- true：計算する
- false：計算しない（デフォルト）

docs.ekispert.com

なお、パラメータの値のデフォルトは「計算しない」となり、今回の対応によって既存のサービスに影響が出ることはありません。

このoffpeakTeikiパラメータを利用して、経路探索機能にてオフピーク定期券の金額を取得します。

まずは、探索条件生成機能を利用し、オフピーク定期券の計算を有効にした探索条件を生成します。

https://api.ekispert.jp/v1/xml/toolbox/course/condition?key=アクセスキー&offpeakTeiki=true

結果として、以下のような探索条件が取得できます。

<ResultSet apiVersion="1.27.0.0" engineVersion="202301_02a">
   <Condition>T32212332323191:F33211221200002:A23121141:</Condition>
</ResultSet>

この取得した探索条件を指定して、経路探索機能を実行します。

https://api.ekispert.jp/v1/xml/search/course/extreme?key=アクセスキー&viaList=北千住:上野:大宮(埼玉県)&date=20230318&searchType=plain&conditionDetail=T32212332323191:F33211221200002:A23121141

※ わかりやすいように駅名を名称で指定していますが、駅コードの利用を推奨しています。

経路探索の実行結果は以下のようになり、定期代の金額を返す要素である ResultSet / Course / Price / kind の値が Teiki1、Teiki3、Teiki6、Teiki12 の Price要素にoffpeakTeiki属性が返ります。

<ResultSet apiVersion="1.27.0.0" engineVersion="202301_02a">
   <Course searchType="plain" dataType="plain">
      <Route index="1" timeOther="20" timeOnBoard="38" distance="341" timeWalk="0" transferCount="1" ...>
         <Point index="1">
            <Station code="22630">
               <Name>北千住</Name>
                 :
         </Point>
         <Line index="1" teiki1Index="1" teiki3Index="1" teiki6Index="1" timeOnBoard="11" ...>
            <Name>ＪＲ常磐線快速</Name>
              :
         </Line>
         <Point index="2">
            <Station code="22528">
               <Name>上野</Name>
                 :
         </Point>
         <Line index="2" teiki1Index="1" teiki3Index="1" teiki6Index="1" ...>
            <Name>ＪＲ東北本線(上野－宇都宮)</Name>
              :
         </Line>
         <Point index="3">
            <Station code="21987">
               <Name>大宮(埼玉県)</Name>
                 :
         </Point>
      </Route>
      <SerializeData>...</SerializeData>
      <Teiki>...</Teiki>
      <Price ...>...</Price>
      <Price kind="Teiki1Summary">
         <Oneway>13030</Oneway>
      </Price>
      <!-- 定期区間1の1ヶ月定期代(13030円)はオフピーク定期の金額であることを表す -->
      <Price fareRevisionStatus="none" offpeakTeiki="true" toLineIndex="2" fromLineIndex="1" passClassIndex="1" kind="Teiki1" index="1" selected="true" nikukanteikiIndex="1">
         <Type>Teiki1</Type>
         <Oneway>13030</Oneway>
         <RevisionStatus>latest</RevisionStatus>
      </Price>
      <Price kind="Teiki3Summary">
         <Oneway>37120</Oneway>
      </Price>
      <!-- 定期区間1の3ヶ月定期代(37120円)はオフピーク定期の金額であることを表す -->
      <Price fareRevisionStatus="none" offpeakTeiki="true" toLineIndex="2" fromLineIndex="1" passClassIndex="1" kind="Teiki3" index="1" selected="true" nikukanteikiIndex="1">
         <Type>Teiki3</Type>
         <Oneway>37120</Oneway>
         <RevisionStatus>latest</RevisionStatus>
      </Price>
      <Price kind="Teiki6Summary">
         <Oneway>62600</Oneway>
      </Price>
      <!-- 定期区間1の6ヶ月定期代(62600円)はオフピーク定期の金額であることを表す -->
      <Price fareRevisionStatus="none" offpeakTeiki="true" toLineIndex="2" fromLineIndex="1" passClassIndex="1" kind="Teiki6" index="1" selected="true" nikukanteikiIndex="1">
         <Type>Teiki6</Type>
         <Oneway>62600</Oneway>
         <RevisionStatus>latest</RevisionStatus>
      </Price>
      :
   </Course>
   :
</ResultSet>