利用ガイド

2016.06.16 初版作成

本APIにて提供するデータ形式について説明します。

JSON API

概要

広く普及したデータ交換形式であるJSON形式でデータを提供するAPIです。
属性や位置による検索に対応しており、アプリケーションに組み込んで利用することで、たとえば検索したデータを一覧表示したり、地図上でデータを可視化することができます。

基本的なリクエストは、次のような形式になります。

http://{オープンデータサーバ}/opendataapi/servicepoint/{サービスポイント名}?auth_key={あなたの認証キー}

サービスポイント名は取得したいデータの種類を表す文字列であり、公開リソース一覧から選択します。認証キーについては次節で説明します。

たとえば、次の例は、災害情報を取得する場合です。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}

これで次のような災害情報の一覧が取得できます。

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": 40,
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          138.375839233,
          35.00938797
        ]
      },
      "properties": {
        "disaster_name": "平成26年台風18号",
        "open_flag": "0",
        "spot": "静岡市葵区松富２丁目７−３５",
        "spot_public": "静岡市葵区松富２丁目７−３５",
        "road_name": "松富上１号線",
        "reasons": [
          {
            "type": "災害",
            "reason": "災害等",
            "reason_detail": "倒木"
          },
          ...
        ],
        ...
      },
      "TotalRecord": 256,
      "TotalPage": 9,
      "PageRecord": 30
    },
    ...
  ]
}

パラメータやレスポンス中の各プロパティについての詳細については、APIリファレンスを参照して下さい。

認証と制限について

JSON APIは、一定時間当たりの利用回数に制限があります。
これは、アクセスの急激な増加によるサーバーダウンを防ぐための措置です。
制限を超えてAPIが呼び出された場合、サーバーはHTTPステータス429 (Too Many Requests)のステータスを返却します。
その際は、一定時間待ってから再度アクセスを行うようにしてください。

本運用時には、認証された利用者について、上記の利用回数の制限を緩和する予定です。

座標情報による検索

座標情報による検索を利用することで、地理的に特定の範囲に存在するデータだけを抽出して取得することができます。本APIでは矩形（四角形）による検索と、円形による検索の2通りをサポートしています。緯度、経度の測地系は世界測地系で指定します。

矩形による検索を行いたい場合、パラメータextentで対角座標（南西端と北東端）の緯度・経度を指定します。下の例では、北緯35度と北緯35.05度の緯線および東経138.4度と東経138.48度の経線に囲まれた範囲のデータを検索します。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&extent=35,138.4,35.05,138.48

円による検索を行いたい場合、パラメータradiusで半径を、latおよびlngで中心を指定します。下の例では、北緯34.98、東経138.385の地点から半径1キロメートル以内の災害を検索します。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&radius=1000&lat=34.98&lng=138.385

属性情報による検索

属性検索を利用することで、特定の属性情報をもつデータだけを抽出して取得することができます。本APIでサポートしている検索方法は完全一致、部分一致、より大きい、より小さい、不一致の5通りがあります。たとえば、下の例では完全一致検索で原因が「台風」である災害情報を検索します。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&reason=台風

これは、実際にはURLエンコードされて下記のように送信される必要があります。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&reason=%E5%8F%B0%E9%A2%A8

次に、発生日が「2015年8月10日10時」より後である災害情報のデータを取得する例を示します。
日付フォーマットはyyyy-MM-dd HH:mm:ss形式で送信します。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&occur_date=>2015-08-10 10:00:00

これも同様にURLエンコードにより

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&occur_date=%3E2015-08-10%2010%3A00%3A00

として送信します。

なお、ある属性フィールドに対して検索方法が適用できるかどうかは、その属性フィールドの型に依存します。検索方法の各型への適用可否はAPIリファレンスの属性検索パラメータの項目を参照下さい。
また、同時に利用できる属性検索は座標情報による検索を含め、10件までとなります。

属性情報による並び替え

並び替えを利用することで、特定の属性情報をもとに並び替えを行います。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&order=occur_date+desc

これは、日付が最新の順(降順)でソートを行います。

ページング

1回のリクエストで取得できるデータ件数の上限は100件です。
100件より多くの検索結果がヒットしても、100件までしか返却しない為、すべての結果を取得するにはページングの仕組みを利用する必要があります。

ページングは、pageパラメータとrowパラメータを利用することで実現されます。
クエリパラメータに含めてリクエストを行うことで、指定したページのデータを取得します。
なお、pageパラメータが未指定時は1ページ目が、rowパラメータが未指定の時は30件まで取得されます。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}

⇒ 30件まで取得される。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&page=2&row=50

⇒ 51件目～100件目まで取得される。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&row=100

⇒ 100件まで取得される。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&page=2&row=200

⇒ 101件目～200件目まで取得される。（row=100と解釈される）

ページング機能を利用したAPIを実行した場合の返却形式は以下となります。

{
  "Success": true,
  "Data": {
    ...
  },
  "Error": null,
  "TotalRecord": 256,
  "TotalPage": 9,
  "PageRecord": 30
}

なお、データが0件の時の返却形式は以下となります。

{
  "Success": true,
  "Data": {
    "features": [],
    "type": "FeatureCollection"
  },
  "Error": null,
  "TotalRecord": 0,
  "TotalPage": 0,
  "PageRecord": 30
}

添付ファイルの取得

災害情報、道路規制情報などのリソースには一部のデータに添付ファイルに関する情報が含まれます。

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": 1,
      "type": "Feature",
      "geometry": { ... },
      "properties": {
        "regulation_type": "夜間通行止",
        "road_name": "井川湖御幸線",
        ...,
        "related_files": [
          {
            "open_flag": "0",
            "type": "2",
            "name": "20150128_142421.jpg",
            "location": "https://storage.cloud.google.com/.../....jpg?generation=1422422753542000&alt=media",
            "thumbnail_location": "https://storage.cloud.google.com/.../....jpg?generation=1422422752848000&alt=media",
            "update_date": "2015-01-28 14:31:27"
          }, ...
        ]
      }
    }, ...
  ]
}

locationに格納されているURLにアクセスすることで、添付ファイルをダウンロードすることができます。
thumbnail_locationに格納されているURLにアクセスすることで、添付ファイルのサムネイル画像をダウンロードすることができます。

その他のフィールドの意味についてはAPIリファレンスの該当項目を参照下さい。

JSONPによるリクエスト

一般に、ブラウザのJavaScriptから別のドメインのデータを読み込むことは、セキュリティ上の理由から制限されています。本APIでは、ブラウザのJavaScriptからデータを読み込んで使用するアプリの開発をサポートするため、JSONP（ウィキペディア）という方法をサポートすることにより、この制約を回避してデータを読み込む方法を提供しています。

本APIでJSONPを有効にするには、リクエストURLのクエリパラメータでjsonp=trueを指定します。また、レスポンスデータを受け取るJavaScript関数の名前をcallbackで指定します。

http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key={あなたの認証キー}&jsonp=true&callback=myCallbackFn

JSONPではXMLHttpRequestを使用してAjaxでデータを読み込むかわりに、<script>タグのJavaScriptとしてデータを読み込みます。

<script type="text/javascript" src="http://{オープンデータサーバ}/opendataapi/servicepoint/disaster?auth_key=*{あなたの認証キー}&jsonp=true&callback=myCallbackFn"></script>

データはクエリパラメータで名前を指定したJavaScript関数の引数として読み込まれます。

myCallbackFn({
  "type": "FeatureCollection",
  "features": [
    ...
  ]
});

したがって、リクエスト送信前に関数の定義を作成しておく必要があります。

<script type="text/javascript">

function myCallbackFn(data) {
  if (data && data.Success === true) {
    // dataを使って行いたい処理を記述
  } else {
    alert(data.Error);
  }
}

</script>

特定の大型イベントに関連する情報の取得

大型イベント基本情報から、関連する図形情報(点・線・面)と道路規制情報の取得方法を説明します。
初めに、大型イベント基本情報から、関連する情報を取得するためのキーとなる、イベント管理ID(id)を取得します。

http://{オープンデータサーバ}/opendataapi/servicepoint/bigEvents

次に、関連する図形情報(点・線・面)、道路規制情報を取得します。
関連するイベント図形情報や道路規制情報には、同じイベント管理ID(bigevent_id)が付与されているため、完全一致検索で情報を取得します。

http://{オープンデータサーバ}/opendataapi/servicepoint/bigEvents/feature/point?bigevent_id={基本情報のイベント管理ID}
http://{オープンデータサーバ}/opendataapi/servicepoint/bigEvents/feature/lineString?bigevent_id={基本情報のイベント管理ID}
http://{オープンデータサーバ}/opendataapi/servicepoint/bigEvents/feature/polygon?bigevent_id={基本情報のイベント管理ID} http://{オープンデータサーバ}/opendataapi/servicepoint/roadRegulation?bigevent_id={基本情報のイベント管理ID}

gaewiki:sidebar

メニュー

Tools