Batch Supply Shed

The /batch_supply_shed endpoint complements the /batch_process endpoint by providing the ability to compute environmental metrics (e.g, deforestation, biomass emissions) for all areas growing a specific commodity (e.g. cocoa, rubber, palm oil) with a representative supply shed (i.e. an equal travel time isochrone from a processing facility). It leverages state-of-the-art commodity models made available by Google to identify and discretize commodity plots in a region of interest.

This is particularly useful when the exact plot locations are not known, but the broader region of interest and target commodity are known.

Note: If you provide polygon geometries (instead of point geometries) in your input file, the endpoint will skip isochrone generation and use those polygons directly as the supply shed for plot detection.

Key Datasets

The probabilistic deforestation check using the same logic as the batch_process, but adds a step to generate the commodity plots based on an input AOI and commodity type.

The key datasets used in this process are:

1. Forest Data Partnership Forest Persistence: FDP Forest Persistence layer is used in this context to mask out natural forests from the commodity plot discretization process. Only plot locations which are not classified as natural forests as per the date of processing are considered for commodity plot generation.

2. Forest Data Partnership Commodity Probability Models: In order to discretize commodity plots of interest, we further leverage the FDP Commodity Probability Models. These enable to identify locations of high probability of commodity presence, which are then discretized into commodity plots using a probability threshold that is locally defined. For Timber, timber commodity plots are identify by looking at areas which fall outside of all other commodity masks, as well as outside of the persistent forest mask. The biomass density in the latest year generated by Epoch's Biomass models (see Biomass Emissions for more information) is used to identify canopy-covered areas higher than 5m canopy height as timber plots.

Key Considerations

See below a list of key considerations to keep in mind when using the /batch_supply_shed endpoint:

1. The area calculations are weighted, which means that the exact proportion of overlapping pixels are accounted for in the reported non-compliance areas. This avoids over- and under-accounting issues.

2. The plot boundaries generated are probabilistic. They offer no guarantee that this plot is within a given supply chain. In that sense, for EUDR compliance, the user must take appropriate measures to ensure that the plots generated by this API endpoint and which identify a deforestation risk are indeed within (or outside) the supply chain of interest. If this is not done, the user can still use this information as a risk assessment for its AOI, but it will not be suitable to support EUDR compliance check.

3. The thumbnail shows changes in and around the plot, but the reported values in the response ONLY report changes WITHIN the plot. The change data surrounding the plot itself is shown in the thumbnail for reference, and to highlight potential risks around the plots themselves. For a more comprehensive statistical comparison to a reference area (supply shed, watershed, administrative unit), the Batch API should be used.

4. The confidence attribute is provided when the noncompliance_area is superior to 0, and ranges from very low to very high. It is advised to visualize the thumbnails for very low, low and medium cases as it may be due to geo-referencing issues or false positives.

5. The deforestation_alert attribute is the final assessment of the deforestation event, and can take no deforestation, non-critical or critical as values. This is a qualitative assessment of the deforestation event, and is based on the noncompliance_area, confidence and agreement attributes.

Deforestation Categorization Metrics

The deforestation detection and categorization follows the European Union Deforestation Regulation (EUDR) definition of forest and uses standardized thresholds to classify deforestation events as critical or non-critical.

For detailed information on EUDR forest definitions, deforestation alert thresholds, and confidence levels, see the Deforestation Check documentation.

Parameters and Headers

Basic Parameters

A typical example of a basic payload for the /batch_supply_shed endpoint is the following:

request_data = {
    "collection_name": '<collection_name>',
    'description': '<collection_description>',
    "stats": 'luc_emissions,eudr_deforestation', # (1)!
    "crop_type": "Cocoa", # (2)!,
    "eudr_dds": False, # (3)!
    "travel_times": [120] # (4)!
}   

files = {
    'file': ('<file_name>', open('<local_path_to_file>', 'rb'),
             'application/geo+json') # (5)!
}

1. The statistics to run. Can be 'eudr_deforestation', 'luc_emissions', 'biodiversity', 'water', or any combination separated by commas.
2. Crop type, i.e. the target commodity to retrieve information for. Can be any of 'coffee', 'timber', 'rubber', 'palm', 'cocoa', 'cattle', 'soy', or other supported commodity types.
3. Whether to export an EUDR Due Diligence Statement automatically.
4. The travel time to use for the supply shed delineation. If not provided, a commodity-specific assumption is made on a realistic travel time.
5. Pass the path to a geojson file containing processing facilities (points) or supply shed polygons. For points: the file should contain "Facility ID", "Facility Address" and "Company Name" fields. For polygons: isochrone generation is skipped and polygons are used directly for plot detection.

Complete Parameter List

The /batch_supply_shed endpoint extends the /batch_process parameters with additional supply shed-specific parameters:

Parameter	Type	Required	Default	Description
collection_name	string	Yes	-	Collection name to assign to the staged file
input_payload	object/string	No	{}	Detailed agricultural and supply chain data for emissions calculations
crop_type	string/int	Yes	-	Target commodity for supply shed processing
processing_type	string	No	-	The processing type that the commodity undergoes
system_type	string	No	-	The system type that the commodity is grown in
description	string	No	-	A description of the staged file
stats	string	No	"eudr_deforestation,luc_emissions,biodiversity"	Stats to compute, comma-separated (e.g. eudr_deforestation,luc_emissions)
non_biomass	boolean	No	false	Whether to compute non-biomass emissions
validate_locations	boolean	No	true	Whether to validate input geometries/locations
travel_times	array[int]	No	[]	Travel times (minutes) for isochrone-based supply sheds
radii	array[int]	No	[]	Radii (meters, min 1000) for circular buffer supply sheds (cannot be used with travel_times). One supply shed is created per radius.
plots_only	boolean	No	false	If true, stop after plot delineation
geocode	boolean	No	false	If true, geocode empty geometries in the uploaded file

Supply Shed Specific Parameters

Travel Times

• travel_times: Array of travel times in minutes (e.g., [60, 120, 180])
• Used to create isochrone-based supply sheds from processing facilities
• Each travel time creates a separate supply shed analysis

Radii

• radii: Array of radii in meters (minimum 1000m), e.g. [5000, 10000]
• Alternative to travel times for creating circular buffer supply sheds
• One supply shed is created per radius
• Cannot be used together with travel_times

Processing Options

• plots_only: If true, stops after plot delineation (skips emissions calculations)
• geocode: If true, attempts to geocode addresses in input_payload

Input Payload Parameter

The input_payload parameter is a complex nested structure that contains detailed agricultural and supply chain data for accurate emissions calculations. It consists of three main payload types:

• CFT Payload: Cool Farm Tool data for farm-level emissions
• LCA Payload: Life Cycle Assessment data for supply chain emissions
• EUDR Payload: EU Deforestation Regulation compliance data

For detailed documentation on the input_payload structure, see the Input Payload Documentation.

Example with Input Payload

import json

# Define the input payload with detailed agricultural data
input_payload = {
    "cft_payload": {
        "crop": {
            "type": "cocoa",
            "yield": {"value": 500, "unit": "kg/ha"}
        },
        "farm": {
            "size": {"value": 10, "unit": "ha"},
            "location": {"country": "Ghana"}
        }
    },
    "eudr_payload": {
        "product_type": "cocoa",
        "production_country": "Ghana",
        "production_year": 2024
    }
}

request_data = {
    "collection_name": "cocoa_supply_shed_2024",
    "description": "Cocoa supply shed analysis with travel time analysis",
    "input_payload": json.dumps(input_payload),  # JSON stringify for form data
    "crop_type": "cocoa",  # Required for supply shed
    "stats": "luc_emissions,eudr_deforestation",
    "travel_times": [60, 120, 180],  # 1, 2, and 3 hour travel times
    "resolution": 50,  # Higher resolution for detailed analysis
    "geocode": True  # Geocode any addresses in the payload
}

With the headers being:

headers = {
    'Authorization': "Bearer <authorization_token>",
    'accept': '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:

import requests
import json

response = requests.post("https://epoch-sco2-api.com/batch_supply_shed", 
                         files=files, 
                         data=request_data, 
                         headers=headers)

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

Javascript

const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

// Create a form-data object
const form = new FormData();

const request_data = {
    "collection_name": '<collection_name>',
    "description": '<collection_description>',
    "stats": 'luc_emissions,eudr_deforestation',
    "crop_type": 'Cocoa', 
    "eudr_dds": False,
    "travel_times": [120]
};

// Append form fields
form.append('request_data', JSON.stringify(request_data));

// Append the file
form.append('file', fs.createReadStream('<local_path_to_file>'), {
    filename: '<file_name>',
    contentType: '<file_format>' // e.g., 'application/geo+json', 'text/csv'
});

// Define headers, including the form-data headers
const headers = {
    'Authorization': "Bearer <authorization_token>",
    ...form.getHeaders()
};

// Send the request using axios
axios.post('https://epoch-sco2-api.com/batch_supply_shed', form, { headers })
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

Curl

curl -X POST https://epoch-sco2-api.com/batch_supply_shed \
-H "Authorization: Bearer <authorization_token>" \
-F "request_data={
    \"collection_name\": \"<collection_name>\",
    \"description\": \"<collection_description>\",
    \"stats\": \"luc_emissions,eudr_deforestation\",
    \"crop_type\": \"Cocoa\",
    \"eudr_dds\": false,
    \"travel_times\": [120],
}" \
-F "file=@<local_path_to_file>;type=<file_format>;filename=<file_name>"

Response

The response indicates that processing has started in the background, or that processing was skipped:

# Normal processing response
response = {
    "status": "PROCESSING",
    "facility_tracking_id": "0x44c87929d1ed966d86a844a98744bd7e3d47aa3da48e262150874c2bc8313feb",
    "facility_ids": ["facility_1", "facility_2", "facility_3"],
    "ungeocoded_facility_ids": ["facility_4"],
    "message": "Batch supply shed processing started in background"
}

Important: - The facility_tracking_id (also known as tracking_id) is used to monitor progress via the /batch_progress endpoint - facility_ids lists all facilities that were successfully geocoded and will be processed - ungeocoded_facility_ids lists facilities that failed geocoding and will not be processed - Processing is asynchronous - results will be available once processing completes - Use the facility_tracking_id to track progress and retrieve results

Step-by-Step Explanation of the Process

The process of the /batch_supply_shed endpoint can be broken down into the following steps:

1. Delineation of a supply shed or region of interest (ROI) using the user-provided geometry.

This supply shed provides a representative sourcing area from a processing facility by looking at the travel time from it using the road network. Note: If polygon geometries are provided instead of point facilities, this step is skipped and the polygons are used directly.

1. Generation of probabilistic commodity plots within the above-delineated supply shed, based on the commodity type provided by the user.

This approach of pre-generating commodity plots circumvents the data gaps which are commonly encountered when dealing with suppliers that do not have exact plot locations.

1. Deforestation checks are performed on the generated commodity plots, using the same logic as the /deforestation_check endpoint.

This gives a comprehensive overview of the deforestation risk within the supply shed, based on the commodity type of interest. In cases of residual deforestation, the user can proceed by exclusion by asking the supplier to confirm they are not sourcing from the non-compliant plots. In cases of significant deforestation, the user can prioritize engaging with high-priority suppliers that have significant deforestation risk exposure, and prompt them for corrective action (i.e provide exact commodity sourcing locations).