本記事はヴァル研究所の支援として作成された記事です
駅すぱあとはAPIを公開しており、駅情報や経路探索などをAPI経由で行えます。メソッドはすべてGETメソッドで、情報取得系のみです。レスポンスはJSONまたはXMLで返ってきます。
この駅すぱあと APIを利用しやすくするSDKを開発しはじめました。SDKはPythonで作っており、CLIやWebサービスなどから利用できます。
今回は、スタンダードプランで提供されている定期券の払い戻し計算APIに対応しました。
定期券は有効期間が長いほど割引率が高くなりますが、定期券の利用中にお引越しや異動などで購入した定期券を払い戻す必要がある場合もあります。
それでは、SDKの使い方について解説します。
必要な情報
SDKを利用する際にはAPIキーが必要です。無料トライアルがあるので、こちらから取得してください。
注意点
- SDKは非公式です。公式サポートへの問い合わせはご遠慮ください
インストール
インストールは pip コマンドで行います。
pip install ekispert
初期化
先ほど取得したAPIキーを使ってSDKを初期化します。
from ekispert.client import Ekispert
client = Ekispert("YOUR_API_KEY")
定期券の払い戻し計算の設定
定期券の払い戻し計算を行う際には、まず経路を探索して、そのシリアライズデータが必要です。経路探索は CoursePlainQuery にて行います。
query = client.coursePlainQuery()
query.from_ = '高円寺'
query.to = '東京'
query.date = datetime.now()
results = query.execute()
そして、レスポンスにある serialize_data を使って、定期券の払い戻し計算用のクエリークラスである CourseRepaymentQuery にて払い戻し計算を行います。
query2 = client.courseRepaymentQuery()
query2.serialize_data = results[0].serialize_data
query2.separator = ['1', 'true']
results2 = query2.execute()
検索条件は 定期券の払い戻し計算 - 駅すぱあと API Documents 駅データ・経路検索のWebAPI にあるものを指定できます。
検索の実行
検索条件を設定したら、検索処理を実行します。結果は CourseRepaymentResponse クラスになります。 repayment_list と teiki_route というプロパティを持ちます。
assert results2.repayment_list is not None
assert results2.teiki_route is not None
レスポンスは定期券の払い戻し計算 - 駅すぱあと API Documents 駅データ・経路検索のWebAPIを参照してください。各属性はスネークケースになっています。
エラーだった場合
もし検索がエラーだった場合は例外処理が返ってきます。try-catchで例外をキャッチして、エラーメッセージを表示します。
try:
results2 = query2.execute()
except Error as e:
print(f"Error: {e}")
成功した場合
処理が成功した場合、 repayment_list に定期券の払い戻し情報、そして teiki_route に定期券の払い戻し用経路情報が入っています。
results2.repayment_list.validity_period # 6
results2.repayment_list.repayment_tickets[0].fee_price_value # 220
results2.teiki_route.teiki_route_sections[0].points[0].prefecture.name # '東京都'
results2.teiki_route.teiki_route_sections[0].points[0].station.name # '高円寺'
ソースコード
SDKのコードは以下のリポジトリにて公開しています。ライセンスはMIT Licenseです。
まとめ
定期券の払い戻しは計算が複雑なので、システム自動化の際にはぜひ駅すぱあと APIを利用してください。SDKを使えば、Excelなどから簡単に利用できます。
何か不具合があれば、Issueにて連絡いただければ対応します。
Discussion