コンテンツにスキップ

入出力ルール

API の入出力に関する基本的なルールを説明します。

入力のルール

URLのサイズについて

NAVITIME API 2.0におけるリクエストURLのサイズは、7KBが上限となります。 また、上限は以下の内容を前提としています。

  • リクエストヘッダーを含む
  • URLをエンコードした状態でサイズを計算する

文字のエンコーディング

入力パラメータに日本語を使用する場合は、UTF-8 で URL エンコードした文字列を送信してください。

共通パラメータ

全ての API は以下のパラメータを受け付けています。

名称 概要 入力値 規定値 備考
datum 緯度経度の測地系 文字列 wgs84 ・wgs84
・tokyo
coord_unit 出力データに含まれる緯度経度の単位 文字列 degree ・degree
・millisec
callback JSONP 利用時のコールバック 文字列

例

  • 世界測地系かつミリ秒形式でスポット情報を取得
/spot?word=ピザ&datum=wgs84&coord_unit=millisec

　

地図表示を行うことを想定されている場合は、世界測地系 (wgs84) をご利用ください。

　

・いずれのパラメータも省略可能ですが、規定値は今後変更となる可能性がありますので、極力指定するようにして下さい
・測地系のズレを防ぐため、入力値の測地系と datum パラメータの指定は一致させる必要があります
・日本測地系で緯度経度を入力しつつ、出力だけ世界測地系にする、といったことは出来ませんので、予めご了承ください

緯度経度の形式

緯度経度指定の際、有効な入力パラメータは次の通りです。

  • ミリ秒表記
  • 度表記の10進法

緯度と経度をカンマで区切って指定して下さい (間にスペースは不要です) 。

例

  • 緯度=35.66416, 経度=139.718117 の住所を取得
/address/reverse_geocoding?coord=35.66416,139.718117

　

緯度と経度は同じ表記でなければなりません。緯度はミリ秒で経度は度表記、などは受け付けません。
・緯度 ... latitude
・経度 ... longitude

日付時刻の形式

RFC 3339 に準拠します。
タイムゾーンは IANA の Time Zone Database を参照してください。

ID・コード

駅／バス停 ID や住所コードといった ID・コード系のパラメータは有効数字にご注意下さい。

フィルタ

検索結果をコード指定でフィルタリング(指定コードの除外や絞り込み)をする時、以下のルールのフィルタリング条件を指定できます。

  • 出力を指定コードに限定: code
  • 出力から指定コードを除外: -code
  • 複数指定する場合は、上記の指定を ピリオド ( . ) 区切りで指定

例

  • 東京都 (13) の千代田区 (13101) 以外の住所を検索
/address?word=公園&address_filter=13.-13101

出力のルール

緯度経度情報

緯度経度情報は Coordinate オブジェクト として出力されます。このオブジェクトには緯度と経度の各値が入っています。 具体的には次のプロパティを持ちます。

名称 型 説明
lat 数値 緯度
lon 数値 経度

Coordinate オブジェクトの例

"coord": {
    "lat": 35.682372,
    "lon": 139.698866
}

　

出力される緯度経度の測地系・単位はそれぞれ datum, coord_unit パラメータの指定に依存します。

度表記の小数について

度表記の緯度経度は小数点第 6 位までの入力をサポートしています。 小数点第 7 位以降の入力値は内部的に丸め込みが行われ、ルート検索のような入力値がそのまま出力されるような場合に、下記のような誤差が生じる場合があります。 あらかじめご了承ください。

例
入力：135.15032091 → 出力：135.150321
入力：34.272600001 → 出力：34.2726
(切り捨て・切り上げは小数点第7位以降の数値に依存します。必ずしも四捨五入ではありません。)

単位情報

レスポンスに単位が必要となる値が含まれる場合、Unit オブジェクト が合わせて出力されます。
このオブジェクトにはレスポンスに含まれる値の単位のみが含まれるようになっています。
具体的には次のプロパティを持ちます。

名称 型 説明
datum String 緯度経度の測地系
coord_unit String 緯度経度の単位
distance String 距離の単位
time String 時間の単位
currency String 通貨の単位 
"unit": {
    "datum": "wgs84",
    "coord_unit": "degree",
    "distance": "metre",
    "time": "minute",
    "currency": "JPY"
}

　

datum と coord_unit は、それぞれ入力パラメータの datum と coord_unit で指定したものが出力されます。
それ以外のものは、入力パラメータによる指定は基本的には出来ません。詳細は各 API の仕様書をご確認ください。