駅すぱあとWebサービスでWebAPIを使ってみる

今年は[ヴァル研究所](http://www.val.co.jp/)もAdvent Calendarに参加してみようと思います。

「ヴァル研究所」という弊社の名前よりも製品名である「駅すぱあと」といえばピンとくる方も多いのではないでしょうか。
実際、中央線から見える弊社の社屋には「駅すぱあと」のロゴが掲げられています。
(社名は右側の方にあるのですが、中央線からは見えにくい位置に...)

さて、Advent Calendar第1日目の今日は「[駅すぱあとWebサービス](https://ekiworld.net/service/sier/webservice/index.html)」で駅すぱあとの機能をWebAPIから使い始めてみる話をしようと思います。

## 駅すぱあとWebサービス？

Windows上で動作するアプリケーションとして提供されている「駅すぱあと」の情報や機能をWebAPIから利用できるサービスです。

自社サービスの基盤にもなっており、iOSやAndroidアプリなどのサービスが「駅すぱあとWebサービス」を利用しています。

### WebAPIを使ってみる

WebAPIを利用するにはアクセスキーが必要になります。「[駅すぱあとWebサービス](https://ekiworld.net/service/lp/webservice/)」からお申込みいただくことでアクセスキーを取得できます。

企業に限らず、個人のお客様でも「フリープラン」をご利用いただけますので、まずはフリープランを試してみて、必要になったらスタンダードプランに移行するというご利用方法も可能です。

アクセスキーを取得したら、さっそくWebAPIを試してみましょう。まずは`/dataversion`です。その名前の通り「駅すぱあと」データの詳細情報を取得するAPIになります。

```xml
$ curl -s -XGET 'http://api.ekispert.jp/v1/xml/dataversion?key=<アクセスキー>' | xmllint --format -
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResultSet apiVersion="1.27.0.0" engineVersion="201612_02a">
  <Version create="20161202" createType="Edition" caption="知識ベース"/>
  <Version create="20161202" createType="Edition" caption="鉄道時刻表"/>
  <Version create="20161201" createType="Date" createComment="Now" caption="ＪＲ"/>
  <Version create="20161122" createType="Date" createComment="Now" caption="私鉄"/>
  <Version rangeTo="20170106" rangeFrom="20161001" create="20161201" createType="Edition" rangeCaption="有効期間" caption="航空時刻表"/>
  <Version create="20161203" createType="Edition" caption="高速・連絡・深夜急行バス"/>
  <Version create="20161201" createType="Edition" caption="船"/>
  <Version create="20161101" createType="Date" createComment="Now" caption="得トクきっぷデータ"/>
  <Version create="20160801" createType="HideDay" createComment="Now" caption="住所データ"/>
  <Copyrights companyId="2" company="株式会社交通新聞社">交承 平成25年68号
ＪＲデータの内容は、株式会社交通新聞社発行の「ＪＲ時刻表」2016年12月号に基づいています。
この時刻データを無断で転載・複写し、又は紙媒体、電磁媒体その他いかなる媒体に加工することも禁じます。


ＪＲバスデータの内容は、株式会社交通新聞社作成のデータ平成28年12月分に基づいています。この時刻データを無断転載・複写や電磁媒体等に加工することを禁じます。


一部の内容は株式会社ヴァル研究所が自らの責任により加工を加えたものです。
</Copyrights>
</ResultSet>
```

WebAPIのレスポンスはXMLまたはJSONで取得可能です。`/dataversion`のレスポンスをJSONで取得すると以下のようになります。
JavaScriptのJSONオブジェクトと組み合わせることを考えると、WebブラウザからWebAPIを利用する場合はJSONで取得するのがオススメです。

```json
$ curl -s -XGET 'http://api.ekispert.jp/v1/json/dataversion?key=<アクセスキー>' | jq .
{
  "ResultSet": {
    "apiVersion": "1.27.0.0",
    "engineVersion": "201612_02a",
    "Version": [
      {
        "create": "20161202",
        "createType": "Edition",
        "caption": "知識ベース"
      },
      {
        "create": "20161202",
        "createType": "Edition",
        "caption": "鉄道時刻表"
      },
      {
        "create": "20161201",
        "createType": "Date",
        "createComment": "Now",
        "caption": "ＪＲ"
      },
      {
        "create": "20161122",
        "createType": "Date",
        "createComment": "Now",
        "caption": "私鉄"
      },
      {
        "rangeTo": "20170106",
        "rangeFrom": "20161001",
        "create": "20161201",
        "createType": "Edition",
        "rangeCaption": "有効期間",
        "caption": "航空時刻表"
      },
      {
        "create": "20161203",
        "createType": "Edition",
        "caption": "高速・連絡・深夜急行バス"
      },
      {
        "create": "20161201",
        "createType": "Edition",
        "caption": "船"
      },
      {
        "create": "20161101",
        "createType": "Date",
        "createComment": "Now",
        "caption": "得トクきっぷデータ"
      },
      {
        "create": "20160801",
        "createType": "HideDay",
        "createComment": "Now",
        "caption": "住所データ"
      }
    ],
    "Copyrights": {
      "text": "交承 平成25年68号\nＪＲデータの内容は、株式会社交通新聞社発行の「ＪＲ時刻表」2016年12月号に基づいています。\nこの時刻データを無断で転載・複写し、又は紙媒体、電磁媒体その他いかなる媒体に加工することも禁じます。\n\nＪＲバスデータの内容は、株式会社交通新聞社作成のデータ平成28年12月分に基づいています。この時刻データを無断転載・複写や電磁媒体等に加工することを禁じます。\n\n一部の内容は株式会社ヴァル研究所が自らの責任により加工を加えたものです。\n",
      "companyId": "2",
      "company": "株式会社交通新聞社"
    }
  }
}
```

レスポンスのResultSet要素にあるengineVersionが'201612_02a’となっています。
駅すぱあとが持つ情報はこまめに更新されており、そのデータのバージョンがengineVersionとして取得できます。
利用者がengineVersionの値を参照・利用することはあまりないと思いますが、常に最新のデータが提供されているということが分かります。

## WebAPIのリファレンス

WebAPIの動作が確認できると、`/dataversion`以外のAPIも試してみたくなるかと思います。
APIリファレンスとして「[駅すぱあとWebサービスDocuments](http://docs.ekispert.com/v1/)」を公開しており、必要な情報はここに網羅されています。
また、「[平均待ち時間](http://docs.ekispert.com/v1/dictionary/average-time/)」「[平均路線](http://docs.ekispert.com/v1/dictionary/average-rail/)」といった独特の用語についても"[Dictionary](http://docs.ekispert.com/v1/dictionary/)"で解説されていますので、ぜひご参照ください。

フリープランについては、以下のドキュメントをご参照ください。

 * [駅すぱあとWebサービス - フリープラン Documents](http://docs.ekispert.com/v1/le/)

フリープランで利用できるAPIの機能としては以下になります。それぞれの機能について随時紹介して行ければと思います。

 * 付加情報
   * [駅付加情報](http://docs.ekispert.com/v1/le/station/info.html) 
 * 会社情報
   * [会社情報](http://docs.ekispert.com/v1/le/corporation.html) 
 * 探索
   * [経路探索](http://docs.ekispert.com/v1/le/search/course/light.html)
 * 路線情報
   * [路線情報](http://docs.ekispert.com/v1/le/rail.html)
   * [線区情報](http://docs.ekispert.com/v1/le/line.html)
 * 駅情報
   * [駅情報](http://docs.ekispert.com/v1/le/station.html)
   * [駅簡易情報](http://docs.ekispert.com/v1/le/station/light.html)

## まとめ

「[駅すぱあとWebサービス](https://ekiworld.net/service/sier/webservice/index.html)」を利用して駅すぱあとの機能をWebAPIから利用する手順を簡単に紹介してみました。2日目以降の記事では、APIの各機能を実例を交えて解説してみようと思います。