Skip to content

Batch Zonal Statistics

The /batch_zonal_stats API endpoint allows users to generate the same sustainability metrics as the ones generated with the Core APIs, but for a large number of plots or input geometries. Core APIs are intended for small uploads (few dozens to few hundreds of plots), while Batch Zonal Statistics enable the processing of thousands of plots.

Moreover, the batch processed sustainability metrics are systematically stored and can be queried at any time by the user, either through the user interface (Monitoring pane', or using the Fetch APIs.

The advantage of processing large supply bases through the Batch Zonal Statistics procedure is that they can be visualized at a glance in the dashboard, aggregated at supply-base level (e.g. overall deforestation non-compliance rate, Biomass emissions, etc), but also compared to a statistically representative reference area, i.e. other commodities grown within the same administrative area or watershed. This is particularly helpful to compare the environmental performance of a given supply-base against the overall supply of that same commodity in the same jurisdiction or region.

The Batch Zonal Statistics endpoint is an asynchronous REST service. This means that data will not be returned immediately in a request response but will be delivered to your user dashboard.

Alternatively, the following endpoints can also be used to process specific metrics using the batch logic:

  • /batch_deforestation_check

  • /batch_biomass_emissions

  • /batch_biodiversity

  • /batch_water

They are identical to running /batch_zonal_stats with the corresponding metric (deforestation, biomass emissions, biodiversity, water).

An upload and batch-processed supply base looks like this:

Monitoring dashboard example

Batch Processing via Dashboard

Following a Batch Upload operation via the dashboard (see [Batch Upload] documentation), a Start Processing button appears, which will trigger the Batch Zonal Statistics when clicked.

Monitor Dashboard Batch Zonal Stats

The process may take anywhere between a few minutes and a few hours. The status can be monitored in the Account page of the platform.

Monitoring processing progress

Once the processing has successfully completed, it can be visualized in the Monitoring pane, by selecting the corresponding file from the drop-down menu in the top right of the screen.

Select file to visualize

Batch Processing via API

Parameters and Headers

An example of a payload for the /batch_zonal_stats endpoint is the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
request_data = {
    "filename": '<collection_name_or_collection_id>',
    "date": '2024-08-07'
}

request_data_deforestation = {
    "filename": '<collection_name_or_collection_id>',
    "date": '2024-12-31',  # End date for monitoring period (up until processing)
    "start_date": '2020-12-31'  # For EUDR: set to EUDR cut-off date to check deforestation after this date
}

With the headers being:

1
2
3
4
headers = {
    'Authorization': "Bearer <authorization_token>",
    'Content-Type': 'application/json'
}

The Authorization header must be replaced by your user token. Check this page for more information on how to authenticate.

Python

In python, you can submit a request in the following way:

batch_zonal_stats.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import requests
import json

response_biodiversity = requests.post("https://epoch-sco2-api.com/batch_biodiversity",
                                      json=request_data, 
                                      headers=headers)

response_biomass_emissions = requests.post("https://epoch-sco2-api.com/batch_biomass_emissions", 
                                           json=request_data, 
                                           headers=headers)

response_deforestation = requests.post("https://epoch-sco2-api.com/batch_deforestation_check", 
                                       json=request_data_deforestation, 
                                       headers=headers)

json_result = json.loads(response.content)
print(json_result)

Javascript

batch_zonal_stats.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
const axios = require('axios');

const headers = {
    'Authorization': "Bearer <authorization_token>",
    'Content-Type': 'application/json'
};

const requestData = {
    "filename": '<collection_name_or_collection_id>',
    "date": '2024-08-07'
};

const requestDataDeforestation = {
    "filename": '<collection_name_or_collection_id>',
    "date": '2024-12-31',  // End date for monitoring period
    "start_date": '2020-12-31'  // For EUDR: set to EUDR cut-off date
};

// Biodiversity request
axios.post("https://epoch-sco2-api.com/batch_biodiversity", requestData, { headers })
    .then(response => {
        console.log("Biodiversity response:", response.data);
    })
    .catch(error => {
        console.error("Error in Biodiversity request:", error);
    });

// Biomass Emissions request
axios.post("https://epoch-sco2-api.com/batch_biomass_emissions", requestData, { headers })
    .then(response => {
        console.log("Biomass Emissions response:", response.data);
    })
    .catch(error => {
        console.error("Error in Biomass Emissions request:", error);
    });

// Deforestation Check request
axios.post("https://epoch-sco2-api.com/batch_deforestation_check", requestDataDeforestation, { headers })
    .then(response => {
        console.log("Deforestation Check response:", response.data);
    })
    .catch(error => {
        console.error("Error in Deforestation Check request:", error);
    });

Curl

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Biodiversity request
curl -X POST https://epoch-sco2-api.com/batch_biodiversity \
-H "Authorization: Bearer <authorization_token>" \
-H "Content-Type: application/json" \
-d '{"filename": "<collection_name_or_collection_id>", "date": "2024-08-07"}'

# Biomass Emissions request
curl -X POST https://epoch-sco2-api.com/batch_biomass_emissions \
-H "Authorization: Bearer <authorization_token>" \
-H "Content-Type: application/json" \
-d '{"filename": "<collection_name_or_collection_id>", "date": "2024-08-07"}'

# Deforestation Check request
curl -X POST https://epoch-sco2-api.com/batch_deforestation_check \
-H "Authorization: Bearer <authorization_token>" \
-H "Content-Type: application/json" \
-d '{"filename": "<collection_name_or_collection_id>", "date": "2024-12-31", "start_date": "2020-12-31"}'

Response

The response indicates that processing has started in the background:

1
2
3
response = {
    "status": "PROCESSING"
}

Important: - Processing is asynchronous - results will be available once processing completes - Use the filename (collection_id) to track progress via /batch_progress and retrieve results via the Fetch API endpoints - For detailed progress tracking, see the Batch Progress documentation