How to Use｜Tellus

戻る

TellusのAPIを学ぶ

Tag

TellusのAPIを学ぶ

APIとは

APIとはApplication Programming Interfaceの略称です。APIとは何をするものでしょうか。

例えば、あなたがTwitterを始めとしたSNSのデータベース上にある画像を検索できるようなアプリを製作したとしましょう。ユーザが「タイタン」で検索をかけたとすると、その検索がSNSのデータベースにアクセスし、「タイタン」と発言されたツイートを取得します。投稿した発言内に画像があれば、取得します。このとき、アプリ内部では、SNSが提供しているWeb APIを利用しています。

このように、Twitter Web APIを利用することで、アプリケーションは、データベースから画像を取得することが可能になります。加えて、ユーザは、APIの裏側でどのようなことが行われているのかを詳細に知る必要はありません。

APIの使い方をラーメンの注文で例えてみましょう。ラーメンの種類を選択したら（味噌、塩、醤油）、麺の量を決定します。続けてトッピングも選択しましょう。野菜、ニンニク、そして背脂の量も決めます。最後に味の濃さを決めます。全てを合わせると、「醤油大ヤサイマシマシニンニクスクナメアブラカラメ」のように注文をすることができます。店側は注文を受けて（リクエスト）、指定された通りのラーメンを返します（レスポンス）。このとき注文をした人は、厨房でラーメンがどのように作られるのかを気にする必要はありません。店員（API）に対して正しい注文が通っていれば、注文通りのラーメンを得ることができるからです。

APIは利用者に対して単にデータを与えるだけではありません。例えば、利用者が保有しているデータを、API経由で提供することでデータを加工した結果を入手することもできます。そのため、材料を持ち込み、欲しいものを作ってもらえる風変わりなレストランと考えることもできます。

まとめると、APIとは利用者にとって欲しい結果を簡単に取得できるようにするための仲介役と言えます。

＊さらに詳しくAPIについて知りたいという方は、参考文献リストをご参照ください。

それでは、実際にTellusのAPIを実行してみましょう。

ASNARO-1を例に紹介します。ASNARO-1には4つのGETメソッドがあります。具体的な例として、/asnaro1/sceneを利用してみましょう（＊仮に欲しいシーンidが既に分かっている場合には、/asnaro1/get_scene/{id}を使う方が簡単です）。このメソッドでは最小緯度、最小経度、最大緯度、最大経度を指定することで、範囲内のASNARO-1のシーンを取得することができます。

各々のパラメーターの詳細な説明については、Tellus公式商品の商品詳細をご覧ください。

早速APIを使用してリクエストしてみましょう。サーバーのurlを参考にすると、以下のように考えることができます。

https://gisapi.tellusxdp.com/api/v1/asnaro1/scene?min_lat=20.425278&min_lon=122.933611&max_lat=45.557222&max_lon=153.986389

出来上がったものをブラウザに貼り付けて実行すると、”out of telluside. we only provide sevice under telluside.”というメッセージが映し出されたはずです。つまり、APIを実行する環境はtellus下でなければならないということがわかります。

加えて、APIを実行するためにはAPIアクセス設定をする必要があります。ユーザーマイページからAPIアクセス設定をし、トークンを作成しましょう。任意の文字列を空欄に入力することにより（下の例ではHogeに対してキーを作成）、トークンが取得できます。

開発環境であるJupyter Labを起動し、FileからNew、最後にNotebookを選択します。Notebookはwork/以下のディレクトリでないと作成できません。左のウィンドウ内にあるworkフォルダをクリックし、その中で作業を行ってください。

Pythonを使用しますので、Python3を選択して新しいNotebookの作成を完了します。これでAPIを実行する準備が整いました。

import json, requests
TOKEN = "ここにあなたのAPIアクセストークンを貼り付けてください"
# 任意の最小緯度・経度、最大緯度・経度を入力します
min_lat = 32.4440
min_lon = 129.5224
max_lat = 33.4440
max_lon = 130.5224
# URLはサーバーURL+parametersとなります

ASNARO-1のURLはhttps://gisapi.tellusxdp.com/api/v1/asnaro1/scene?min_lat=32.444&min_lon=129.5224&max_lat=33.444&max_lon=130.5224のように表されます。URLの中で指定した緯度と経度の範囲にあるシーンを取得することになります。これをPythonで表すと次のようになります。

url = "https://gisapi.tellusxdp.com/api/v1/asnaro1/scene" \
  + "?min_lat={}&min_lon={}&max_lat={}&max_lon={}".format(min_lat, min_lon, max_lat, max_lon)
# header情報として、トークンを設定します
headers = {
  "Authorization": "Bearer " + TOKEN
}

APIを実行するためにはトークンをヘッダ情報に示さなければなりません。ご自身のトークンを上のコードに貼り付け、実際にリクエストを送信してみましょう。

r = requests.get(url, headers=headers)

が返ってきたはずです。正常にレスポンスが得られたことを示しています。

取得された情報をjsonで表示しましょう。

print(r.json())

以上のような結果が得られました。条件に合う撮影シーンの情報が変数としてjson内に記述されていることが分かります。これらは取得された各々の衛星画像に対するメタデータであり、様々な情報が含まれています。例えば、thumbs_urlではサムネイル画像のURLが示されており、それを用いて画像を表示することが可能です。

scenes = r.json() #シーン情報を変数に格納
scenes[-1]['thumbs_url'] #scenesに含まれる最後のメタ情報からサムネイル画像URLを取得
from skimage import io
img_thumbs = io.imread(scenes[-1]['thumbs_url'])
io.imshow(img_thumbs)

Original data provided by NEC

メタデータは識別番号（entityId）も保持しています。entityIdがわかれば、別のAPIを利用してシーン画像に含まれる任意のxy座標とズーム率を指定することでタイル画像を取得することができます。さらにproductIdを用いれば、波長合成画像も取得することが可能です。メタ情報を読み取り、APIと組み合わせることで目的に合った衛星画像を入手してください。

今回使用したスクリプトです。

import json, requests
TOKEN = "ここにAPIアクセストークンを貼り付けてください"
# 任意の最小緯度・経度、最大緯度・経度を入力します
min_lat = 32.4440
min_lon = 129.5224
max_lat = 33.4440
max_lon = 130.5224
# URLはサーバーURL+parametersとなります
# 組み合わせたURLはhttps://gisapi.tellusxdp.com/api/v1/asnaro1/scene?min_lat=32.444&min_lon=129.5224&max_lat=33.444&max_lon=130.5224のようになります
url = "https://gisapi.tellusxdp.com/api/v1/asnaro1/scene" \
    	+ "?min_lat={}&min_lon={}&max_lat={}&max_lon={}".format(min_lat, min_lon, max_lat, max_lon)
# header情報として、トークンを設定します
headers = {
    	"Authorization": "Bearer " + TOKEN
	}
r = requests.get(url, headers=headers)
print(r.json())
scenes = r.json()
scenes[-1]['thumbs_url']
from skimage import io
img_thumbs = io.imread(scenes[-1]['thumbs_url'])
io.imshow(img_thumbs)

参考文献

How to Useトップに戻る