都市構造可視化 API V1の仕様について説明します。
APIとの全ての通信にはHTTPSプロトコルを利用します。アクセス先のホストは、mieruka.city
を利用します。
APIへのリクエストには、POSTの1種類のHTTPメソッドを利用します。多くのAPIへのリクエストにはパラメータを含められますが、GETリクエストにパラメータを含める場合にはURIクエリを利用し、それ以外の場合にはリクエストボディを利用します。パラメータには、ページネーション用途など任意で渡すものと、投稿時の本文など必須のものが存在します。APIドキュメントには、各APIごとに送信可能なパラメータが記載されています。
201、400、403、404、405、500の5種類のステータスコードを利用します。但し、エラーが起きた場合にはその他のステータスコードの中から適切なものを返します。
APIとのデータの送受信にはJSONを利用します。JSONをリクエストボディに含める場合、リクエストのContent-Typeヘッダにapplication/jsonを指定してください。但し、GETリクエストにバラメータを含める場合にはURIクエリを利用します。また、PUTリクエストまたはDELETEリクエストに対してはレスポンスボディが返却されません。日時を表現する場合には、 原則 YYYY-mm-dd もしくは YYYYmmddとするが、 RFC2822,RFC3399に準じる書式は全て許可しています
POST /v1/mieruka/kmls/search HTTP/1.1 Content-Type: application/json Host: mieruka.city { "access_token": "123456789abcd...", "city": "福岡県糸島市", "item": "人口分布" }
エラーが発生した場合、エラーを表現するオブジェクトを含んだエラーレスポンスが返却されます。このオブジェクトには、エラーの内容を説明するmessageプロパティと、エラーの種類を表すtypeプロパティで構成されます。typeプロパティはエラーの種類ごとに一意な文字列で、^[a-z0-9_]+$
というパターンで表現できます。
{ "message": "Not Found" }
都市構造可視化のAPIを利用するには、アクセストークンをリクエストに含める必要があります。アクセストークンは、ユーザマイページの "アクセストークンを発行する" から発行出来ます。
"123456789abcd..."
指定した市町村の、指定したテーマのKMLに関するURLを検索することが出来ます。
取得したURLにアクセスすることでKMLを表示することが可能となります。
"福岡県糸島市"
"人口分布"
POST /v1/mieruka/kmls/search HTTP/1.1 Content-Type: application/json Host: mieruka.city { "access_token": "123456789abcd...", "city": "福岡県糸島市", "item": "人口分布" }
HTTP/1.1 201 Content-Type: application/json { "filepath": "https://mieruka.city/v1/mieruka/kmls/view...", }