Tellus公式データAPIと数日間格闘して、Tellus公式データAPIを使って指定した住所の周辺の衛星画像を取得するまでこぎつけました。
あとに続く人のために、わかりづらかった点をまとめます。
ユーザー登録からAPIトークンの発行までは簡単でした。例えばTellus APIを利用した衛星データ活用 可視化偏などをご参照ください。
１．全体像
Tellus Travelerというブラウザから衛星データを検索して閲覧できるサービスで感触をつかんでから、その作業をプログラムから自動化するためにAPIを使うという順序を強くおすすめします。私は最初にこの全体像を聞きたかったです。
APIドキュメントは、「サポート」→「利用ガイド」にあります。
いろいろなページがあって道に迷いそうになりますが、頻繁に参照するのはこの２箇所です。
２．Tellus Traveler
デフォルトではすべてのデータセットが選択された状態になっていて、このまま検索すると膨大なデータがヒットしてわけがわからなくなります。いったんすべてクリアしてから、興味のあるデータセットを少数選ぶことをおすすめします。
データセットの違いや特徴を理解するのも難しいですが、これは物事の性質上どうしても難しいので仕方ないです。私はまだほとんど理解できていません。
AOI（関心領域）で検索対象とする地理的な場所を選択できます。それも絞ったほうがヒットする結果が少なくなって見やすいです。
検索結果はシーン単位で表示されます。一つのシーンが一つの衛星画像だと大まかに考えるとわかりやすいです。
３．APIの使い方
APIリファレンス（Tellus公式データAPI）が非常に見づらいので、以下のサンプルコードを見たほうがわかりやすいです。
- シーンを検索して衛星データをダウンロード（前編） （サンプルコード）
- シーンを検索して衛星データをダウンロード（後編） （サンプルコード）
- 光学データ「SLATS」をダウンロードして画像結合 （サンプルコード）
- SARデータ「PALSAR-2」をダウンロードして描画 （サンプルコード）
特に最初の２つが最重要資料だと私は考えます（最後の２つが重要でないと考える理由は後述します）。
（１） シーンを検索して衛星データをダウンロード（前編） （サンプルコード）
APIトークンの発行やPythonのモジュールのインストールについては丁寧に説明されているのですが、肝心のTellus公式データAPIについてはいきなりコードを示されて面食らいます。
シーンの検索→（シーン情報の取得）→ファイル情報の取得→ダウンロードURLの取得→データ（画像）ダウンロードという流れを最初に示してもらいたかったです。
そして、示されるコード例が、関数の定義と呼び出しがつながっていて、理解に苦しみました。
赤線の上が関数の定義、赤線の下が関数の呼び出しです。せめてここに改行がほしかったです。
また、ご覧のとおり、この図の関数呼び出しがわかりづらいです。引数で各種設定ができるように柔軟な関数になっている分だけ理解しづらいのです。
Tellus公式データAPIを使って指定した住所の周辺の衛星画像を取得するで私が書いたように、関数の定義部分でできるだけ固定したほうがわかりやすいと思います。
この前編では、シーンの検索→（シーン情報の取得）まで扱われているのですが、この→のつなぎ目がわかりにくいです。printした結果ないしTellus Travelerの操作画面から手動でコピーすることが想定されているようです。
そうではなく、Tellus公式データAPIを使って指定した住所の周辺の衛星画像を取得するで私が書いたように、プログラムで取得する方法が知りたかったです。言い換えると、この前編を通してのコードの全体像を示してほしかったということでもあります。「# API 呼び出しの共通設定」と書かれている部分は１回だけ書けばよいと気づくのにも時間がかかりました。
データ（画像）を取得するのが目的ならシーン情報の取得は必須ではないこと、「data_id（シーンID）」と書かれているように、data_idとシーンIDが概念的に同じものを指していることを理解するのにも苦労しました。
（２） シーンを検索して衛星データをダウンロード（後編） （サンプルコード）
前編同様、シーンの検索→（シーン情報の取得）→ファイル情報の取得→ダウンロードURLの取得→データ（画像）ダウンロードという流れが示されずにいきなりコードが登場します。この後編では、ファイル情報の取得→ダウンロードURLの取得→データ（画像）ダウンロードが扱われます。
細かいことですが、ファイル情報の取得に相当する関数名が、この後編ではget_files_listとなっていて、ややミスリーディングです。データ（画像）ファイルにはまだまだたどり着けませんので。私はget_file_informationという名前の関数にしました。
ダウンロードURLの取得では、何の説明もなしにfile_idとして9が指定されていることに戸惑います。おそらく、その前の段階のファイル情報の取得結果をprintで表示して、ほしいファイルのidを目視で見つけ出したのでしょう。私はwebcog形式のファイルがほしかったので、やむなく「if “webcog” in file[“name”]:」としてそのファイルidを見つけ出すコードを書きました。
データ（画像）ファイルのURLまで取得できれば、あとはTellus公式データAPIというよりもPythonの一般的な処理になります。この後編では複数ファイルを一括でダウンロードするコードを示してくれていますが、読みづらく、一つのファイルがダウンロードできたら複数ファイルをダウンロードするように拡張するのはPythonの知識でできるので、この部分は参考にしていません。
（３） 光学データ「SLATS」をダウンロードして画像結合 （サンプルコード）
国立競技場の衛星画像を取得するという、見た目にわかりやすく興味深い内容です。
しかし、致命的なことに、ここで説明されているSLATSはTellus環境でのみ利用可能で、それ以外の環境からは利用できません。
開発/解析環境 | Tellusによると、Tellus環境は最低でも月額１万円を超えるので、個人で気軽に試すにはハードルが高すぎます。
どおりで国立競技場の衛星画像を取得してみたくてサンプルコードを慎重にコピーして何度実行してもうまくいかないわけです。画像をダウンロードするところで「KeyError: ‘download_url’」が発生します。エラーが発生した「url = download_url[“download_url”]」の行の直前に「print(download_url)」を実行してみたら、「{‘detail’: ‘このアクションを実行する権限がありません。’, ‘code’: ‘permission_denied’}」という表示だったため、権限の問題だと気づきました。
APIの使い方を説明する記事でTellus環境からしか使えないデータセットを例に取るのはやめてもらいたいです。ここで時間を浪費しました。
また、仮にこの問題をクリアしたとしても、（１）（２）と同様のわかりにくさに加えて、分割した画像で国立競技場が写っている範囲をおそらく目視で推測して選んでいるのがとてもわかりにくいです。「io.imshow(img[row1_size * 20 : row1_size * 30, col1_size * 15 : col1_size * 25, :])」の数値がどこから出てきたのかが疑問です。
（４） SARデータ「PALSAR-2」をダウンロードして描画 （サンプルコード）
いちいち細かく示しませんが、PALSAR-2もTellus環境でのみ利用可能で、それ以外の環境からは利用できません。
これをAPIの説明で例に使われても…と感じます。
４．まとめ
せっかく素晴らしいデータを無料で公開しているのに、ドキュメントがわかりづらくて利用できていない人がたくさんいるのではないかと危惧します。
このデータをもっと多くの人が有効活用できるように、私が理解した限りのことを書き残しました。