f:id:kumatira:20190228101926j:plain

(※ 今回は「駅すぱあとWebサービススタンダートプラン」「駅すぱあとWebサービス for Amazon」をご利用の方向けの記事です。「駅すぱあと for KDDI」など他の環境でのご利用の場合は記事内容と異なる場合があります。)

こんにちは!! 熊野です。

早速ですが、皆さんは「駅すぱあとWebサービス」に 課金対象外のAPI があることはご存知でしょうか? 今回はこの 課金対象外のAPI とは何なのか? そしてその中の駅簡易情報 (/station/light) 機能についてご紹介します!!

課金対象外のAPIって?

「駅すぱあとWebサービス」では、概ねアクセス数に応じて利用料金が発生するような料金体系をとっています。例えば「駅すぱあとWebサービス for Amazon」では、5000アクセスできるキーが5,400円、20000アクセスできるキーが21,600円という感じです。

この時の アクセス数 とは「駅すぱあとWebサービス」に何回リクエストをしたかでカウントされています。例えば、ある鉄道駅を起点として上限時間以内に到達できる鉄道駅を探索する範囲探索(/search/multipleRange)機能を5000回リクエストすると、5000リクエスト用のキーは無効になります。(「エラーの場合はアクセスしない」などの例外はあります。詳しくは→こちら)

これはスタンダードプランの利用アクセス算出も同様です。

ところが今回紹介する 課金対象外のAPI へのリクエストについては先述のようなカウントはされません。つまり何回リクエストしても、利用上限や利用基準リクエスト数には反映されないということです!!

そのような機能は以下の9つあります(2019年2月現在です。こちらで一覧をみることができます )。

駅簡易情報 /v1/{format}/station/light
地点生成 /v1/{format}/toolbox/course/point
測地系変換 /v1/{format}/toolbox/geo/convert
探索条件生成 /v1/{format}/toolbox/course/condition
回数券一覧 /v1/{format}/coupon/list
回数券詳細 /v1/{format}/coupon/detail
路線図一覧 /v1/{format}/railmap/list
鉄道運行情報路線リスト /v1/{format}/rail/service/list
データバージョン /v1/{format}/dataversion

今回はこの中から駅簡易情報 (/station/light) について便利な用途をお伝えします。

駅簡易情報って?

駅名(nameパラメータ)や都道府県名(prefectureCodeパラメータ)などを使って、駅の情報を検索、取得することができる機能です。

触ってみよう

例えば、nameに「こうえん」、prefectureCodeに「13(東京都)」を指定して駅簡易情報を利用します。

リクエスト例

https://api.ekispert.jp/v1/json/station/light?name=こうえん&prefectureCode=13&key=YOUR_API_KEY

レスポンス例

{
  "ResultSet": {
    //略
    "Point": [
      {
        "Station": {
          "code": "63117",
          "Name": "公園入口(江戸川区)／京成バス",
          "Type": {
            "text": "bus",
            "detail": "local"
          },
          "Yomi": "こうえんいりぐち"
        },
        "Prefecture": {
          "code": "13",
          "Name": "東京都"
        }
      },
      {
        "Station": {
          "Name": "公園入口／小田急バス",
          //略
        },
        //略
      },
      {
        "Station": {
          "Name": "公園入口／京王バス",
          //略
        },
        //略
      },
      {
        "Station": {
          "Name": "高円寺",
          "Type": "train",
          //略
        },
        //略
      },
//略

するとこんな感じで「こうえん」から始まる東京都内の駅の情報が取れます。ここで駅情報(/station)と何が違うの?と疑問を持たれる方もいるかもしれません。

何が違うの?

よく似ている2つの機能から取得できる情報を比較してみましょう。

	駅簡易情報	駅情報
パス	`/station/light`	`/station`
都道府県	○	○
駅名	○	○
駅コード	○	○
読みかな	○	○
交通種別	○	○
緯度経度情報	-	○
出口の名称	-	○
出口の緯度経度情報	-	○
最大取得件数	30	100

「あれ?駅簡易情報って完全に下位互換な機能なの?」となりますね。駅簡易情報はその名の通り、取得できる情報がかなり限られています。ですが、駅簡易情報が活躍する場所があります。それがインクリメンタルサーチです。

インクリメンタルサーチ

駅簡易情報が活躍するのがインクリメンタルサーチの実装時です。というよりインクリメンタルサーチを作る開発者が便利に使える機能として駅簡易情報が作られました!!

インクリメンタルサーチでは、ユーザー入力に応じて頻繁にサーバーサイドへのアクセスが発生します。そんな高頻度アクセス下でも快適に使っていただくため、駅簡易情報では取得できる項目を最小限に削ぎ落としレスポンス軽量化を図っています。また検索窓での利用を想定しているため返却される駅数は最大30駅になっています。先ほどのサンプルの様に都道府県や交通種別(鉄道、路線バスなど)での絞り込みも使いながらご利用ください!!

インクリメンタルサーチをした時のネットワークアクセスを見てみましょう。Developer Toolsを見るとこのように数秒間で何回も「駅すぱあとWebサービス」にリクエストしています。

f:id:kumatira:20190227212609p:plain — (下記紹介記事より)

もしこの1回ごとに課金カウントされるとすると、すぐに利用上限や利用基準リクエスト数に達してしまいますよね😇😇

ところが 駅簡易情報 なら大丈夫!!先述の通りこの機能は何回リクエストしても課金対象としてカウントされることはありません。ですのでユーザーの入力ごとに多くのアクセスが発生しても安心なんです!!同様の使い方で駅情報にリクエストするよりも課金対象カウントをグッと抑えることができますね。

ちなみに昔、この駅簡易情報機能を使って、Vue.jsで駅名インクリメンタルサーチを作ってみた記事を書きました。ぜひご覧ください。

f:id:kumatira:20190228094520g:plain — 出来上がるもの

qiita.com

このインクリメンタルサーチでユーザーが指定する駅コードを取得し、駅情報(/station)や駅付加情報(/station/info)へリクエストすればより詳細な駅の情報を取得することができます。もちろんそのまま経路探索(/search/course/extreme)などに移ることも可能です。