API Reference

Overview

📘

Quick Start

Here is a recipe to get a time series of daily NDVI for a single point.

Here is a recipe to get a time series of daily NDVI for a polygon.

Time Series NDVI Overview

The Streambatch API is asynchronous. There are four steps to get an NDVI time series:

  1. In JSON, specify the location(s) and time frame you want NDVI for.
  2. POST that specification to https://api.streambatch.io/async; get an id for query and access_url in return.
  3. Wait until the job is processed.(Poll at https://api.streambatch.io/check.)
  4. GET your data from the access_url

Here are the four steps as an executable Python program:

import requests
import pandas as pd
import json
import time

# Replace YOUR_API_KEY with your actual API key
api_header = {'X-API-Key': YOUR_API_KEY}

#
# STEP 1: Specify what you want
#
ndvi_query = {
    'variable': ['ndvi.streambatch'],
    'space': [[-44.149163, -20.789250]], 
    'time': {
        'start':'2018',
      	'end':'2023',
      	'unit':'day'
    }
}


#
# STEP 2: Make the request
#
response = requests.post('https://api.streambatch.io/async', json=ndvi_query, headers=api_header)
result = json.loads(response.content)
query_id = result.get('id')
access_url = result.get('access_url')


#
# STEP 3: Wait for job to finish
#
query_finished = False
while not query_finished:
  status_response = requests.get('https://api.streambatch.io/check?query_id={}'.format(query_id), headers=api_header)
  status = json.loads(status_response.text)
  if (status['status'] == 'Succeeded') or (status['status'] == 'Failed'):
    query_finished = True
    print("Finished")
  else:
    print(".",end="")
    time.sleep(5)
    

#
# STEP 4: Get the data
#

ndvi_data = pd.read_parquet(access_url, storage_options={"anon": True})

Rasters

To get NDVI as rasters, make two changes to the program above:

First, set the space parameter to be a polygon and add 'raster':True to the request:

farm_polygon = [{'type': 'Polygon', 'coordinates': 
                [[[-94.4545917478666, 41.9792090154671], 
                  [-94.4545448033213, 41.9757220431519], 
                  [-94.4450066084548, 41.9757090969481], 
                  [-94.4450437851949, 41.9792826686391], 
                  [-94.4545917478666, 41.9792090154671]]]}]

ndvi_query = {
    'variable': ['ndvi.streambatch'],
    'space': farm_polygon, 
    'time': {
        'start':'2018',
      	'end':'2023',
      	'unit':'day'
    },
    'raster': True
}

Second, change the last line of the program to accommodate raster data which will be in zarr format.

ndvi_data = xr.open_zarr(access_url, storage_options={"anon": True})

Here is the complete program for getting NDVI data in raster form:

import requests
import pandas as pd
import json
import time
import xarray as xr

# Replace YOUR_API_KEY with your actual API key
api_header = {'X-API-Key': YOUR_API_KEY}

#
# STEP 1: Specify what you want
#
farm_polygon = [{'type': 'Polygon', 'coordinates': 
                [[[-94.4545917478666, 41.9792090154671], 
                  [-94.4545448033213, 41.9757220431519], 
                  [-94.4450066084548, 41.9757090969481], 
                  [-94.4450437851949, 41.9792826686391], 
                  [-94.4545917478666, 41.9792090154671]]]}]

ndvi_query = {
    'variable': ['ndvi.streambatch'],
    'space': farm_polygon, 
    'time': {
        'start':'2018',
      	'end':'2023',
      	'unit':'day'
    },
    'raster': True
}


#
# STEP 2: Make the request
#
response = requests.post('https://api.streambatch.io/async', json=ndvi_query, headers=api_header)
result = json.loads(response.content)
query_id = result.get('id')
access_url = result.get('access_url')


#
# STEP 3: Wait for job to finish
#
query_finished = False
while not query_finished:
  status_response = requests.get('https://api.streambatch.io/check?query_id={}'.format(query_id), headers=api_header)
  status = json.loads(status_response.text)
  if (status['status'] == 'Succeeded') or (status['status'] == 'Failed'):
    query_finished = True
    print("Finished")
  else:
    print(".",end="")
    time.sleep(5)
    

#
# STEP 4: Get the data
#

ndvi_data = xr.open_zarr(access_url, storage_options={"anon": True})