駅すぱあとの「駅コード」の話。

[ヴァル研究所Advent Calendar 2016](http://qiita.com/advent-calendar/2016/val) 3日目は「[駅コード](http://docs.ekispert.com/v1/dictionary/station-code/)」についてお話ししようと思います。

## 駅コードの例

「[駅コード](http://docs.ekispert.com/v1/dictionary/station-code/)」は駅を一意に特定するためのコードです。例えば、弊社の最寄駅である高円寺の駅コードは`22671`になります。

```shell-session
$ curl -s -XGET 'http://api.ekispert.jp/v1/json/station/light?key=<アクセスキー>&name=高円寺&type=train' | jq .
```

```json
{
  "ResultSet": {
    "apiVersion": "1.27.0.0",
    "engineVersion": "201612_02a",
    "Point": {
      "Station": {
        "code": "22671",
        "Name": "高円寺",
        "Type": "train",
        "Yomi": "こうえんじ"
      },
      "Prefecture": {
        "code": "13",
        "Name": "東京都"
      }
    }
  }
}
```

この「[駅コード](http://docs.ekispert.com/v1/dictionary/station-code/)」は弊社が独自に駅名と対応付けているコード体系で、「駅すぱあと」のみで使用できるコードです。
なぜ駅名と駅コードを対応させているかというと、[昨日の記事](http://qiita.com/valsitoh/items/786e8356d71cbcd9d934#レスポンスで得られる項目を把握する)でも少しお話ししたように、「駅名は変更されることがある」からです。
([「業平橋」→「とうきょうスカイツリー」駅に改名されています](http://railway.tobu.co.jp/guide/station/info/1103.html)、という話しですね)

駅すぱあとWebサービスが提供するWebAPIのパラメータには駅名指定できるものもありますが、基本的には駅コードの使用を推奨しています。
駅名が変更になった場合、古い駅名はレスポンスに含まれる`OldName`という要素で取得可能ですが、古い駅名をいつまでも返してくれるとは限らないので、修正の手間を考えると始めから駅コードを使用することをオススメします。

## 駅名が渡されてきたときのWebAPI呼び出し例

とはいっても、ユーザから渡される(入力されてくる)のは駅名なので、それを踏まえたWebAPIの呼び出し手順を示します。
手順としては一旦、駅名を駅コードに変換したのち、得られた駅コードを使用して必要なWebAPIを呼び出す形になります。

例として、[範囲探索](http://docs.ekispert.com/v1/api/search/range.html)という、指定した駅からn分以内の駅を検索する例を示します。駅名として「高円寺」が渡されたと想定します。

まずは駅コードを取得します。これは先の例にもあるように、[駅情報](http://docs.ekispert.com/v1/api/station.html)(または[駅簡易情報](http://docs.ekispert.com/v1/api/station/light.html))のWebAPIを使用します。

```shell-session
$ curl -s -XGET 'http://api.ekispert.jp/v1/json/station/light?key=<アクセスキー>&name=高円寺&type=train' | jq '.ResultSet.Point.Station.code'
"22671"
```

つぎに駅コードを指定して[範囲探索](http://docs.ekispert.com/v1/api/search/range.html)を呼び出します。
駅コードは`code`パラメータで指定し、探索範囲の上限時間(分)は`upperLimit`で指定します。
(ちなみに`upperLimit`は必須パラメータなので指定を忘れるとエラーになるのでご注意ください)

```shell-session
curl -s -XGET 'http://api.ekispert.jp/v1/json/search/range?key=<アクセスキー>&code=22671&upperLimit=10'
```

以下のレスポンスが返されてきます。

```json
{
  "ResultSet": {
    "apiVersion": "1.27.0.0",
    "engineVersion": "201612_02a",
    "Point": [
      {
        "Minute": "7",
        "Station": {
          "code": "22849",
          "Name": "中野(東京都)",
          "Type": "train"
        },
        "Prefecture": {
          "code": "13",
          "Name": "東京都"
        },
        "TransferCount": "0"
      },
      {
        "Minute": "7",
        "Station": {
          "code": "22494",
          "Name": "阿佐ケ谷",
          "Type": "train"
        },
        "Prefecture": {
          "code": "13",
          "Name": "東京都"
        },
        "TransferCount": "0"
      },
      {
        "Minute": "9",
        "Station": {
          "code": "22936",
          "Name": "東中野",
          "Type": "train"
        },
        "Prefecture": {
          "code": "13",
          "Name": "東京都"
        },
        "TransferCount": "0"
      },
      {
        "Minute": "9",
        "Station": {
          "code": "22573",
          "Name": "荻窪",
          "Type": "train"
        },
        "Prefecture": {
          "code": "13",
          "Name": "東京都"
        },
        "TransferCount": "0"
      }
    ]
  }
}
```

欲しい情報だけ一覧表示してみるとこんな感じですね。`upperLimit`パラメータで指定した時間(分)以内で到着できる駅の候補が取得できます。

```shell-session
$ curl -s -XGET 'http://api.ekispert.jp/v1/json/search/range?key=<アクセスキー>&code=22671&upperLimit=10' \
      | jq '.ResultSet.Point[]' \
      | egrep '(Minute|Name)'   \
      | paste - - - 
  "Minute": "7",            "Name": "中野(東京都)",         "Name": "東京都"
  "Minute": "7",            "Name": "阿佐ケ谷",     "Name": "東京都"
  "Minute": "9",            "Name": "東中野",       "Name": "東京都"
  "Minute": "9",            "Name": "荻窪",         "Name": "東京都"
```

## Tips:古い駅名から駅コードを取得する

駅すぱあとでは古い駅名も保持しており、あまり昔の駅名でなければ[駅情報](http://docs.ekispert.com/v1/api/station.html)の`oldName`パラメータに駅名を指定することで駅コードが取得できます。
([駅簡易情報]()には`oldName`パラメータは用意されていませんのでご注意ください)

例として、「業平橋」「とうきょうスカイツリー」の駅名について、[駅情報](http://docs.ekispert.com/v1/api/station.html)で調べてみましょう。

```shell-session
$ curl -s -XGET 'http://api.ekispert.jp/v1/json/station?key=<アクセスキー>&oldName=業平橋&type=train'|jq '.ResultSet.Point.Station.code'
"22859"
pleiades ~ $ curl -s -XGET 'http://api.ekispert.jp/v1/json/station?key=<アクセスキー>&name=とうきょうスカイツリー&type=train'|jq '.ResultSet.Point.Station.code'
"22859"
```

どちらも駅コード`22859`が返されているので、同じ駅であることがわかります。

## まとめ

駅すぱあとWebサービスで駅を一意に特定するためのコードである「[駅コード](http://docs.ekispert.com/v1/dictionary/station-code/)」について解説してみました。
駅名の場合は駅の名称変更があると対応が必要になりますが、あらかじめ駅コードを使用するようにしておくことで、対応の手間をなくすことができます。