ヴァル研究所アドベントカレンダー2018の14日目です。
弊社アドベントカレンダーでは今年も「駅すぱあとWebサービス」についていくつかの記事でご紹介してきました。「駅すぱあとWebサービス」は経路探索サービス「駅すぱあと」の持つ機能や情報をWebAPIで利用できるサービスです。
便利な機能が沢山あって最高です!と言いたいところですが、いくつかの辛いポイントもあります。
今回はハマりポイントのうち、駅すぱあとWebサービスで見かける難解な用語を解説することで、みなさんがハマらずに「駅すぱあとWebサービス」を使ってもらえればと思います!!
普通に「駅すぱあとWebサービス」を知りたい方はこちら
- アクセスキー要らず!!API Testerで 駅すぱあとWebサービスに簡単入門する
- 「駅すぱあとWebサービス」個人的推し機能3選(範囲探索・住所情報からの周辺駅検索・バス路線時刻表)
- 駅すぱあとWebサービスの範囲探索APIと駅すぱあと路線図を組み合わせてアプリを作ってみる
目次
- 用語が難しい
- 「駅」って?
- 「路線」って?
- 「測地系」って?
用語が難しい
駅すぱあとWebサービスが扱っている日本の公共交通機関は巨大で複雑なシステムです。そのため、それらをコンピューターの世界に表現する駅すぱあとWebサービスには、一見わかりづらい独自の用語・概念が多く含まれています。
ドキュメントサイトのDictionaryページでは、そういった用語や概念についての説明があります。今回はその中から、駅すぱあとWebサービスが初めての方にとって特にわかりづらい3つの用語を紹介します。
「駅」って?
駅すぱあとWebサービスを使っていると「駅情報」や「駅コード」というような「駅」という単語がよく出てきます。一般的に駅というと鉄道駅を指す言葉だと思いますが、駅すぱあとにおける「駅」には以下が含まれています。
- 鉄道駅
- 空港
- 港
- 路線バス停留所／ターミナル
- コミュニティバス停留所
- 高速バス停留所／ターミナル
- 連絡バス停留所／ターミナル
- 深夜急行バス停留所
公共交通機関が止まる場所は全部という感じですね
駅情報機能では、typeパラメータ交通種別を入れることで、返却される
駅の種別(鉄道や路線バスなど)を絞ることができます。
リクエスト例
https://api.ekispert.jp/v1/json/station?name=富山&type=bus.highway&key={your_accessskey}
リクエスト例
{
ResultSet: {
(略)
Point: [
{
Station: {
code: "305121",
Name: "富山駅前(高速・連絡バス)",
Type: {
text: "bus",
detail: "highway:connection"
},
Yomi: "とやまえきまえ"
},
Prefecture: {
code: "16",
Name: "富山県"
},
GeoPoint: {
longi: "137.12.59.51",
lati: "36.41.49.97",
longi_d: "137.216533",
lati_d: "36.697216",
gcs: "tokyo"
}
},
{
Station: {
Name: "富山県水墨美術館前(高速・連絡バス)",
(略)
},
(略)
},
{
Station: {
Name: "富山市民病院前(高速・連絡バス)",
(略)
},
(略)
},
{
Station: {
Name: "富山市役所前(高速・連絡バス)",
(略)
},
(略)
},
{
Station: {
Name: "富山大学前(高速・連絡バス)",
(略)
},
(以下略)
このリクエスト例だと高速バスが利用できる「駅」のみが返って来ます。もちろん鉄道駅だけではなく、鉄道駅以外にあるバス停も入っています(駅すぱあとの「駅」にはバス停も入るため)。
「路線」って?
「駅すぱあとWebサービス」最大の鬼門が「路線」です。「駅すぱあと」には以下の3種類の「路線」があります。それぞれ表している区間や適した使い方が異なります。
- 運行路線
- 平均路線
- 運行情報路線
それぞれについて例をあげながら説明します。
平均路線
列車の停車パターンをベースに定義された路線です。列車の停車パターンを元に作られています。なので「中央特快」みたいな種別名がついていることが多いです。またバスでは系統がそのまま平均路線になっていることが多いです。コードはなく、名称だけがあることに注意してください。
平均路線には以下のような路線があります。
- ＪＲ中央本線(立川－甲府)
- ＪＲ中央本線(甲府－松本)
- ＪＲ中央本線(岡谷－塩尻)
- ＪＲ中央本線(名古屋－中津川)
- ＪＲ中央本線(中津川－松本)
- ＪＲ中央線快速
- ＪＲ中央線青梅特快
- ＪＲ中央線中央特快
運行路線
鉄道事業者の運行系統をベースにした路線で、鉄道事業者が乗客向けに案内するときの取り扱いに近い区間分け・名称となっています。なので日常会話で「〇〇線に乗って〜」と使うときのイメージに近いですね。
各運行路線に、名称とコードの両方が存在するので、より扱いやすくなっています。
運行路線には以下のような路線があります。
- ＪＲ中央本線(東京－塩尻)
- ＪＲ中央本線(岡谷－辰野－塩尻)
- ＪＲ中央本線(名古屋－塩尻)
- ＪＲ中央線快速
- ＪＲ中央・総武線各駅停車
運行情報路線
こちらは運行情報機能を使う時に用いる路線名です。
見た目は平均路線と似ていますが、互換性はありません。(←ここ大事。中の人の筆者も間違えたことがあります
)
以下のような路線があります。
- ＪＲ中央線快速
- ＪＲ中央本線(立川－甲府)
- ＪＲ中央本線(甲府－松本)
- ＪＲ中央本線(岡谷－塩尻)
- ＪＲ総武線
- ＪＲ中央本線(中津川－松本)
- ＪＲ中央本線(名古屋－中津川)
3つの路線区分には互換がありません。
そのため路線名称やコードを使って2つ以上の機能を連携する場合、前工程の機能がレスポンスで返す路線、後工程の機能がリクエストとして読める路線をそれぞれドキュメントとにらめっこして選ぶ必要があります
平均路線はかなり初期の駅すぱあとからある概念です。また運行情報路線は、駅すぱあとWebサービスに運行情報機能が搭載されたタイミングで整備されました。翻って運行路線は公開されてからまだ日が浅く、新しい機能では比較的リクエストやレスポンスに採り入れられている概念です。
ドキュメントを見ながら使い分けましょう!!
「測地系」って?
駅すぱあとWebサービスでは座標情報を扱うことがあります。緯度経度で示されるものですね。
例えば緯度経度からの周辺駅検索では、geoPointに座標情報を指定することでその周りの駅を探すことができます。また駅情報機能や経路探索のaddStop=true指定時などは、レスポンス中の駅の情報に座標情報が含まれます。
測地基準系について
座標情報にはその緯度経度が何を基準にして求められているか、によって「種類」があります。この「何を基準にして」の部分は測地基準系(「測地系」とも)と呼ばれており、いくつかの測地系があります。駅すぱあとWebサービスが扱える測地系は「日本測地系」と「世界測地系」の二つです。
よってある2つの座標情報が同じ緯度経度を持っていても、それぞれの測地系が異なれば、それぞれ違う場所を表しているということが起きます。また逆も然りで、ある地点を示す時に測地系が違えば異なった緯度経度が得られるということです。
なんだかややこしいですが、とりあえず二つの異なる基準があって、同じ緯度経度でも違う場所をさす事がある事を覚えていただければOKです😫
駅すぱあとWebサービスでは
先述の通り駅すぱあとWebサービスは「日本測地系」「世界測地系」両方に対応しています。例えば緯度経度からの周辺駅検索などでリクエストパラメータとして座標情報を指定する時、
日本測地系の緯度経度なら35.6783055555556,139.770441666667,tokyo
世界測地系の緯度経度なら35.6783055555556,139.770441666667,wgs84
とすれば良いだけです。簡単ですね!!
逆に駅情報機能などで返される座標情報を希望の測地系で返して欲しい時、
日本測地系の緯度経度なら gcs=tokyo
世界測地系の緯度経度なら gcs=wgs84
と指定すればOKです!!
なお指定しなければリクエスト・レスポンス共にデフォルトの日本測地系として解釈されます。
よくあるミス
それぞれの測地系で同じ緯度経度の座標を地図に落としてみると、日本国内では数10mほどずれている事わかります。よって他のサービスと連携する時に、本来は日本測地系の座標情報なのに世界測地系として扱ったり、その逆を行ったりするとに不具合が起きるのです。
GoogleMapsの「この地点について」機能は世界測地系の緯度経度を返しますので、デフォでは日本測地系として解釈する駅すぱあとWebサービスに持ってきた時、「あれっ?」となる事故がよくあります。
きちんとパラメータを指定したり測地系変換を使ったりして、うまく実装してください!!
まとめ
という事で駅すぱあとWebサービスを利用する際に「ハマって」しまいやすい用語について解説しました。
日本の公共交通機関は巨大で複雑なシステムで、なるべく平易に扱うべくできたのがまさに「駅すぱあとWebサービス」ですが、なかなか難しい概念もある事がわかっていただけたと思います。