Query Construction

Elements of a Query

When constructing a query, specify four things:

1. the variable (data source) you want; (one of ndvi.streambatch or ndvi.modis)
2. the space you want; i.e. what location(s) you want NDVI for.
3. the time you want; i.e. over what period do you want data.
4. the output you want; set raster to true for raster data; false for time series data. (default is false)

You provide this information to the API as a JSON object. Here's an example:

query  = {
    'variable': ['ndvi.streambatch'],
    'space': [[-44.149163, -20.789250]], 
    'time': {
        'start':'2018',
      	'end':'2023',
      	'unit':'day'
    },
  	'raster':'false'
}

These four parameters are discussed in detail below.

Variable (what data)

The variable parameter is used to specify the data you want. variable must be set to one of:

Space (what locations)

space defines the location you want data for. It can be a single point, a set of points, a polygon (whose boundaries are defined by a set of points), or a set of polygons. An overview of these options follows. For details see the Space reference page.

Points

To get data for one or more points, specify a list of points. For example:

'space': [[-44.149163, -20.789250]] # single point location (lon,lat) 

Or:

'space': [[-44.149163, -20.789250], [-44.133113, -20.232451]] 

Single Polygon

To get data for a polygon, specify it as GeoJSON, for example:

'space': [
	{
  	'type':'Polygon',
  	'coordinates': [(-44.149163, -20.789250),(-44.162389, -20.793057),(-44.157394, -20.802396),(-44.144168, -20.798589)]
	}
]

Multiple Polygons

To get data for multiple polygons, provide a list. For example:

polygons = [{'type':'Polygon', 'coordinates':[[(-44.149163, -20.789250), (-44.162389, -20.793057), (-44.157394, -20.802396), (-44.144168, -20.798589)]]},
            {'type':'Polygon', 'coordinates':[[(-45.149163, -21.789250), (-45.162389, -21.793057), (-45.157394, -21.802396), (-45.144168, -21.798589)]]]
...
'space': polygons

Time

time defines the date range and frequency for which you want data. For example:

'time': {
	'start':'2018',
	'end':'2023',
	'unit':'day'
}

See the Time section for additional information on specifying time-related query parameters.

Raster

Set raster to falseor leave the parameter out entirely to get time series data. Set raster to true to get raster data.

'raster': False

if rasteris True, space must be a polygon. (Requesting raster data for a single point makes no sense and is invalid input.)

Output data format depends on the value of raster:

When rasteris true and you have a valid access_url you can pull the output to an xarray:

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

When raster is false and you have a valid access_url you can pull the output to a dataframe:

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