宙畑衛星データ講座！追補版 Tellus APIの使い方解説
2020年夏に開催した宙畑の衛星データ講座の中で、TellusのAPIについて触れたDAY6を記事化しました！
記事作成時から、Tellusからデータを検索・取得するAPIが変更になっております。該当箇所のコードについては、以下のリンクをご参照ください。
https://www.tellusxdp.com/ja/howtouse/access/traveler_api_20220310_
firstpart.html
2022年8月31日以降、Tellus OSでのデータの閲覧方法など使い方が一部変更になっております。新しいTellus OSの基本操作は以下のリンクをご参照ください。
https://www.tellusxdp.com/ja/howtouse/tellus_os/start_tellus_os.html
2020年7月15日～8月26日まで毎週水曜日に7回に分けて開催した「基礎から学ぶ衛星データ講座」の中で、TellusのAPIの使い方を説明したDAY6について、たくさんの記事化のご要望をいただきまして、テキスト化記事をお届けします。
Youtubeのアーカイブ動画と合わせてご利用ください。
TellusのAPIの全体像
TellusのAPIは大きく分けて4つあります。
①ユーザー定義API
まず、一つ目の「ユーザー定義」APIは、Tellus OSで書いた図形を開発環境に落としてきたり、逆に消したり、また図形を描いたりすることのできるAPIです。
APIリファレンスはこちら
https://www.tellusxdp.com/docs/api-reference/users-v1.html
以降の3つの種類は、データの種類によって分けられます。
②衛星データAPI
「衛星」のAPIはその中でも、「GPS」「光学」「レーダー（SAR）」に分けられます。今回は「光学」を中心に説明するので、ここでは「GPS」と「レーダー（SAR）」について説明します。
「GPS」のデータとしては、profile passportというデータがあります。
【Tellus公式】位置情報｜Profile Passport
https://www.tellusxdp.com/market/tool_detail/tellus-default/122
「レーダー（SAR）」のデータとしては現在、TellusにはPALSAR-2やASNARO-2というSAR画像が搭載されています。
【Tellus公式】PALSAR-2 | ALOS-2
https://www.tellusxdp.com/market/tool_detail/tellus-default/53
【Tellus公式】ASNARO-2
https://www.tellusxdp.com/market/tool_detail/tellus-default/57
③気象観測データAPI
「気象観測」のデータとしてはAMeDAS（アメダス）と呼ばれる、気象庁が地上のセンサを用いて気温や積雪、降雨量のデータを取得できるデータがあります。
【Tellus公式】アメダス1分値
https://www.tellusxdp.com/market/tool_detail/tellus-default/74
④分布統計データAPI
最後の「分布統計」はモバイル空間統計という人口分布の時間的変動を見ることができます。
【Tellus公式】人口統計情報｜モバイル空間統計
https://www.tellusxdp.com/market/tool_detail/tellus-default/125
次の章では、衛星データの特に「光学」について掘り下げていきます。
Tellusの衛星画像（光学）のAPIの種類
光学の衛星データを、今回の講義ではさらに4つに区分しています。
①気象データ
気象衛星であるひまわり8号の画像のデータを公開しています。
【Tellus公式】ひまわり8号
https://www.tellusxdp.com/market/tool_detail/tellus-default/71
②標高
光学の衛星データを複数組み合わせることで、立体視の原理で標高を求めることができます。Tellusでは2種類の標高データを公開していますが、APIとして切られているのはASTER GDEMというデータです。
【Tellus公式】ASTER GDEM 2
https://www.tellusxdp.com/market/tool_detail/tellus-default/60
【Tellus公式】ASTER GDEM 3
https://www.tellusxdp.com/market/tool_detail/tellus-default/61
③高解像度
Tellusでは地表面を1m以下の解像度で見ることができる衛星画像を複数搭載しています。1m以下の解像度では車などを捉えることができます。
【Tellus公式】SHIROP | SLATS
https://www.tellusxdp.com/market/tool_detail/tellus-default/50
【Tellus公式】ASNARO-1
https://www.tellusxdp.com/market/tool_detail/tellus-default/47
【Tellus公式】ALOS-3相当データ ※講義配信後の2020年9月4日に追加
https://www.tellusxdp.com/market/tool_detail/tellus-default/285
④複数の波長
衛星データは一般の画像としての使い方だけでなく、赤青緑の波長以外の波長でも観測しているので、そういった成分を取りだせるAPIも用意しています。
【Tellus公式】AVNIR-2 | ALOS
https://www.tellusxdp.com/market/tool_detail/tellus-default/44
【Tellus公式】Landsat-8
https://www.tellusxdp.com/market/tool_detail/tellus-default/52
また、高解像度の衛星のところでも紹介したASNARO-1やALOS-3相当データでも波長のデータを扱うことができます。
⑤オリジナルデータAPI ※講義後に追加
ここまでご紹介したAPIは、Tellus側でタイル化処理をしたデータを呼び出せるAPIです。
一方で、いくつかのデータでは元のデータをそのまま配信するAPIも公開しています。
【Tellus公式】AVNIR-2 | ALOS
https://www.tellusxdp.com/docs/api-reference/avnir2-files-v1.html
【Tellus公式】PALSAR-2 | ALOS-2
https://www.tellusxdp.com/docs/api-reference/palsar2-files-v1.html
TellusのAPIの使い方解説
この章からは、ここまでで紹介したデータのAPIを具体的に使うための手順を説明していきます。
データの詳細はTellusマーケットから探すことができます。
使いたい衛星名が分かっている場合はマーケットの検索窓に衛星名やセンサ名を入力しても良いですし、分からない場合は「光学」や「SAR」などキーワードで入れることもできます。
データを一つ選んでクリックすると、詳細ページからAPIリファレンスを見ることができます。
APIリファレンスを持っている全てのデータを確認したい場合には、上の図と同じ商品検索のページにある、「詳細検索」をクリックします。
詳細検索の画面では、キーワードは空、カテゴリを「データ」、接続形式を「API」としてください。その後、最下部にある、「この条件で検索する」を押すと、Tellusが提供している全てのAPIを調べることができます。
話を戻して、以下では、ASNARO-1を例にとって説明していきます。
ASNARO-1のAPIは全部で4つです。
上の2つは衛星画像の情報を引っ張ってくるもの。下の二つは実際の画像（png画像）を引っ張ってくるものです。
衛星画像を取ってくる場合、この2つのステップを踏んで衛星データの取り込みを行います。
①撮影画像（メタ情報）検索API
条件に合う画像はどれかを探すために使うAPIです。
画像の情報を閲覧することができます。
探し方としては、以下の2種類があります。
(1)緯度経度
自分が欲しいエリアの緯度と経度を使って、該当エリアにある画像の一覧を入手することができます。こちらを使うことが多いです。
(2)ID
衛星画像は画像毎に区別できるようにIDが付与されています。Tellus OSなどの方法で既に欲しい画像のIDが分かっている場合にはこちらを使います。
撮影画像検索の結果返ってくるものの中で、よく使うものは次の3点です。
・entityId
先ほど説明したIDを使ってカラーの衛星画像を持ってくることができます。
・productId
波長の組み合わせの結果など、単なるRGBのカラー合成だけではない画像を取り出すことができます。
・thumbs_url
衛星画像のサムネイルを確認できます。TellusではPNGタイル画像を提供していますが、そのタイル画像はここに示されたサムネイル画像の元ファイルから切り出されたものになります。
②タイル画像取得API
上記の繰り返しになりますが、撮影画像検索APIで得られたIDを使って、所望の画像を取り出します。
・SceneID：Entity idに紐づいている・普通に写真のようなものを獲りたい
・Product ID：波長を合成したものをとることができる
ここからは具体的にAPIの使い方を説明していきます。
まずは、撮影画像（メタ情報）検索APIを使って関心範囲の画像があるかどうかを確認します。
https://gisapi.tellusxdp.com/api/v1/asnaro1/scene?min_lat=31.5661481766963&min_lon=130.47162065429&max_lat=31.7205387930055&max_lon=130.788547580551pythonで使う場合、変数を使って以下のようにまとめると良いです。
import requests
url = "https://gisapi.tellusxdp.com/api/v1/asnaro1/scene"
querystring = {"min_lat": 31.5661481766963,"min_lon": 130.47162065429,
"max_lat": 31.7205387930055,"max_lon": 130.788547580551}
headers = {'Authorization': 'Bearer ' + TOKEN}
response = requests.request("GET", url, headers=headers, params=querystring)
print(response.text)さらに、JupyterLabで書く場合は、様々なデータに対応するために、以下のように関数を定義して書くと良いでしょう。
# ライブラリのインポートと描画のための宣言
import requests
import json
import math
import matplotlib.pyplot as plt
from skimage import io
from io import BytesIO
%matplotlib inline
# トークンとドメインの指定
# https://www.tellusxdp.com/ja/howtouse/dev/install_development_environment.html
TOKEN = 'tellusのAPIトークンを入れる'
DOMAIN = 'tellusxdp.com'
# ASNARO-1の撮影画像を取得するための関数を定義
# APIリファレンスに沿って、必要なパラメータを設定する
def search_ASNARO1_scenes(min_lon, min_lat, max_lon, max_lat):
url = 'https://gisapi.{}/api/v1/asnaro1/scene'.format(DOMAIN)
headers = {
'Authorization': 'Bearer ' + TOKEN
}
payload = {'min_lat': min_lat, 'min_lon': min_lon,
'max_lat': max_lat, 'max_lon': max_lon}
r = requests.get(url, params=payload, headers=headers)
if r.status_code is not 200:
raise ValueError('status error({}).'.format(r.status_code))
return r.json()
実際に、コードをを書いて、撮影画像（メタ情報）検索APIを実行した例が以下になります。
(min_lon,min_lat,max_lon,max_lat) = (130.47162065429,31.5661481766963,130.788547580551,31.7205387930055)
scenes = search_ASNARO1_scenes(min_lon,min_lat,max_lon,max_lat)
print('number of scenes : {}'.format(len(scenes)))
print(scenes[7])
thumb = io.imread(scenes[7]['thumbs_url'])
# io.imshow(thumb);
plt.axis('off')
plt.imshow(thumb);
返ってきた値を見てみると、
number of scenes:9
とあり、指定したエリア内に合う、9つの画像があるということが分かります。
また、先ほどご紹介したentityId、productId、thumbs_urlの情報も返ってきていることが確認できるかと思います。
続いて、タイル画像取得APIを見ていきます。
画像取得APIでは、さきほど調べたproductidを使ってタイル画像を取り出します。
衛星の画像は1枚が大きいため、productidだけでなく、その中をさらに細かく割ったタイル画像を使って指定していきます。
タイル座標はTellus OSの右上にあるグリットマークのボタンから表示できます。
zはズーム率、xとyが座標になります。
こちらもpythonで書くと以下の様になります。
import requests
url = "https://gisapi.tellusxdp.com/blend/asnaro1/20181223152430886_AS1_D01_L1B/13/7069/3337.png"
headers = {'Authorization': 'Bearer ' + TOKEN}
response = requests.request("GET", url, headers=headers)
print(io.imread(BytesIO(response.content)))こちらも実際に使う時には関数を定義して使うと良いでしょう。
def get_ASNARO1_blend_tile(scene_id, zoom, xtile, ytile,
opacity=1, r=4, g=3, b=2, rdepth=1, gdepth=1, bdepth=1, preset=None):
# zoom = 8 - 16
url = 'https://gisapi.{}/blend/asnaro1/{}/{}/{}/{}.png'.format(
DOMAIN, scene_id, zoom, xtile, ytile)
headers = {
'Authorization': 'Bearer ' + TOKEN
}
payload = {'preset': preset, 'opacity': opacity, 'r': r, 'g': g,
'b': b, 'rdepth': rdepth, 'gdepth': gdepth, 'bdepth': bdepth}
r = requests.get(url, params=payload, headers=headers)
if r.status_code is not 200:
raise ValueError('status error({}).'.format(r.status_code))
return io.imread(BytesIO(r.content))
img = get_ASNARO1_blend_tile(scenes[7]['productId'], zoom, xtile, ytile)
plt.axis('off')
plt.imshow(img);
実行すると、タイル（256ピクセル×256ピクセルの画像）が手に入ります。
他のデータのAPIの構成について
前章ではASNARO-1のAPIの使い方についてご紹介しました。それ以外のデータも基本的には同じような仕組みで使うことができます。
①撮影画像情報取得API（緯度経度）
撮影画像情報取得APIは、大きく分けて2種類あります。
多くはASNARO-1と同じで、緯度経度を指定する方式です。
Landsat-8には、現在公開しているものの中で唯一被雲率（画像の中で雲がかかっている割合：cloud coverage）を条件に含めることができます。
②撮影画像情報取得API（ID）
もう一つの撮影画像情報取得APIはIDで検索する方式です。こちらはどの衛星でも共通です。
③タイル画像取得API
タイル画像取得APIはASNARO-1と同形式です。
scene idとタイル座標を指定してタイル画像を取得します。
④波長合成タイル画像取得API
波長合成タイル画像取得APIの場合、大きくパラメーターは2種類あります。
Path parametersの中には衛星の撮影場所を特定するための固有のパラメーターとズームレベル、タイル座標が含まれ、Query parametersには呼ばれる波長の選択や透過率の選択をするパラメーターが含まれています。Path parameters内の衛星固有のパラメーターは各々異なりますが、Query parametersは共通です。
固有のIDががなぜ必要かというと、上図のように同じ場所（タイル座標）でも複数のシーンが存在しており、複数の画像の中でどの画像にするかを選択する必要があります。
以下で、衛星毎に詳しく見ていきます。
ASNARO-1では、productidとタイル座標で指定します。
AVNIR-2ではproductidとrspidとタイル座標を指定します。
ここでRSPとはReference System for Planningの略で、検索システムと思っておけばOKです。
Landsat-8では、軌道上の位置を意味するpathとrowというものを指定するようになっています。
⑤その他のタイル画像取得API
その他のAPIも基本的な構造は同様です。
標高データであるASTER GDEMではタイル座標で画像を取ってくるようになっています。
気象衛星ひまわりの画像はプロダクトIDの代わりに年月日を指定する作りになっています。
まとめ
以上、駆け足でTellus のAPIについて解説しました。
ぜひ開発環境を申込んで実際にAPIを触ってみて下さい。
「Tellus」で衛星データを触ってみよう！
日本発のオープン＆フリーなデータプラットフォーム「Tellus」で、まずは衛星データを見て、触ってみませんか？
★Tellusの利用登録はこちらから
