本記事はヴァル研究所の支援として作成された記事です
駅すぱあとはAPIを公開しており、駅情報や経路探索などをAPI経由で行えます。メソッドはすべてGETメソッドで、情報取得系のみです。レスポンスはJSONまたはXMLで返ってきます。
この駅すぱあと APIを利用しやすくするSDKを開発しはじめました。SDKはVBAで作っており、Excelなどから利用できます（Windowsのみ、macOSでは利用できません）。
今回は、スタンダードプランで提供されている定期券の払い戻し計算APIに対応しました。
定期券は有効期間が長いほど割引率が高くなりますが、定期券の利用中にお引越しや異動などで購入した定期券を払い戻す必要がある場合もあります。
それでは、SDKの使い方について解説します。
必要な情報
SDKを利用する際にはAPIキーが必要です。無料トライアルがあるので、こちらから取得してください。
注意点
- SDKはWindowsでのみ動作します
- SDKは非公式です。公式サポートへの問い合わせはご遠慮ください
ファイルのインポート
こちらのリポジトリにある *.cls と *.bas ファイルをすべてインポートします。これらは以下のライブラリを含んでいます。
初期化
先ほど取得したAPIキーを使ってSDKを初期化します。
Dim client As Ekispert
Set client = New Ekispert
client.ApiKey = "YOUR_API_KEY"
定期券の払い戻し計算の設定
定期券の払い戻し計算を行う際には、まず経路を探索して、そのシリアライズデータが必要です。経路探索は CourseExtremeQuery にて行います。
Dim Query1 As CourseExtremeQuery
Set Query1 = Client.CourseExtremeQuery()
' 出発地、目的地の設定
Query1.ViaList(0) = "高円寺"
Query1.ViaList(1) = "東京"
' 日付の設定
Query1.DateProp = Now
Dim Result1 As ResultSet
Result1 = Query1.Find()
そして、レスポンスにある SerializeData を使って、定期券の払い戻し計算用のクエリークラスである CourseRepaymentQuery にて払い戻し計算を行います。
Dim Query As CourseRepaymentQuery
Set Query = Client.CourseRepaymentQuery
' 探索結果のシリアライズデータを設定
Query.SerializeData = Result1.Courses(0).SerializeData
Query.Separator(0) = 1
Query.Separator(1) = "true"
検索条件は 定期券の払い戻し計算 - 駅すぱあと API Documents 駅データ・経路検索のWebAPI にあるものを指定できます。
検索の実行
検索条件を設定したら、検索処理を実行します。結果は ResultSet クラスになります。探索がうまくいったかどうかは ResultSet.Success の値で判定してください。
Dim Result As ResultSet
Result = Query.Find()
Debug.Print Result.Success ' True または False
エラーだった場合
もし探索がエラーだった場合は ResultSet.Error の中にエラー情報があります（駅すぱあと APIからのエラーの場合）。
If Not Result.Success Then
MsgBox Result.Error.Message
Exit Sub
End If
成功した場合
処理が成功した場合、 ResultSet.RepaymentList に定期券の払い戻し情報、そして ResultSet.TeikiRoute に定期券の払い戻し用経路情報が入っています。
Debug.Print Result.RepaymentList.ValidityPeriod ' 6
Debug.Print Result.RepaymentList.RepaymentTickets(0).FeePriceValue ' 220
Debug.Print Result.TeikiRoute.TeikiRouteSections(0).Points(0).Prefecture.Name ' 東京都
Debug.Print Result.TeikiRoute.TeikiRouteSections(0).Points(0).Station.Name ' 高円寺
ソースコード
SDKのコードは以下のリポジトリにて公開しています。ライセンスはMIT Licenseです。
EkispertAPIMania/VBA-SDK: Excel VBAなどで動作する駅すぱあと VBA SDKです（Windowsのみ）
まとめ
定期券の払い戻しは計算が複雑なので、システム自動化の際にはぜひ駅すぱあと APIを利用してください。SDKを使えば、Excelなどから簡単に利用できます。
何か不具合があれば、Issueにて連絡いただければ対応します（macOSでは動かないので注意してください）。
EkispertAPIMania/VBA-SDK: Excel VBAなどで動作する駅すぱあと VBA SDKです（Windowsのみ）