オフピーク定期券利用時の運賃計算に対応しました

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

この度「駅すぱあとWebサービス」では、ＪＲ東日本より2023年3月18日に発売されたオフピーク定期券について、オフピーク定期券利用時の運賃計算に対応しました。

過去にオフピーク定期券の金額取得と払い戻し計算に対応した内容についても紹介していますので、あわせてご覧ください。 blog.ekispert.com

オフピーク定期券とは

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

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

オフピーク定期券利用時の運賃計算について

オフピーク定期券利用時の運賃計算について説明します。

今回、以下の機能にオフピーク定期券利用時の運賃計算方法を設定するパラメータが新規に追加されました。

■ 対象機能

定期券利用時の運賃計算をする際に、オフピーク定期券を、オフピーク時間帯利用とみなして運賃計算をするか、ピーク時間帯利用とみなして運賃計算をするかを、設定することができます。

新規に追加されたオフピーク定期券の運賃計算を設定するパラメータと仕様は以下のとおりです。

パラメータ名：offpeakTeikiMode
値
- offpeakTime：オフピーク時間帯の利用とみなして運賃計算する (通常の定期券を利用した時の運賃計算と同じ)
- peakTime：ピーク時間帯の利用とみなして運賃計算する
説明
- オフピーク定期券利用時の計算モード。
- assignRoute, assignDetailRoute, assignTeikiSerializeDataのいずれか指定時のみ指定可。
- 省略可。未指定時は、オフピーク定期券として保存された定期券情報であっても、通常の通勤定期券として、運賃計算を行います。

また、このoffpeakTeikiModeパラメータは説明にも記載がある通り、定期情報（定期経路文字列、または定期経路シリアライズデータ）を利用して、定期控除をするときに指定するパラメータになりますが、定期情報が、通常の定期券かオフピーク定期券かに関係なく、offpeakTeikiModeパラメータが指定された場合に、定期情報をオフピーク定期券とみなして、運賃計算をします。

そのため注意点として、アプリケーションやサービスにおいて、オフピーク定期券の場合のみピーク時間帯の控除を可能にする、ということを実現したい場合には、アプリケーションやサービス側で、定期券がオフピーク定期券である情報を保持しておいていただく必要があります。定期券がオフピーク定期券かどうかを判断する情報につきましては、オフピーク定期券の金額取得と払い戻し計算に対応時のブログで紹介していますので、こちらをご確認ください。

blog.ekispert.com

具体例

今回は、以下のケースを例として説明します。

定期情報 : 三鷹-[JR中央線]->中野-[東京メトロ東西線]->神楽坂
探索経路 : 三鷹-[JR中央線]->中野-[東京メトロ東西線]->神楽坂

上記において、ピーク時間帯利用として運賃計算をした場合、「三鷹-[JR中央線]->中野」の区間はオフピーク定期券の適用区間になるため、運賃の控除がされず、「中野-[東京メトロ東西線]->神楽坂」の区間はオフピーク定期券の対象外区間となるため、通常の定期券と同様に運賃が控除されます。

サンプルのリクエストとレスポンスは以下の通りです。

■ サンプルリクエスト

https://api.ekispert.jp/v1/xml/search/course/extreme?key={アクセスキー}&time=0800&viaList=三鷹:神楽坂&assignDetailRoute=三鷹:ＪＲ総武線:Up:中野(東京都):東京メトロ東西線:Down:神楽坂&offpeakTeikiMode=peakTime&addAssignStatus=true&answerCount=1

■ サンプルレスポンス

<ResultSet apiVersion="1.27.0.0" engineVersion="202308_01a">
    <Course searchType="departure" dataType="onTimetable">
        <Route index="1" ...>
            <Point index="1">
                <Station code="22986">
                    <Name>三鷹</Name>
                      :
            </Point>
            <Line index="1" ...>
                <Name>東京メトロ東西線・西船橋行</Name>
                  :
            </Line>
            <Point index="2">
                <Station code="22849">
                    <Name>中野(東京都)</Name>
                      :
            </Point>
            <Line index="2" ...>
                <Name>東京メトロ東西線・西船橋行</Name>
                  :
            </Line>
            <Point index="3">
                <Station code="22591">
                    <Name>神楽坂</Name>
                      :
            </Point>
        </Route>
        <!-- 「三鷹-[JR中央線]->中野」区間は運賃が控除されていない -->
        <Price index="1" kind="Fare" fromLineIndex="1" toLineIndex="1" selected="true" ...>
            <Type>Fare</Type>
            <Oneway>180</Oneway>
            <RevisionStatus>latest</RevisionStatus>
            <Round>360</Round>
        </Price>
        <!-- 「中野-[東京メトロ東西線]->神楽坂」区間は運賃が控除されている -->
        <Price index="2" kind="Fare" fromLineIndex="2" toLineIndex="2" selected="true" ...>
            <Type>WithTeiki</Type>
            <Oneway>0</Oneway>
            <RevisionStatus>latest</RevisionStatus>
            <Round>0</Round>
        </Price>
        <Price kind="FareSummary">
            <Oneway>180</Oneway>
            <Round>360</Round>
        </Price>
        <Price kind="Teiki1Summary">
            <Oneway>13280</Oneway>
        </Price>
          :
        <PassStatus index="1" ...>...</PassStatus>
          :
        <SerializeData>...</SerializeData>
        <Teiki>
            <SerializeData>...</SerializeData>
            <DisplayRoute>三鷹--ＪＲ中央・総武線各駅停車--中野(東京都)--東京メトロ東西線--神楽坂</DisplayRoute>
        </Teiki>
        <!-- 0: 正常に定期経路が割り当てられた -->
        <AssignStatus requireUpdate="0" kind="teiki" code="0"/>
    </Course>
</ResultSet>

また、上記のサンプルリクエストでは、定期券を利用した運賃計算を行った際に、割り当てのステータスを返す addAssignStatus を有効にしています。今回は、一部の区間が控除されず、一部の区間が控除される、という結果になり、ステータスとしては一部の区間が控除されているため、「正常に定期経路が割り当てられた」というステータスが返ります。現時点では、割り当てステータスでは、オフピーク定期券のピーク時間帯の利用により、定期券区間で控除がされなかった、という情報を取得することができませんので、ご注意ください。

また、今回オフピーク定期券利用時の運賃計算について、経路結果表示の経路表示パーツ（expGuiCourse）に、「オフピーク定期券利用時の計算（オフピーク時間帯として計算する／ピーク時間帯として計算する）」を設定する関数 setOffpeakTeikiMode 、設定値を取得する関数 getOffpeakTeikiMode を追加します。こちらもよろしければご覧ください。

github.com

以下、GUIサンプルのイメージになります。

※ 経路表示パーツ