駅すぱあと API BLOG

駅すぱあと APIの開発チームが作るブログです。

チャレンジ!!GWに「駅すぱあとWebサービス」に一気に入門!!

tips ハンズオン

f:id:kumatira:20190425104940j:plain

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

今回は「駅すぱあとWebサービス」の使い方を基本から解説してみます!!ドキュメントサイトの読み方なども併せて解説します。

いつもと比べてかなり長い記事です。「WebAPIとか『駅すぱあとWebサービス』とかちょっと気になってたんだよね 」という方は、お休みの日にぜひチャレンジしていただき、「駅すぱあとWebサービス」をはじめとするWebAPIを利用したプログラミングのきっかけにしてください!!

想定読者

  • WebAPIに馴染みのない方
  • これからWebAPIを使ったアプリケーションを作ってみたい方
  • 「駅すぱあとWebサービス」をこれから触ってみたいという方

説明しないこと(詳しい方向け)

  • POSTなど「駅すぱあとWebサービス」で利用しないHTTPメソッド
  • リクエストのうちURL文字列以外の内容

必要なもの

Webブラウザ

みなさんがこの記事を見ているブラウザでOKです。通常、WebAPIはなんらかのプログラムから利用しますが、簡単に体験するため今回はWebブラウザから「駅すぱあとWebサービス」を使ってみます。

「駅すぱあとWebサービス」からはJSONというフォーマットを使って情報を取得します。この際、結果をブラウザから見ると全ての内容が一行に繋がり、画像のように情報が確認しづらくなるかもしれません。

f:id:kumatira:20190424143126g:plain

JSONを見やすくするアドイン(拡張機能)を入れ、画像右のように情報が見やすく表示されるようにしましょう。Google Chromeをお使いの方は「JSONView」、Microsoft Edgeをご利用の方は「 JSON Formatter for Edge」などがおすすめです。そのほかのブラウザでも「ブラウザ名 JSON 拡張機能」などのキーワードで検索するとたくさん出てくると思います。

ドキュメント

WebAPIに関係する資料をまとめてドキュメントと呼ぶことがあります。その中でもWebAPIの詳しい仕様が書かれているのがリファレンスページです。「駅すぱあとWebサービス」に限らず、WebAPIを使った実装ではリファレンスを参照することが欠かせません。もしかしたらプログラムを組む時間よりリファレンスを眺めている時間の方が長いかも...🤔

「駅すぱあとWebサービス」のドキュメントサイトはこちら

docs.ekispert.com

詳しい仕様を書いたリファレンスページに加えて、以下のようなページも充実させています。

  • やりたいことから利用する機能を逆引きできるTips
  • 「駅すぱあと」独自の用語を解説するDictionary
  • 開発中に役に立つツールを集めたTools

などなど。自慢のドキュメントサイトです。ぜひ活用してください!

アクセスキー

「駅すぱあとWebサービス」はアクセスキーを使った認証方法を取っています。そのためご利用にはアクセスキーが必要です。「駅すぱあとWebサービス」には機能が異なるいくつかのプランがあり、アクセスキーの取得方法もそれぞれ異なります。ここでは簡単にアクセスキーが取得でき、基本的な機能も揃っている「駅すぱあとWebサービス for Amazon」をご紹介します。

Amazon SaaSストア

ここからいずれかのバージョンを購入するとAmazonからアクセスキー(「abcde12345」のような文字列)が送られてきます。手元にメモしておきましょう。

もしこの文字列が他の方に漏れてしまうと不正に流用されることも考えられます。特に開発中は細心の注意を払うようにしてください。(アクセス制限する方法もありますが今回は省略します。)

前置きはこのぐらいで

実際に利用してみよう!!

サンプルリクエスト

WebAPIは、インターネットを介して向こう側にあるサーバーにあるアプリケーションへアクセスし、機能を利用したり情報を取得したりするための仕組みです。 手元のコンピュータからのアクセスを「リクエスト」、返ってくる情報を「レスポンス」と呼びます。

f:id:kumatira:20190424151732p:plain

インターネットの向こう側に話しかける(リクエスト)と、応答が返ってくる(レスポンス)イメージですね!!

今回は、「〇〇駅からXX駅まで」といった経路探索の結果が取得でき、使い方も複雑でない平均待ち時間探索という機能をサンプルとします。この機能についての仕様が書いてあるリファレンスページはこちらです。

docs.ekispert.com

ページを開きながら読み進めてください。そして肝心のサンプルとなるリクエストはこちら

https://api.ekispert.jp/v1/json/search/course/plain?from=高円寺&to=大阪&key={アクセスキー}

WebAPIのリクエストは通常こういったURLの形を取ります。ブラウザを通じてWebサイトを見るときのURLと同様です。{アクセスキー} と書かれた部分は先ほど準備したアクセスキーで置き換えてください。key=abcde12345 のような感じですね。

早速このリクエストURLをブラウザのアドレスバーに入れてリクエストしてみましょう。結果が返ってくるでしょうか？

f:id:kumatira:20190424152738p:plain

画像のようになんだか縦に長いレスポンスが返ってきたら成功です。「駅すぱあとWebサービス」の世界へようこそ🎉

それ以外のエラーが返ってきた場合はサンプルのコピペに失敗していないか、アクセスキーの置き換えをミスしていないかなどを確かめましょう。

サンプルリクエストの解説

サンプルとしたリクエストURLを詳しくみてみます。URLはいくつかの部分に分けることができます。それぞれにどういった意味があるのか解説します。

f:id:kumatira:20190424154118p:plain

URIスキーム

URIスキームはこのURLが利用する通信方法を示しています。Webサイトのアドレスの先頭でよく見かける「HTTP」や「HTTPS」が有名ですね。他に「FTP」なんかもURIスキームのうちの一つです。「駅すぱあとWebサービス」では「HTTP」と「HTTPS」の2種類に対応していますが、ここではよりセキュアな通信方法である「HTTPS」を使っています。

ホスト名

ホスト名はこのリクエストがどこへ向けて送られたのかを示しています。「駅すぱあとWebサービス」はapi.ekispert.jpのアドレス(住所)でさし示すことのできるサーバーで動いているので、ホスト名にapi.ekispert.jpを入れます。「駅すぱあとWebサービス」のこのホスト名はAPI概要のページにも記載されています。

ここが間違っていると「駅すぱあとWebサービス」までリクエストが届きません!!

パス

続いてはパスです。コンピューターの中でファイルの場所を示す「/user/hoge/fuga/sample.txt」のような文字列をパスと呼びますがそれと同様の考え方です。「駅すぱあとWebサービス」では、パスの指定によって使う機能を選ぶことができます。今回サンプルにしている平均待ち時間探索の機能はパスに/v1/json/search/course/plainを指定することで利用できます。

機能ごとにパスは異なりますが、それはどこで知ることができるのでしょうか。ここでリファレンスページを開きます!!

f:id:kumatira:20190424155909p:plain

「駅すぱあとWebサービス」のリファレンスページでは、機能ごとのページの先頭に、その機能を呼び出すためのパスを記載しています(「GET」については今回は無視してください)。例えば範囲探索なら/v1/{format}/search/multipleRange、緯度経度からの周辺駅検索なら/v1/{format}/geo/stationという感じです。このパスは「駅すぱあとWebサービス」以外のWebAPIでもリファレンスに必ず記載されています。迷ったら確認してみましょう!!

さてサンプルリクエストで指定しているパスとリファレンスに記載のパスが微妙に違っているのには気づきましたか?

サンプルリクエスト → /v1/json/search/course/plain
リファレンスの記載 → /v1/{format}/search/course/plain

実は「駅すぱあとWebサービス」では「JSON」と「XML」という2つのフォーマットでレスポンスを取得することができます。今回はJavaScriptを使ったプログラミングで用いられやすい「JSON(JavaScript Object Notation)」を選択しています。名前に「JavaScript」と入っていますが、それ以外のPythonやRuby、Javaなど多くの言語に、JSONをパースするためのライブラリが備わっています。

この2つのうちどちらのフォーマットで取得したいかによってパスの「{format}」に入れる文字列を変えてリクエストします。

JSONでレスポンスが返る平均待ち時間探索 → /v1/json/search/course/plain
XMLでレスポンスが返る平均待ち時間探索 → /v1/xml/search/course/plain

クエリ文字列

最後はクエリ文字列です。先ほどのパスの指定によって「どの機能を利用するか」は指定することができました。クエリ文字列では「機能にどのような変数を渡すか」を表すことができます。クエリ文字列は先頭が?で始まり、{クエリ名}={値}の形で表現されます。また複数のクエリを指定する場合はそれぞれを&で繋ぎます。

サンプルリクエストを受け取った「駅すぱあとWebサービス」の平均待ち時間探索機能は

?from=高円寺&to=大阪&key={アクセスキー}

というクエリ文字列を以下のように解釈しレスポンスを返しています。

クエリ名 値
from 高円寺
to 大阪
key {アクセスキー}

機能を利用する時どういったクエリを指定すればいいのか、それぞれのクエリはどういう意味を持つのかを知るにはどうすればいいでしょうか。そんな時はまたリファレンスページを見てみましょう!!

平均待ち時間探索 - 駅すぱあとWebサービス Documents 駅データ・路線検索のWebAPI

f:id:kumatira:20190424204554p:plain

利用しているパラメータの「parameters」の項目をみるとその答えが書いてあります。ここをみるとサンプルリクエストに含めたクエリはそれぞれfromは出発駅、toは到着駅、keyはアクセスキーとして解釈されることがわかります。

またそれ以外にいくつかのクエリが指定できることもわかります。例えばshinkansen=falseというクエリをつければ、新幹線を利用せずに経路を探索します。

さらに「Required」の列をみると、どのクエリが必須で、どのクエリがオプションであるかも確認できます。例えばサンプルリクエストに含めた3つのクエリは全て必須であることがわかります。試しにto外してリクエストしてみましょう。

https://api.ekispert.jp/v1/json/search/course/plain?from=高円寺&key={アクセスキー}
{
  ResultSet: {
    apiVersion: "1.27.0.0",
    engineVersion: "201905_01a",
    Error: {
      code: "W400",
      Message: "toは必須です。"
    }
  }
}

f:id:kumatira:20190424210028p:plain

するとtoが指定されていないとエラーが返ってきました。確かに到着駅がわからないと経路探索できませんね。

「駅すぱあとWebサービス」以外のWebAPIにおいてもリファレンスページを見ながらクエリを組み立てていきます。また必須のクエリ、そうでないクエリがあるのも同様です。

レスポンスの解説

リクエストの次はレスポンスを見ていきます。
サンプルリクエストでレスポンスのフォーマットとして指定したJSONは、JavaScriptの記法でデータが記述されています。配列やオブジェクト(辞書、ハッシュ)などを表現することができます。JSON自体は文字列ですので、実際にプログラムから利用する際は、各言語の対応ライブラリでパースして利用します。

まずはレスポンスの中からある経路の中で、乗り換えが何回発生するのかを取得してみましょう。

f:id:kumatira:20190424212905p:plain
駅すぱあとforweb(https://roote.ekispert.net/ja/)より

レスポンスについてもリファレンスページを参照します。レスポンスの各項目の意味は「response」の項目を確認します。が、平均待ち時間探索機能のリファレンスでは経路探索機能と同等と説明されています。ということで経路探索機能のレスポンスについての項目をみてみましょう。

docs.ekispert.com

経路探索機能は様々なデータが取得できる機能なのでレスポンスに関する説明が巨大ですがその中から「経路の乗り換え回数合計」を見つけます。

f:id:kumatira:20190424214025p:plain
経路の乗り換え回数合計の項目

左列を見るとこの項目はResultSet / Course / Route / transferCountで指し示される場所にあるようです。これはResultSet要素の中のCourse要素の中のRoute要素の... といった入れ子を表しています。これに従い、ブラウザで表示したレスポンスの中から辿ってみましょう。ブラウザに先述のアドインを入れている場合は「-」マークや「+」マークで配列やオブジェクトを畳んだり開いたりしながらデータを確認できます。

f:id:kumatira:20190424214715p:plain

まずはResultSet/Courseの中身から。配列を畳むとCourseの値の配列に5つの要素があることがわかります。リファレンスをみるとResultSet / Courseは「経路探索の結果である経路を表す要素」であることがわかります。経路探索の結果として5つの経路が返ってきているということですね!!

そのうちの一つを開くとこのようになります。

f:id:kumatira:20190424232014p:plain

そして先ほどのResultSet / Course / Route / transferCountにしたがって、Routeを開き、transferCountを参照します。すると「2」という数字が返っていることがわかります。このRoute要素が表している経路の「乗り換え回数合計」です!!

f:id:kumatira:20190424215330p:plain

例題1

リファレンスページの読み方、レスポンスの構造がわかってきたら、いくつか欲しい要素を目視で探してみましょう。
まずは「2経路目の『経路の乗車時間合計』」。リファレンスをみると「経路の乗車時間合計」はResultSet / Course / Route / timeOnBoardにあることがわかります。

配列やオブジェクトを畳んだり開いたりしながら探してみます。2経路目であることからCourse直下の2つ目の要素を参照するのがポイントです。

f:id:kumatira:20190424220951p:plain

例題2

『3経路目の1つ目の乗り換え駅の「駅の名称」』はどうでしょうか。ここでも何番目の要素を参照していくのかがポイントです。

f:id:kumatira:20190424221505p:plain

まとめ

ここまでリクエストURLについて、そしてレスポンスの構造について解説しました。これらは他のどの機能においても概ね共通しています。ドキュメントサイトで他の機能のリファレンスページやTipsのページを眺めながら色々遊んでみてください。

レスポンス構造のイメージが掴めたらアプリケーションを組み、実際にプログラムから値を取得してみましょう!!

最後に「駅すぱあとWebサービス」のなかでハマりポイントとなっているポイントをいくつか紹介します。

平均待ち時間探索機能で「Message: 駅名が見つかりません。」が返る

  • fromやtoに入れることができるのは「駅すぱあと」で定義されている駅名のみで、一般的な駅名と異なる場合があります(例: 中野→中野(東京都))。
  • これを防ぐためにまず駅簡易情報機能(/v1/{format}/station/light)などで駅を検索し、確定させます。確定させた情報から駅名ではなく駅コードを取得し、fromやtoに入れることを推奨しています。

配列を参照しようとすると参照エラーとなる時がある。

  • 「駅すぱあとWebサービス」ではJSONフォーマットのレスポンスにおいて、該当の要素が1つしかない場合とそうでない場合とを比べてレスポンス構造が異なっています。
  • この仕様を詳しく解説する記事を書いていますのでご覧ください→ここが辛いよ:cry: 駅すぱあとWebサービス レスポンス構造編

「Message: 利用できない機能を呼び出しています。」が返る

  • アクセスキーのプランによって使える機能が異なります。ドキュメントサイトなどを参考にしてください。
  • 例えば今回ご紹介した「駅すぱあとWebサービス for Amazon」の機能はAmazone SaaSストアの商品ページで利用できる機能が確認できます

リファレンスが見辛い...

  • 特に「response」の項目が巨大になっているページがあります。ブラウザのページ内検索機能を利用しながら参照してみてください。Google Chromeの場合、Windowsなら「Ctrl + F」Macなら「⌘(command) + F」で利用できます。
  • それでもやはり見辛いという場合はページの最下部についているフィードバックフォームからご意見をお寄せください。「駅すぱあとWebサービス」開発チームではドキュメントサイトを日々改善し、デベロッパーのみなさんが使いやすいドキュメントサイトを目指しています!!

Qiitaの「駅すぱあと」タグには「駅すぱあとWebサービス」を使ったアプリケーションを作ってみたという記事がたくさんあります!!こういった記事も参考にしながら楽しく実装してください!

ではでは👋

参考

gihyo.jp