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

ヴァル研究所Advent Calendar 2016 3日目は「駅コード」についてお話ししようと思います。

駅コードの例

「駅コード」は駅を一意に特定するためのコードです。例えば、弊社の最寄駅である高円寺の駅コードは22671になります。

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

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

この「駅コード」は弊社が独自に駅名と対応付けているコード体系で、「駅すぱあと」のみで使用できるコードです。
なぜ駅名と駅コードを対応させているかというと、昨日の記事でも少しお話ししたように、「駅名は変更されることがある」からです。
(「業平橋」→「とうきょうスカイツリー」駅に改名されています、という話しですね)

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

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

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

例として、範囲探索という、指定した駅からn分以内の駅を検索する例を示します。駅名として「高円寺」が渡されたと想定します。

まずは駅コードを取得します。これは先の例にもあるように、駅情報(または駅簡易情報)のWebAPIを使用します。

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

つぎに駅コードを指定して範囲探索を呼び出します。
駅コードはcodeパラメータで指定し、探索範囲の上限時間(分)はupperLimitで指定します。
(ちなみにupperLimitは必須パラメータなので指定を忘れるとエラーになるのでご注意ください)

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

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

{
  "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パラメータで指定した時間(分)以内で到着できる駅の候補が取得できます。

$ 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:古い駅名から駅コードを取得する

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

例として、「業平橋」「とうきょうスカイツリー」の駅名について、駅情報で調べてみましょう。

$ 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サービスで駅を一意に特定するためのコードである「駅コード」について解説してみました。
駅名の場合は駅の名称変更があると対応が必要になりますが、あらかじめ駅コードを使用するようにしておくことで、対応の手間をなくすことができます。