駅すぱあと VBA SDKを使って、通勤費管理で定期情報の更新を行う

**本記事はヴァル研究所の支援として作成された記事です**

[駅すぱあとはAPIを公開](https://api-info.ekispert.com/)しており、駅情報や経路探索などをAPI経由で行えます。メソッドはすべてGETメソッドで、情報取得系のみです。レスポンスはJSONまたはXMLで返ってきます。

この駅すぱあと APIを利用しやすくするSDKを開発しはじめました。SDKはVBAで作っており、Excelなどから利用できます（Windowsのみ、macOSでは利用できません）。

今回は、通勤費管理を行う上での定期情報の更新方法を、[定期情報の更新 \- 駅すぱあと API Documents 駅データ・経路検索のWebAPI](https://docs.ekispert.com/v1/tips/update-teiki/)に記載されている内容を参考にしたSDKを使って紹介します。

通勤費管理を行う際、基本的には入社時や転居時に従業員から提出されたタイミングで定期券情報を登録し、通勤手当の経費精算に使用しますが、駅や路線は新設や廃止があるため、情報の定期的な更新を推奨しています。

## 必要な情報

SDKを利用する際にはAPIキーが必要です。[無料トライアルがあるので、こちらから取得](https://api-info.ekispert.com/form/trial/)してください。

## 注意点

- SDKはWindowsでのみ動作します
- SDKは非公式です。公式サポートへの問い合わせはご遠慮ください

## ファイルのインポート

[こちらのリポジトリ](https://github.com/EkispertAPIMania/VBA-SDK)にある `*.cls` と `*.bas` ファイルをすべてインポートします。これらは以下のライブラリを含んでいます。

- [VBA-tools/VBA-Dictionary](https://github.com/VBA-tools/VBA-Dictionary)
- [VBA-tools/VBA-Web: VBA-Web](https://github.com/VBA-tools/VBA-Web)
- [VBA-tools/VBA-JSON](https://github.com/VBA-tools/VBA-JSON)

## 初期化

先ほど取得したAPIキーを使ってSDKを初期化します。

```vb
Dim client As Ekispert
Set client = New Ekispert
client.ApiKey = "YOUR_API_KEY"
```

## 定期情報の更新

### 定期情報の更新が必要か定期的にチェックする

経路情報の更新判定を利用する方法です。この場合は、以下のようにAPIを呼び出します。

```
GET /v1/json/toolbox/course/update?key=アクセスキーを入力してください&stationNameList=浅草:業平橋&railNameList=東武伊勢崎線区間準急
```

SDKでは以下のようになります。

```vb
Dim Query2 As ToolboxCourseUpdateQuery
Set Query2 = Client.ToolboxCourseUpdateQuery()

Query2.StationNameList(0) = "浅草"
Query2.StationNameList(1) = "業平橋"
' Query2.StationNameList(0) = "浅草:業平橋" でもOK

Query2.RailNameList(0) = "東武伊勢崎線区間準急"
Dim Result2 As ResultSet
Result2 = Query2.Find()

' エラーチェック
If Not Result2.Success Then
    MsgBox Result2.Error.Message
    Exit Sub
End If

Debug.Print Result2.Updates(0).Points(1).Status.Code ' 1
Debug.Print Result2.Updates(0).Points(1).Station.Code ' 22859
```

ステータスコードが「0:更新なし」以外の場合は、更新推奨です。

### 定期情報を更新する
#### 「定期経路文字列」を再取得する

通勤手当の支給金額を確認する場合、定期経路シリアライズデータは利用できませんので注意してください（定期経路シリアライズデータは、外出時の交通費精算の際に、定期区間を0円にします）。そこで、登録している通勤経路に対して、「路線と方向を固定」して再取得を行います。

具体的には `/search/course/extreme` の `fixedRailList` と `fixedRailDirectionList` を利用します。APIの例としては、以下のようになります。

```
GET /v1/json/search/course/extreme?key=アクセスキーを入力してください&viaList=高円寺:新宿:渋谷&searchType=plain&fixedRailList=ＪＲ中央線快速:ＪＲ山手線内回り&fixedRailDirectionList=Up:Down
```

上記APIをSDKで実行する場合には、以下のようになります。

```vb
Dim Query1 As CourseExtremeQuery
Set Query1 = Client.CourseExtremeQuery()
' 使い回す場合には Query1.Reset を使ってリセットしてください

Query1.ViaList(0) = "高円寺"
Query1.ViaList(1) = "新宿"
Query1.ViaList(2) = "渋谷"
Query1.SearchType = Plain

Query1.FixedRailList(0) = "ＪＲ中央線快速"
Query1.FixedRailList(1) = "ＪＲ山手線内回り"

Query1.FixedRailDirectionList(0) = "Up"
Query1.FixedRailDirectionList(1) = "Down"

Dim Result4 As ResultSet
Result4 = Query1.Find()

If Not Result4.Success Then
    MsgBox Result4.Error.Message
    Exit Sub
End If

Debug.Print Result4.Courses(0).Teiki.DetailRoute
' 高円寺:ＪＲ中央線快速:Up:新宿:ＪＲ山手線内回り:Down:渋谷
```

このように、APIを直接コールするのに比べて、SDKを使うことで簡単に定期情報の更新が行えます。

## ソースコード

SDKのコードは以下のリポジトリにて公開しています。ライセンスはMIT Licenseです。

[EkispertAPIMania/VBA-SDK: Excel VBAなどで動作する駅すぱあと VBA SDKです（Windowsのみ）](https://github.com/EkispertAPIMania/VBA-SDK/tree/main)

## まとめ

駅情報やルートは適宜更新されるので、定期情報についても定期的な更新チェックが必要です。駅すぱあとAPIを使えば、そうしたチェックの手間を大幅に軽減できます。通勤定期券の支給金額などをシステム自動化する際に、ぜひ駅すぱあと APIを利用してください。本SDKを使えば、Excelなどから簡単に利用できます。

何か不具合があれば、Issueにて連絡いただければ対応します（macOSでは動かないので注意してください）。

[EkispertAPIMania/VBA-SDK: Excel VBAなどで動作する駅すぱあと VBA SDKです（Windowsのみ）](https://github.com/EkispertAPIMania/VBA-SDK)