We have decided to create this article after having received multiple requests to do one that explains how to use API on Tellus, something we spoke about on day six of our “Courses on the Basics of Satellite Data“.  This was held every Wednesday in 2020 for 7 weeks from 7/15 to 8/26.

IT has been uploaded to YouTube, so please use that as a reference as well.

An Overview of API on Tellus

There are 4 main types of API on Tellus.

1 User Definition API

The first type we will start off with is called “User Definition”, and this API takes graphics created on Tellus OS and brings it into the development environment. You can also use it to erase graphics or create new ones.

Here is a reference for the API:
https://www.tellusxdp.com/docs/api-reference/users-v1.html

The following three types of API are used when working with different types of data.

2 Satellite Data API

Satellite data API can be split into “GPS”, “optics”, and “radar (SAR)”. For this article, we will be mainly talking about optics, so we will take a moment to explain GPS and radar (SAR).

GPS data uses a type of data called profile passport.[Tellus Official] Location Information｜Profile Passport
https://www.tellusxdp.com/market/tool_detail/tellus-default/122

The current data for radar (SAR) images available on Tellus is taken by PALSAR-2 and ASNARO-2.

[Tellus Official] PALSAR-2 | ALOS-2
https://www.tellusxdp.com/market/tool_detail/tellus-default/53

[Tellus Official] ASNARO-2
https://www.tellusxdp.com/market/tool_detail/tellus-default/57

3 Weather Observation Data API

For weather observation data, we adopt a data set called AMeDAS, which uses sensors on the ground owned by the Japan Meteorological Agency to record data on precipitation rates, snowfall, and humidity.

[Tellus Official] AMeDAS 1 minute interval
https://www.tellusxdp.com/market/tool_detail/tellus-default/74

4 Distribution Statistics Data API

The final type of data is called distribution statistic data, which uses mobile spatial statistics to look at distributions of people over time.

[Tellus Official] Population Statistic Data｜Mobile Spatial Statistics
https://www.tellusxdp.com/market/tool_detail/tellus-default/125

In the next part of this article, we will dive a little deeper into optical satellite data.

The Different Types of API for Satellite Image (Optical) on Tellus

During our lecture, we divided optical satellite data into 4 categories.

1 Weather Data

We have image data taken by the meteorological satellite Himawari-8 available on Tellus.

[Tellus Official] Himawari-8
https://www.tellusxdp.com/market/tool_detail/tellus-default/71

2 Altitude

You can combine multiple optical satellite data points to determine the altitude of something through stereoscopic vision. Tellus has two different kinds of altitude data sets available, but the set that can be used with API is called ASTER GDEM.

[Tellus Official] ASTER GDEM 2
https://www.tellusxdp.com/market/tool_detail/tellus-default/60

[Tellus Official] ASTER GDEM 3
https://www.tellusxdp.com/market/tool_detail/tellus-default/61

3 High Resolution

There are multiple satellite images which have a ground surface resolution of less than 1m available on Tellus. At less than 1m, you can see objects such as cars.

[Tellus Official] SHIROP | SLATS
https://www.tellusxdp.com/market/tool_detail/tellus-default/50

[Tellus Official] ASNARO-1
https://www.tellusxdp.com/market/tool_detail/tellus-default/47

[Tellus Official] Mock ALOS-3 *Added after the course on 9/4/2020
https://www.tellusxdp.com/market/tool_detail/tellus-default/285

4 Multi-Wavelength

The imagery captured by satellites is of a variety of wavelengths beyond just red, blue, and green. We have API to extract those components as well.

[Tellus Official] AVNIR-2 | ALOS
https://www.tellusxdp.com/market/tool_detail/tellus-default/44

[Tellus Official] Landsat-8
https://www.tellusxdp.com/market/tool_detail/tellus-default/52

The wavelengths also can be captured by the ASNARO-1 and mock data of ALOS-3 which we introduced when we talked about high-resolution satellites.

5 Original Data API *has been added to the lecture

The API we have introduced up until now are those that can pull up data in the tile-format on Tellus.
There are also a few API that give you the raw data.

[Tellus Official] AVNIR-2 | ALOS
https://www.tellusxdp.com/docs/api-reference/avnir2-files-v1.html

[Tellus Official] PALSAR-2 | ALOS-2
https://www.tellusxdp.com/docs/api-reference/palsar2-files-v1.html

How to use API on Tellus

In this next part, we will explain how to use each of the API we have listed here.

You can find more information about this data on the Tellus market.

If you know the name of the satellite you want to use, you can enter its name or sensor name into the search bar, and if you don’t know its name, you can just search for optical or SAR.

Choose one of the data sets by clicking it, and it will show you its API reference on the details page.

If you want to see the API reference for all of the data, click “detailed search” on the product search page shown above.

On the detailed search page, leave the keyword as blank, set the category to data, and select API as the connection method. Then click the “search with set filters” button at the bottom of the screen and Tellus will show you all the API it has available.

Getting back on topic, we will use ASNARO-1 as an example.

There is a total of 4 API for ASNARO-1.

The two on top are used for pulling up satellite image data. The two on the bottom are used for pulling up the actual image (as a .png image).

When pulling up satellite images, use the two steps below to load the satellite data.

① Captured Image (metadata) Search API

This API is used to find which images match your search criteria.
It allows you to view information on the image

There are two different ways to do your search.

(1) Longitude and Latitude
You can get a list of images for an area you want to view by entering its longitude and latitude. This is the more commonly used method.

(2) ID
Each satellite image has its own unique ID that distinguishes it. This method works when you already know the ID for the image you want on Tellus OS.

The following three points are often used when looking at the search results for satellite images.
– entityID
Can be used to pull up satellite images with color using the ID explained before.
– productID
Can be used to pull up different combinations of wavelengths, other than RGB.
– thumbs_URL
Allows you to see the satellite image as a thumbnail. Tellus uses PNG tile images, which are cropped an shown as a thumbnail of the image.

② Tile Images Acquisition API

Repeating what we have explained above, use the ID you find via the captured image search API, to find the image you are looking for.

– SceneID: Is linked to the “entity id”/takes something similar to a photo
– Product ID: Takes an image composed through different types of waves.

Now we will get into the more concrete details of how you can use these API.
First, let’s use the captured image (metadata) search API to check whether or not if this is an image we are interested in.

https://gisapi.tellusxdp.com/api/v1/asnaro1/scene?min_lat=31.5661481766963&min_lon=130.47162065429&max_lat=31.7205387930055&max_lon=130.788547580551

If you are using python, you can use the following variables to summarize.

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)

For those of you using JupyterLab, it might be better to define your functions like we have below so that it works for a variety of data sets.

# ライブラリのインポートと描画のための宣言

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()

This is what it looks like when you run the code your wrote using the captured image (metadata) search 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);

The numbers show
number of scenes: 9
which means there are 9 images that came up for the specified area.

You can also see how the entityID, productID, thumbs_URL data we introduced earlier has also appeared.

Next, let’s take a look at the tile image acquisition API.

Image acquisition API uses the product ID we looked up earlier to extract tile images.
Since a single satellite picture is rather large, we will pick them out using images that have been divided up into many smaller tiles in addition to the product ID.

The tile coordinate can be seen by clicking the grid button in the upper right-hand corner of the screen.
The “Z” signifies zoom factor, and the x and y are the coordinates.

Using python for this should give you the following.

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)))

It is also good to define your functions for this API as well.

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);

When you run the API, it will give you a tile image (256 pixels x 256 pixels).

The Configuration of API for Other Data

Earlier, we introduced how to use API for ASNARO-1. When using data for most other satellites, it pretty much works the same way.

(1) Captured Image Data Acquisition API (Longitude and Latitude)

There are 2 main ways to use captured image data acquisition API.

For the most part, this is the same as getting ASNARO-1’s, only this method relies on longitude and latitude.
Landsat-8 is the only set of data that has cloud coverage available to be set as a filter.

(2) Captured Image Data Acquisition API (ID)

The other method for using captured image data acquisition API is to search with using the image’s ID. This is the same for any satellite.

(3) Tile Image Acquisition API

Tile Image Acquisition API uses the same method as ASNARO-1.
You can acquire an image by specifying its scene id and tile coordinates.

(4) Wavelength Composite Tile Image Acquisition API

Wavelength Composite Tile Image Acquisition API uses 2 main parameters.

Path parameters includes information on fixed parameters (to find the angle at which the satellite image was taken), zoom level, tile coordinates, and query parameters that contain more parameters to select wavelength and transmittance. Although path parameters are different for each satellite, all satellites share the same query parameters.

The reason a fixed ID is required is, as shown in the above image, there are multiple scenes taken from the same spot (tile coordinate), meaning you need an ID to specify which image you would like to use.

Let’s take a closer look at each satellite below.

ASNARO-1 uses productID and tile coordinates.

AVNIR-2 uses productID, rspID, and tile coordinates.
RSP stands for Reference System for Planning here, and you can think of it as a search system.

Landsat-8 let’s you specify the satellites path and row, or where it is in its trajectory.

(5) Other Tile Images Acquisition API

Other API have the same basic structure.

The altitude data “ASTER GDEM” extracts pictures using tile coordinates.

Images taken by the meteorological satellite Himawari can be selected by using the time and date instead of product ID.

Summary

That ends our quick explanation of API on Tellus.
Try using API on the development environment for yourself!

Try using satellite data on “Tellus”!
Want to try using satellite data? Try out Japan’s open and free to use data platform, “Tellus”!
You can register for Tellus here