API User Guide

Introduction

Welcome to the VanderSat API User Guide. In this document you can find general information about the functioning of our RESTful API.

For a comprehensive list of API endpoints and parameters, please visit https://maps.vandersat.com/api/v2. There you will also be able to try out API requests and inspect responses, directly in the browser.

Interactive API documentation used for trying out the product listing request

Authentication

Username and password are supplied to you through separate channels. These credentials can be easily changed in the VanderSat Viewer by going to the Settings menu in the top right corner.

We support HTTP basic authentication. There are two ways of providing your authentication:

1. Go to https://maps.vandersat.com/api/v2/products/ and provide your username and password in the authentication popup. Alternatively, provide your credentials directly in the URL: https://username:password@maps.vandersat.com/api/v2/products

2. Provide your username and password in the HTTP header of the request. For example, use Python’s requests library:

import requests
import json

r = requests.get('https://maps.vandersat.com/api/v2/products',
                 auth=('username', 'password'))  # change username and password
r.raise_for_status()
product_dict = json.loads(r.content)

to get a Python dictionary with all products available to this user account.

Python client

vds-api-client is a Python and command line interface to download data from the API. This package simplifies and speeds up the process of making API requests and downloading data.

The project is on GitHub and the package can be pip installed from PyPI:

$ pip install vds-api-client

More information on using the client can be found in the package documentation.

Data availability

Checking access to VanderSat products

Your VanderSat account gives access to a number of different products, depending on your contract with us. To get a complete list, make the following GET request (for example, by typing the URL in your browser address bar):

GET https://maps.vandersat.com/api/v2/products/

The most important field for each product is the api_name, which is needed for requesting data.

An extensive description of all the products can be found on the Data Products page.

Checking data availability for a specific VanderSat product

To check the availability of a product, get the api_name as described in the previous section and make the following request:

GET https://maps.vandersat.com/api/v2/products/{api_name}/availability

The returned JSON object contains a list of datetime values. The date component indicates days for which data is available. The time component can be ignored; for local overpass times, please refer to the Data Products page.

Data requests

This section introduces the main endpoints for making data requests. For a comprehensive list of endpoints and parameters, please visit https://maps.vandersat.com/api/v2.

Some endpoints are asynchronous, which means that the response contains a UUID with which you can monitor the processing status and download the data. How to download the data once it is ready, will be explained in the Data downloading section. Please be aware that the requested data is stored until 7 days after submitting the request.

Requesting images with xyztiles

The xyztiles endpoint can be used as an XYZ tile service. The returned PNG tiles of 256x256 pixels allow you to easily display the images in a web mapping application, similar to our Viewer.

The endpoint follows the slippy map tilenames specification as defined by OpenStreetMap. For example, to add the images to a map built with the JavaScript library Leaflet, create the following tileLayer:

var VDS_map = L.tileLayer('https://{s}.maps.vandersat.com/api/v2/products/{api_name}/xyztiles?x={x}&y={y}&z={z}&date={date}', {
        maxZoom: 15,
        attribution: '© VanderSat'
});

You will need to specify the path parameters {api_name}, {date}, and {s}. Substitute {s} with either a, b, or c, which allows for more concurrent requests. Leaflet will automatically provide the {x}, {y}, and {z} values depending on map location and zoom level.

Requesting images with gridded-data

The gridded-data endpoint lets you request image data. It is asynchronous and data can be requested in either GeoTIFF or NetCDF format.

Example request - Get L band soil moisture for May 2018 in GeoTIFFs:

GET https://maps.vandersat.com/api/v2/products/SM-LN_V001_100/gridded-data?lon_min=3&lon_max=7&lat_min=51&lat_max=53&start_date=2018-05-01&end_date=2018-05-31&format=gtiff&zipped=false

Example request - Get land surface temperature for 2017 in zipped NetCDFs:

GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/gridded-data?lat_min=51&lat_max=53&lon_min=3&lon_max=7&start_date=2017-01-01&end_date=2017-12-31&format=NetCDF4&zipped=true

Requesting point time series with point-time-series

The endpoint point-time-series lets you request a time series for a point location. It is asynchronous and data can be requested in either CSV or JSON format.

Example request - Get L band soil moisture time series from April 2015 to April 2019 at 51.386 degrees latitude and 4.647 degrees longitude:

GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/point-time-series?start_time=2015-04-01&end_time=2019-03-31&lat=51.386&lon=4.647&format=csv&avg_window_days=0&include_masked_data=false&climatology=false

Example request - Same request as above, but also include a 15-day moving average, masked data (marked as invalid), the climatology based on the average column, and the derived root zone calculation given T=10 days. Get the output data in JSON format:

GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/point-time-series?start_time=2015-04-01&end_time=2019-03-31&lat=51.386&lon=4.647&format=json&avg_window_days=15&include_masked_data=true&climatology=true&exp_filter_t=10

Requesting ROI time series with roi-time-series and roi-time-series-sync

The endpoints roi-time-series and roi-time-series-sync let you request time series for a region of interest (ROI). They are asynchronous and synchronous, respectively, and data can be requested in either CSV or JSON format.

The asynchronous roi-time-series request will calculate missing ROI time series values, whereas the synchronous roi-time-series-sync request will only provide the data that is already calculated. If automatic ROI calculation is turned on for your account then the sync request is all you should need. Please contact your VanderSat point of contact in case of doubt.

It is possible to define ROIs in the Viewer by drawing polygons on the map or uploading a shapefile (see Managing regions of interest). It is also possible to manage ROIs through the rois endpoint (see https://maps.vandersat.com/api/v2 for more details).

Example request - Get land surface temperature time series for 2017 as zipped NetCDFs for a previously uploaded ROI.

Using roi-time-series:

GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/roi-time-series?start_time=2015-04-01&end_time=2019-03-31&roi_id=4325

Using roi-time-series-sync:

GET https://maps.vandersat.com/api/v2/products/TEFF_V001_100/roi-time-series-sync?start_time=2015-04-01&end_time=2019-03-31&roi_id=4325

Note

The climatology parameter determines if a climatology should be supplied together with the requested time series data. It is important to realize that the climatology is determined for the period for which the time series is requested. Data available earlier or later is not taken into account.

Data downloading

Downloading data of asynchronous requests

The response of an asynchronous request contains a UUID value:

{
  "url": "api/v2/api_requests/83833aae-1376-4288-b7c7-3e99af57e29f/status",
  "message": "Download request received",
  "uuid": "83833aae-1376-4288-b7c7-3e99af57e29f"
}

with which the processing status can be queried:

GET https://maps.vandersat.com/api/v2/api_requests/83833aae-1376-4288-b7c7-3e99af57e29f/status

The response for Scheduled or Processing requests will look like:

{
  "scheduled_dt": "2019-06-04T11:59:56.409228",
  "percentage": 0,
  "processing_status": "Scheduled"
}

while for requests that are Ready, the response will look like:

{
  "scheduled_dt": "2019-01-24T17:18:45.810523",
  "started_dt": "2019-01-24T17:19:07.409485",
  "processing_status": "Ready",
  "finished_dt": "2019-01-24T17:19:12.698098",
  "data": [
    "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-02T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
    "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-03T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
    "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-04T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
    "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-05T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
    "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-06T000000_6.481934_52.669720_8.602295_51.710012_83833.tif",
    "/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-07T000000_6.481934_52.669720_8.602295_51.710012_83833.tif"
  ],
  "percentage": 100
}

Data of requests that are Ready can be downloaded by making a request to the download endpoint for each of the produced files. For example:

GET https://maps.vandersat.com/api/v2/api-requests/83833aae-1376-4288-b7c7-3e99af57e29f/data/SM-LN_V001_100_2018-12-02T000000_6.481934_52.669720_8.602295_51.710012_83833.tif/download

Note

Data is stored until 7 days after submitting the request.

File naming

gridded-data files

The file naming convention for a gridded-data file is:

<api_name>_<date:YYYY-MM-DDThhmmss>_<lon_min:.6f>_<lat_max:.6f>_<lon_max:.6f>_<lat_min:.6f>_<uuid4_short>.<ext>

or, for zipped files:

<api_name>_<start_date:YYYY-MM-DDThhmmss>_<end_date:YYYY-MM-DDThhmmss>_<lon_min:.6f>_<lat_max:.6f>_<lon_max:.6f>_<lat_min:.6f>_<uuid4_short>.<ext>

with:

• <api_name> Product name as described in Product naming convention.

• <date:YYYY-MM-DDThhmmss> Sensing date, e.g. 2018-12-07T000000.

• <start_date:YYYY-MM-DDThhmmss> Sensing date of first image, e.g. 2018-12-07T000000.

• <end_date:YYYY-MM-DDThhmmss> Sensing date of last image, e.g. 2018-12-07T000000.

• <lon_min:.6f> Minimum longitude rounded to 6 decimals.

• <lat_max:.6f> Maximum latitude rounded to 6 decimals.

• <lon_max:.6f> Maximum longitude rounded to 6 decimals.

• <lat_min:.6f> Minimum latitude rounded to 6 decimals.

• <uuid4_short> First 5 characters of the API request UUID.

• <ext> File extension depending on requested data format (tif, nc, or zip)

Note

Although a datetime is specified, currently only the sensing date is reflected in date, start_date, and end_date. The time is always set to T000000 and should be ignored.

time-series files

The file naming convention for a point-time-series file is:

ts_<api_name>_<start_date:YYYY-MM-DDThhmmss>_<end_date:YYYY-MM-DDThhmmss>_<lon:.6f>_<lat:.6f>_<uuid4_short>.<ext>

and for a roi-time-series file:

roi-ts_<api_name>_<start_date:YYYY-MM-DDThhmmss>_<end_date:YYYY-MM-DDThhmmss>_<roi_id:d>_<uuid4_short>.<ext>

with:

• <api_name> Product name as described in Product naming convention.

• <start_date:YYYY-MM-DDThhmmss> Sensing date of first time point, e.g. 2018-12-07T000000.

• <end_date:YYYY-MM-DDThhmmss> Sensing date of last time point, e.g. 2018-12-07T000000.

• <lon:.6f> Longitude rounded to 6 decimals.

• <lat:.6f> Latitude rounded to 6 decimals.

• <roi_id:d> Identifier of the region of interest (integer value).

• <uuid4_short> First 5 characters of the API request UUID.

• <ext> File extension depending on requested data format (csv or json)

Note

Although a datetime is specified, currently only the sensing date is reflected in start_date and end_date. The time is always set to T000000 and should be ignored.

Data sample

Sample data files available for download

API endpoint	File format	Download
gridded-data	GeoTIFF	gridded_data.tif
gridded-data	NetCDF	gridded_data.nc
point-time-series	CSV	point_time_series.csv
point-time-series	JSON	point_time_series.json
roi-time-series-sync	CSV	roi_time_series_sync.csv
roi-time-series-sync	JSON	roi_time_series_sync.json

Python script example

The Python script below is a minimal example demonstrating how to request and download image data with the gridded-data endpoint.

To run the script, please create a Python>3.6 environment with the requests library installed. Also customize the script by changing the username and password, product name, and output folder.

import os
import time
import json
import requests


BASE_URL = 'https://maps.vandersat.com/api/v2'


def request_data(url, params, auth):
    r = requests.get(url, params=params, auth=auth)
    return json.loads(r.content)['uuid']


def get_status(uuid, auth):
    url = f'{BASE_URL}/api-requests/{uuid}/status'
    r = requests.get(url, auth=auth)
    return json.loads(r.content)


def wait_until_ready(uuid, auth):
    percentage = get_status(uuid, auth)['percentage']
    while percentage < 100:
        print(f"Processing status... {percentage} percent")
        time.sleep(5)
        percentage = get_status(uuid, auth)['percentage']
    print('Finished')


def get_filenames(uuid, auth):
    wait_until_ready(uuid, auth)
    slugs = get_status(uuid, auth)['data']
    filenames = []
    for slug in slugs:
        filenames.append(os.path.basename(slug))
    return filenames


def download_data(filenames, output_folder, auth):
    for filename in filenames:
        url = f'{BASE_URL}/api-requests/{uuid}/data/{filename}/download'
        r = requests.get(url, stream=True, auth=AUTH)
        path = os.path.join(output_folder, filename)
        with open(path, 'wb') as f:
            for chunk in r.iter_content(1024):
                f.write(chunk)


if __name__ == '__main__':

    # Change these values
    OUTPUT_FOLDER = ''
    API_NAME = 'SM-AMSR2-C1N-DESC_V003_100'
    AUTH = ('username', 'password')

    # Define API request URL and parameters
    url = f'{BASE_URL}/products/{API_NAME}/gridded-data'
    params = {
        'lat_min': 51.5,
        'lat_max': 52.5,
        'lon_min': 4,
        'lon_max': 5,
        'start_date': '2020-05-01',
        'end_date': '2020-05-03',
        'format': 'gtiff',
        'zipped': 'false'
    }

    # Request and download data
    uuid = request_data(url, params=params, auth=AUTH)
    filenames = get_filenames(uuid, auth=AUTH)  # wait for processing to finish
    download_data(filenames, output_folder=OUTPUT_FOLDER, auth=AUTH)

This script can be easily modified to request data from other asynchronous endpoints. Below is an abbreviated example for the point-time-series endpoint.

# ...

if __name__ == '__main__':

    # Change these values
    # ...

    # Define API request URL and parameters
    url = f'{BASE_URL}/products/{API_NAME}/point-time-series'
    params = {
        'lat': 52,
        'lon': 4.5,
        'start_time': '2020-01-01',
        'end_time': '2020-05-01',
        'avg_window_days': 10,
        'avg_window_direction': 'center',
        'climatology': 'true',
        'format': 'csv'
    }

    # Request and download data
    # ...

Contact

Address

VanderSat Data Service Wilhelminastraat 43a, 2011 VK, Haarlem, The Netherlands

E-mail

servicedesk@vandersat.com

Standard office hours

9:00 - 17:00 (CET)