How to Use｜Tellus

戻る

Traveler APIを利用し、シーンを検索して衛星データをダウンロードする(前編)

はじめに

本記事ではJupyterLabを使ってTraveler APIを利用し、シーンを検索して検索結果を元にシーン情報、ファイル情報を取得しダウンロードURLを生成する方法を前編、後編に分けて紹介します。今回はその前編です。

APIの詳細についてはこちらをご覧ください。

また、JupyterLabは事前に個別にセットアップしたものを使用しています。

APIトークンの発行

Traveler APIを使用するためにはAPIトークンが必要です。トークンの発行にはTellusへのログインが必要になります。

まずは、ご自身のアカウントでTellusにログインし、画面右上のアイコンからユーザー名をクリック > アカウント管理＞ APIトークン＞トークンの発行　をクリックしトークン名に任意の文字列を入力してください。

「発行」をクリックするとAPIトークンが生成されます。

1つ作成すれば複数のTraveler APIで利用することができます。

本記事においてサンプルコードを貼り付ける際はTOKEN("TOKENXXXXXXXXXXXXXXXXXX"と表示されている部分)に生成したAPIトークンを貼り付けてください。

requests モジュールのインストール

APIの呼び出しにrequestモジュールを使用します。インストールされていない方は以下のコマンドを実行しMacであればターミナル、Windowsであればコマンドプロンプトでインストールしてください。また、コマンドはJupyterLabの上で！を頭につけて実行することも可能です。

Anacondaを使用している方はバージョンによりますがデフォルトでrequestsがインストールされているケースが多いようです。

まずはpipがあることを確認します。

・ターミナルまたはコマンドプロンプト

pip -V

・JupyterLabで実行

!pip –V

pipがあることが確認出来たら以下のコマンドでrequestモジュールを環境にインストールしてください。

pip install requests

インストールできたかは以下のコマンドで確認できます。

pip list

Anacondaを利用している方はcondaコマンドでrequestモジュールのインストールができます。

conda install requests

pipはPython 3.4以降には標準で付属していますが、なければpipも適宜インストールしてください。

python get-pip.py

これで準備ができましたので、次からいよいよAPIの使い方を紹介します。

検索条件を指定してシーンを検索する

シーンを検索する方法にはデータセットを横断して検索する方法とデータセットを指定して検索する方法があります。

まずはデータセットを横断してシーンを検索する方法から紹介します。

データセットを横断してシーンを検索するにはAPIの/data-search/を使用します。

JupyterLabを起動し以下のサンプルコードを貼り付けます。

メソッド呼び出し時の引数に検索条件を入力することで条件を付けて検索ができます。

import requests
TOKEN = "TOKENXXXXXXXXXXXXXXXXXX"
def scene_search_crossing(datasets=None, intersects=None, query={}, sortby=None, paginate=None):
    url = 'https://www.tellusxdp.com/api/traveler/v1/data-search/'
    headers = {
        "Authorization": "Bearer " + TOKEN,
        'content-type': 'application/json'
    }
    payloads = {}
    if isinstance(datasets, list):
        payloads['datasets'] = datasets
    if intersects is not None:
        payloads['intersects'] = intersects
    if query is not None:
        payloads['query'] = query
    if isinstance(sortby, list):
        payloads['sortby'] = sortby
    if paginate is not None:
        payloads['paginate'] = paginate
    r = requests.post(url, headers=headers, data=json.dumps(payloads))
    return r.json()
print(scene_search_crossing(query={
    'sar:observation_direction':{'eq':'left'},
    'sat:orbit_state':{'eq':'descending'},
    'view:off_nadir':{'gte':15,'lte':46.2},
    'start_datetime': {'gte': '2022-01-12T00:00:00Z'}, 
    'end_datetime': {'lte': '2022-01-20T23:59:59Z'}
}, sortby=[{'field': 'properties.end_datetime', 'direction': 'desc'}], paginate={'size':10,'cursor':None}))

上記のコードでは観測方向(SAR)が「left」、軌道方向が「descending」、オフナディア角が「15以上46.2以下」、撮影日時に条件を設定し、ソートの条件と表示する件数の上限を指定しています。

JupyterLabの画面イメージは以下のようになります。

枠で囲っている部分はご自身のAPIトークンと調べたい検索条件に置き換えてください。

検索条件や表示方法については以下の横断/データセット指定検索パラメータ一覧またはAPIドキュメントのSchema情報等を参考にしてください。

横断/データセット指定検索パラメータ一覧はあくまでも現時点でのパラメータ一覧です。

今後データと共に増える可能性がありますので最新の情報についてはこの後紹介する/dataset-properties/を使用して参照ください。また、表の一部のクエリパラメータには衛星固有のパラメータもあります。

クエリパラメータは/dataset-properties/を使用すると一覧で表示することができます。

import requests
TOKEN = "TOKENXXXXXXXXXXXXXXXXXX"
def get_props():
    url = 'https://www.tellusxdp.com/api/traveler/v1/dataset-properties/'
    headers = {
        "Authorization": "Bearer " + TOKEN,
        'content-type': 'application/json'
    }
    r = requests.get(url, headers=headers)
    return r.json()
print(get_props())

JupyterLabの画面イメージは以下のようになります。

枠で囲っている部分はご自身のAPIトークンと調べたい検索条件に置き換えてください。

Travelerの画面上で検索可能なクエリパラメータを調べることができます。

データセット詳細ページのその他の欄に検索可能なクエリパラメータが掲載されていて、データセットごとに設定されているカタログ情報が異なります。

AOI（area of interest）を指定した検索方法も試してみてください。

検索条件を指定してシーンを検索する際に領域を条件に指定することもできます。

下の画像はTravelerの画面上でのAOI検索イメージ例です。

APIを使用して検索する際はAOIの値は反時計回りに指定し1つ目と5つ目は同じ値を書いてください。

import requests
TOKEN = "TOKENXXXXXXXXXXXXXXXXXX"
def scene_search_crossing(datasets=None, intersects=None, query={}, sortby=None, paginate=None):
    url = 'https://www.tellusxdp.com/api/traveler/v1/data-search/'
    headers = {
        "Authorization": "Bearer " + TOKEN,
        'content-type': 'application/json'
    }
    payloads = {}
    if isinstance(datasets, list):
        payloads['datasets'] = datasets
    if intersects is not None:
        payloads['intersects'] = intersects
    if query is not None:
        payloads['query'] = query
    if isinstance(sortby, list):
        payloads['sortby'] = sortby
    if paginate is not None:
        payloads['paginate'] = paginate
    r = requests.post(url, headers=headers, data=json.dumps(payloads))
    return r.json()
print(scene_search_crossing(
    intersects={
        'type':'Polygon','coordinates':[
            [
                [-162.33,11.55],
                [-149.32,11.55],
                [-149.32,24.07],
                [-162.33,24.07],
                [-162.33,11.55]
            ]
        ]
    },
    query={
        'start_datetime': {'gte': "2018-01-12T00:00:00Z"}
    },
    sortby=[
        {'field': 'properties.end_datetime', 'direction': 'desc'}
    ],
    paginate={'size':10,'cursor':None}
))

JupyterLabの画面イメージは以下のようになります。

枠で囲っている部分はご自身のAPIトークンと調べたい検索条件に置き換えてください。

次にデータセットを指定して検索する方法を紹介します。

データセットを指定して検索するにはAPIの/datasets/{dataset_id}/data-search/を使用します。

以下のサンプルコードをJupyterLabに貼り付けます。

メソッド呼び出し時の引数に検索条件を入力することで条件を付けて検索ができます。

import requests
TOKEN = "TOKENXXXXXXXXXXXXXXXXXX"
def scene_search(dataset_id, intersects=None, query={}, sortby=None, paginate=None):
    url = 'https://www.tellusxdp.com/api/traveler/v1/datasets/{}/data-search/'.format(dataset_id)
    headers = {
        "Authorization": "Bearer " + TOKEN,
        'Content-Type': 'application/json'
    }
    payloads = {}
    if intersects is not None:
        payloads['intersects'] = intersects
    if query is not None:
        payloads['query'] = query
    if isinstance(sortby, list):
        payloads['sortby'] = sortby
    if paginate is not None:
        payloads['paginate'] = paginate
    r = requests.post(url, headers=headers, data=json.dumps(payloads))
    return r.json()
print(scene_search('ea71ef6e-9569-49fc-be16-ba98d876fb73',query={
    'start_datetime': {'gte': "2011-04-21"}, 
    'end_datetime': {'lte': "2011-04-28"}
}, paginate={'size':10,'cursor':None}))

上記のコードでは撮影日時に条件を設定し、表示する件数の上限を指定しています。

JupyterLabの画面イメージは以下のようになります。

枠で囲っている部分はご自身のAPIトークンと調べたい検索条件に置き換えてください。

検索条件や表示方法については上記横断/データセット指定検索パラメータ一覧またはAPIドキュメントのSchema情報を参考にしてください。

横断検索とデータセット指定検索における検索条件の違いはデータセットを一つに指定するかどうかです。

データセット指定検索ではデータセットを既にURLで指定しているためリクエストボディに含んでいません。

実行結果の青枠部分はこの後のAPI紹介にて使用するdataset_idとdata_idです。

検索結果を元にシーン情報を取得する

個別シーンの情報を取得するためにAPIの/datasets/{dataset_id}/data/{data_id}/を使用します。

JupyterLabを起動し以下のサンプルコードを貼り付けます。

先ほど検索した結果からdataset_idとdata_idをサンプルコードの引数に設定してください。

import requests
TOKEN = "TOKENXXXXXXXXXXXXXXXXXX"
def get_scene_info(dataset_id , data_id):
    url = 'https://www.tellusxdp.com/api/traveler/v1/datasets/{}/data/{}/'.format(dataset_id , data_id)
    headers = {
        "Authorization": "Bearer " + TOKEN,
        'content-type': 'application/json'
    }
    r = requests.get(url, headers=headers)
    return r.json()
print(get_scene_info('ea71ef6e-9569-49fc-be16-ba98d876fb73','e432ad2b-d49c-4b50-892a-3487bebb0148'))

JupyterLabの画面イメージは以下のようになります。

枠で囲っている部分はご自身のAPIトークンと調べたいシーン情報に置き換えてください。

先ほどの/data-search/や/datasets/{dataset_id}/data-search/で検索した結果のIDまたは画面上に表示されるIDのどちらでも撮像タイミングや撮像範囲、他メタ情報を取得できます。

画面上でのdataset_id (データセットID)記載箇所はTravelerの取得したいシーンのデータセット詳細ページのIDです。

画面上でのdata_id(シーンID)記載箇所は取得シーン詳細ページのIDです。

ここまででAPIトークンの発行、requests モジュールのインストール、検索条件を指定してシーンを検索する、検索結果を元にシーン情報を取得する方法を紹介してきました。

後編ではシーンのファイル情報を取得、ダウンロードURLの生成、APIドキュメント上での確認方法を紹介します。

一覧に戻る