本記事はヴァル研究所の支援として作成された記事です
駅すぱあとはAPIを公開しており、駅情報や経路探索などをAPI経由で行えます。メソッドはすべてGETメソッドで、情報取得系のみです。レスポンスはJSONまたはXMLで返ってきます。
この駅すぱあと APIを利用しやすくするSDKを開発しはじめました。SDKはPythonで作っており、CLIやWebサービスなどから利用できます。
今回は、交通費精算時に定期情報の更新を行うやり方について、定期情報の更新 - 駅すぱあと API Documents 駅データ・経路検索のWebAPIに記載されている内容を参考にしたSDKを使って紹介します。
外出時の交通費を申請する場合、通勤定期券を持っている区間は申請から控除しますが、登録していた定期情報で定期控除ができなくなっていた場合に、申請の時に通知が出せると便利です。
定期区間の情報は、駅や路線の新設や廃止があるため、定期情報の定期的な更新を推奨しています。
必要な情報
SDKを利用する際にはAPIキーが必要です。無料トライアルがあるので、こちらから取得してください。
注意点
- SDKは非公式です。公式サポートへの問い合わせはご遠慮ください
インストール
インストールは pip コマンドで行います。
pip install ekispertapi-sdk-comm
初期化
先ほど取得したAPIキーを使ってSDKを初期化します。
from ekispertapi_sdk_comm.client import Ekispert
client = Ekispert("YOUR_API_KEY")
定期券情報の作成
定期情報を、定期経路シリアライズデータとして作成する
定期券の情報を作成します。（ここでは、定期券情報がエラーとなるように、あえて廃駅を含む定期経路でサンプルを作成しています。）
GET /v1/json/search/course/extreme?key=アクセスキーを入力してください&viaList=長万部:中ノ沢&date=20240301&searchType=plain
SDKでは以下のようになります。
query = client.courseExtremeQuery()
query.add_assign_status = True
query.search_type = "plain"
query.via_list.append("長万部")
query.via_list.append("中ノ沢")
query.date = datetime.datetime(2024, 3, 1)
courses = query.execute()
print(courses[0].teiki.serialize_data) # 定期経路シリアライズデータ
print(courses[0].teiki.desplay_route) # 定期経路の表示用文字列
定期経路シリアライズデータは VkV4QaECp8rIAQEDpgE0160EksEBpU55wQGlT5kFkcMBAQMBBKVPmQeRxQGlTnkCpU|ZAwAEAAUACAEKAQwA--c8834d0c78fdac190fb61f2d54b78374e48017cf--0--63 のようになり、表示用文字列は 長万部:ＪＲ函館本線(森－長万部):Up:中ノ沢 のようになります。
定期情報の更新
定期情報の更新が必要かチェックする
日々の交通費精算の時に、定期区間の控除が失敗していないかをチェックする方法です。APIとしては、以下のように呼び出します（SDKではJSONを使っているので、その部分を変更しています）。
GET /v1/json/search/course/extreme?key=アクセスキーを入力してください&viaList=国縫:長万部
&searchType=plain
&assignTeikiSerializeData=VkV4QaECp8rIAQEDpgE0160EksEBpU55wQGlT5kFkcMBAQMBBKVPmQeRxQGlTnkCpU|ZAwAEAAUACAEKAQwA--7fc83b8180c61894bbec3b4a6b9cadf92b7a9b14--0--63
&addAssignStatus=true&checkEngineVersion=false
SDKでは以下のようになります。
query = client.courseExtremeQuery()
query.search_type = "plain"
query.via_list.append("国縫")
query.via_list.append("長万部")
query.assign_teiki_serialize_data = "VkV4QaECp8rIAQEDpgE0160EksEBpU55wQGlT5kFkcMBAQMBBKVPmQeRxQGlTnkCpU|ZAwAEAAUACAEKAQwA--7fc83b8180c61894bbec3b4a6b9cadf92b7a9b14--0--63"
query.check_engine_version = False
そして、探索を行います。
courses = query.execute()
courses[0].assign_status.require_update # True
courses[0].assign_status.code # 0
code は、指定した定期区間が正しく控除されたかを確認するステータスです。
code が 0 以外であれば、定期区間の控除ができなかったと判断できます。定期区間の控除ができなかった場合、ステータスコードを確認することで、控除ができない理由を知ることができます。以下は経路探索 - 駅すぱあと API Documents 駅データ・経路検索のWebAPIによる RequireUpdate の説明です。
定期割り当てステータスコード
定期割り当てステータスコードが0以外の場合は、定期区間の運賃は控除されていません。
- 0: 正常に定期経路が割り当てられた。
- 1: 定期券を利用しても運賃が変わらない、または高くなってしまう。
- 2: 定期区間を含む経路ではない。
- 3: 割引乗車券が含まれる経路のため、定期区間の控除計算ができない。
- 4: 定期情報から定期経路を再現できない。
- 5: 定期情報が不適切。
- 99: 予期しない理由により定期経路が割り当てられない。
またRequireUpdate は、定期券の情報が古くなっていないかを確認するステータスです。
RequireUpdate が 0 以外であれば、定期情報の更新が必要です。以下は経路探索 - 駅すぱあと API Documents 駅データ・経路検索のWebAPIによる RequireUpdate の説明です。
定期情報の更新判定ステータスコード
0以外の場合は定期情報の更新が必要です。
- 0: 更新の必要なし
- 1: 定期経路文字列に旧名称の駅名が指定されている
- 2: 定期経路文字列に指定された駅名が見つからない
- 3: 定期経路文字列に旧名称の路線名が指定されている
- 4: 定期経路文字列に指定された路線名が見つからない
- 5: 定期経路文字列の駅名もしくは路線名の廃止など
- 6: 定期経路シリアライズデータが不正
- 7: 定期情報が無効な値。（定期券が発売されていないなど）
定期情報を更新する
「定期経路シリアライズデータ」と「定期経路の表示用文字列」を再取得します。APIは以下のように呼び出します。
GET /v1/json/search/course/extreme?key=アクセスキーを入力してください&viaList=高円寺:渋谷&searchType=plain
SDKでは以下のようになります。 teiki.display_route が定期経路の表示用文字列です。
query = client.courseExtremeQuery()
query.via_list.append("高円寺")
query.via_list.append("渋谷")
query.search_type = "plain"
courses = query.execute()
print(courses[0].teiki.serialize_data) # 定期経路シリアライズデータ
print(courses[0].teiki.display_route) # 定期経路の表示
たとえば定期経路シリアライズデータは VkV...-81 のようになり、表示用文字列は 高円寺--ＪＲ中央線快速--新宿--ＪＲ山手線内回り--渋谷 のようになります。
このように、APIを直接コールするのに比べて、SDKを使うことで簡単に定期情報の更新が行えます。
ソースコード
SDKのコードは以下のリポジトリにて公開しています。ライセンスはMIT Licenseです。
まとめ
経路探索は今回紹介したものの他、前後のダイヤ探索や平均待ち時間探索などさまざまな種類があります。今後のSDKのアップデートにて対応する予定なので、ぜひご利用ください。
何か不具合があれば、Issueにて連絡いただければ対応します。
Discussion