Skip to content

Fetch Supply Shed

The /fetch_supply_shed endpoint retrieves supply shed data generated by the batch supply shed process. Supply sheds are automatically delineated areas around processing facilities that represent the travel-time catchment for commodities.

Overview

Supply sheds are statistical regions that can be:

  • admin_area: Administrative units
  • watershed: Hydrological watersheds
  • supply_shed: Travel-time based catchments (default)

The endpoint summarizes environmental statistics (deforestation, biomass emissions, biodiversity, water stress) for commodity plots within each supply shed.

Parameters

Required Parameters

Parameter Type Description
Authorization Header Bearer token for authentication

Optional Parameters

Parameter Type Default Description
filename string None Collection identifier
stat_type string "supply_shed" Type of statistical region (supply_shed, watershed, admin_area, all)
stats string "eudr_deforestation,luc_emissions,biodiversity" Comma-separated statistics to fetch
overlap_threshold float 1.0 Overlap threshold for supply shed regions
monitoring_start string None Monitoring start date (YYYY-MM-DD)
monitoring_end string None Monitoring end date (YYYY-MM-DD)
limit string/int None Number of supply sheds to fetch. Defaults to 1 if filename is provided, or returns all if no filename is provided.

Dynamic Filtering

Any additional query parameters will be used to filter the data:

# Filter by facility ID
/fetch_supply_shed?facility_id=abc123

# Filter by company name
/fetch_supply_shed?company_name=PT%20Hindoli

# Filter by commodity type
/fetch_supply_shed?commodity=palm

# Multiple filters
/fetch_supply_shed?facility_id=abc123&commodity=palm&monitoring_start=2020-01-01

Available Statistics

Statistic Description Fields Included
eudr_deforestation EUDR deforestation detection noncompliance_area_ha, annual_defor_ha, deforestation_thumbnail_url
luc_emissions Land Use Change emissions luc_tco2eyear, luc_tco2ehayear, nonluc_tco2eyear, nonluc_tco2ehayear, biogenic_tco2eyear, biogenic_tco2ehayear, removal_tco2eyear, removal_tco2ehayear, soc_tco2eyear, soc_tco2ehayear, total_tco2eyear, total_tco2ehayear, annual_agb_tco2eha, annual_bgb_tco2eha, annual_soc_tco2eha, emissions_thumbnail_url
biodiversity Biodiversity metrics diversity_score, annual_chm_m, diversity_thumbnail_url
water Water stress metrics precipitation_pet_ratio, soil_moisture_percentile, evapotranspiration_anomaly, water_stress_index, annual_water_stress

Response Format

The endpoint returns a streaming NDJSON response (one GeoJSON Feature per line). Each feature represents a single supply shed with its associated statistics.

Important: This endpoint does not support aggregation. It always returns individual supply shed features in streaming NDJSON format. To aggregate results, process the streamed features client-side.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    // Core/Common Fields (always present)
    "collection_id": "0x1234567890abcdef1234567890abcdef12345678", // (1)!
    "collection_name": "PT Hindoli, Cargill - Facility A", // (2)!
    "uuid": "c0db3327-755f-4078-bb9d-237f76df4aa7", // (3)!
    "stat_type": "supply_shed", // (4)!
    "facility_id": "f881a77f-17f4-5da3-9870-e7730938a6bf", // (5)!
    "facility_name": "Facility A", // (6)!
    "facility_address": "94QG+2QM, Lilin River, Sungai Lilin, Musi Banyuasin Regency, South Sumatra 30755, Indonesia", // (7)!
    "facility_certainty": "high", // (8)!
    "company_name": "PT Hindoli, Cargill", // (9)!
    "country": "Indonesia", // (10)!
    "admin1": "South Sumatra", // (11)!
    "centroid": {"long": 103.5, "lat": -2.5}, // (12)!
    "travel_time_min": 120.0, // (13)!
    "commodity": "palm", // (14)!
    "area_ha_supply_shed": 714221.50106, // (15)!
    "area_ha_commodity": 247311.234483, // (16)!
    "area_ha_smallholder": 150000.0, // (17)!
    "area_ha_estate": 97311.234483, // (18)!
    "area_ha_forest": 247401.421206, // (19)!
    "commodity_plot_no": 8748, // (20)!
    "monitoring_start": "2020-12-31", // (21)!
    "monitoring_end": "2025-03-07", // (22)!
    "ingestion_date": "2025-03-07", // (23)!
    "facility_geo": "POINT(103.5 -2.5)", // (24)!
    "locations_confidence": "high", // (25)!
    "metadata": {"custom_field": "value"}, // (26)!
    "legality_risk": "low", // (27)!

    // EUDR Deforestation Fields (if stats includes 'eudr_deforestation')
    "noncompliance_area_ha": 19.095381, // (28)!
    "noncompliance_area_perc": 0.19925, // (29)!
    "noncompliance_area_rate": 0.047695, // (30)!
    "noncompliance_plot_count": 14, // (31)!
    "annual_defor_ha": {
      "defor_ha_2021": 3.91295, 
      "defor_ha_2022": 0.535831, 
      "defor_ha_2023": 6.07428
    }, // (32)!
    "deforestation_thumbnail_url": "https://epoch-sco2-api.com/deforestation_thumbnail/...", // (33)!

    // LUC Emissions Fields (if stats includes 'luc_emissions')
    "luc_tco2eyear": -125.4, // (34)!
    "luc_tco2ehayear": -0.175, // (35)!
    "nonluc_tco2eyear": 45.2, // (36)!
    "nonluc_tco2ehayear": 0.18, // (37)!
    "biogenic_tco2eyear": 12.5, // (38)!
    "biogenic_tco2ehayear": 0.05, // (39)!
    "removal_tco2eyear": -30.5, // (40)!
    "removal_tco2ehayear": -0.12, // (41)!
    "soc_tco2eyear": -15.3, // (42)!
    "soc_tco2ehayear": -0.06, // (43)!
    "total_tco2eyear": -125.0, // (44)!
    "total_tco2ehayear": -0.51, // (45)!
    "intensity_ratio_tco2et": 0.85, // (46)!
    "annual_agb_tco2eha": {"2021": -10.5, "2022": -11.2, "2023": -12.1}, // (47)!
    "annual_bgb_tco2eha": {"2021": -2.5, "2022": -2.6, "2023": -2.8}, // (48)!
    "annual_soc_tco2eha": {"2021": -0.05, "2022": -0.06, "2023": -0.07}, // (49)!
    "emissions_thumbnail_url": "https://epoch-sco2-api.com/emissions_thumbnail/...", // (50)!

    // Biodiversity Fields (if stats includes 'biodiversity')
    "diversity_score": 0.65, // (51)!
    "annual_chm_m": {"2021": 15.2, "2022": 15.5, "2023": 15.8}, // (52)!
    "diversity_thumbnail_url": "https://epoch-sco2-api.com/diversity_thumbnail/...", // (53)!

    // Water Stress Fields (if stats includes 'water')
    "precipitation_pet_ratio": 1.2, // (54)!
    "soil_moisture_percentile": 65.5, // (55)!
    "evapotranspiration_anomaly": 0.15, // (56)!
    "water_stress_index": 0.45, // (57)!
    "annual_water_stress": {"2021": 0.45, "2022": 0.42, "2023": 0.48}, // (58)!

    // DDS Fields (EUDR submission related)
    "dds_reference_number": "REF123456", // (59)!
    "dds_verification_number": "VER789012", // (60)!
    "dds_submission_date": "2025-01-15", // (61)!
    "dds_uuid": "dds-uuid-12345" // (62)!
  }
}
  1. Collection identifier (hash)
  2. Collection name
  3. Unique identifier for the supply shed
  4. Type of statistical region (supply_shed, watershed, admin_area)
  5. Unique identifier of the processing facility
  6. Name of the facility
  7. Physical address of the facility
  8. Certainty level of facility location (high, medium, low)
  9. Name of the company operating the facility
  10. Country name
  11. Administrative level 1 (state/province)
  12. Centroid coordinates as JSON object with long and lat keys
  13. Travel time in minutes to supply shed edge
  14. Commodity type (palm, coffee, timber, rubber, cocoa, soy, cattle)
  15. Total supply shed area in hectares
  16. Commodity growing area in hectares
  17. Smallholder commodity area in hectares
  18. Estate commodity area in hectares
  19. Forested area in hectares
  20. Number of commodity plots
  21. Start of monitoring period (YYYY-MM-DD)
  22. End of monitoring period (YYYY-MM-DD)
  23. Date data was ingested (YYYY-MM-DD)
  24. Facility geometry as WKT string
  25. Confidence level of facility location (high, medium, low)
  26. Custom metadata from the original collection upload (JSON object)
  27. Legality risk assessment (low, medium, high)
  28. Total non-compliant area in hectares (EUDR deforestation)
  29. Percentage of forest area deforested (0.0 to 1.0)
  30. Annual deforestation rate
  31. Number of non-compliant plots
  32. JSON object containing annual deforestation by year (e.g., {"defor_ha_2021": 3.91, ...})
  33. URL to deforestation visualization thumbnail
  34. Total Land Use Change emissions in tCO2e/year
  35. LUC emissions per hectare in tCO2e/ha/year
  36. Total practices-based (non-LUC) emissions in tCO2e/year (calculated from emissions factors)
  37. Practices-based emissions per hectare in tCO2e/ha/year
  38. Total biogenic emissions in tCO2e/year (from batch processing tables)
  39. Biogenic emissions per hectare in tCO2e/ha/year
  40. Total carbon removal in tCO2e/year (negative value)
  41. Carbon removal per hectare in tCO2e/ha/year (negative value)
  42. Total soil organic carbon emissions in tCO2e/year
  43. SOC emissions per hectare in tCO2e/ha/year
  44. Total emissions in tCO2e/year (sum of LUC and non-LUC emissions, excluding biogenic)
  45. Total emissions per hectare in tCO2e/ha/year (sum of LUC and non-LUC emissions, excluding biogenic)
  46. Intensity ratio (tCO2e per ton of commodity)
  47. JSON object containing annual above-ground biomass emissions by year (tCO2e/ha)
  48. JSON object containing annual below-ground biomass emissions by year (tCO2e/ha)
  49. JSON object containing annual soil organic carbon emissions by year (tCO2e/ha)
  50. URL to emissions visualization thumbnail
  51. Biodiversity diversity score (0.0 to 1.0)
  52. JSON object containing annual canopy height model statistics by year (meters)
  53. URL to biodiversity visualization thumbnail
  54. Ratio of precipitation to potential evapotranspiration
  55. Soil moisture percentile (0-100)
  56. Evapotranspiration anomaly
  57. Water stress index (0.0 to 1.0, higher = more stress)
  58. JSON object containing annual water stress index by year
  59. EUDR Due Diligence Statement reference number
  60. EUDR DDS verification number
  61. EUDR DDS submission date (YYYY-MM-DD)
  62. EUDR DDS UUID

Note: The response is streamed as NDJSON (Newline Delimited JSON), meaning each line is a complete JSON object. Stat-specific fields (EUDR Deforestation, LUC Emissions, Biodiversity, Water Stress) are only included if the corresponding statistic is requested in the stats parameter.

Emissions Note: This endpoint returns both practices-based (nonluc_*) emissions (calculated from emissions factors) and biogenic (biogenic_*) emissions (from batch processing tables). The nonluc_* fields represent default practices-based emissions, while biogenic_* fields represent actual measured/modeled biogenic emissions from batch processing.

Total Emissions Calculation: The total_tco2eyear and total_tco2ehayear fields represent the sum of LUC emissions (luc_tco2eyear/luc_tco2ehayear) and practices-based non-LUC emissions (nonluc_tco2eyear/nonluc_tco2ehayear). Biogenic emissions (biogenic_*) are excluded from the total, as they represent measured/modeled emissions that are tracked separately.

Usage Examples

Python

import requests
import json

# Authentication
headers = {
    'Authorization': 'Bearer <your_token>'
}

# Fetch supply shed data for palm oil facilities
response = requests.get(
    "https://epoch-sco2-api.com/fetch_supply_shed",
    params={
        'commodity': 'palm',
        'stat_type': 'supply_shed',
        'stats': 'eudr_deforestation,luc_emissions,biodiversity,water',
        'monitoring_start': '2020-01-01',
        'monitoring_end': '2023-12-31',
        'limit': 50
    },
    headers=headers,
    stream=True
)

# Process streaming response
for line in response.iter_lines():
    if line:
        supply_shed = json.loads(line)
        props = supply_shed['properties']
        print(f"Facility: {props['company_name']}")
        print(f"  Non-compliance: {props['noncompliance_area_ha']} ha")
        print(f"  LUC Emissions: {props['luc_tco2eyear']} tCO2e/year")
        print(f"  Diversity Score: {props['diversity_score']}")

# Fetch all supply sheds (no limit)
response = requests.get(
    "https://epoch-sco2-api.com/fetch_supply_shed",
    params={
        'stat_type': 'all',
        'monitoring_start': '2020-01-01',
        'monitoring_end': '2023-12-31'
    },
    headers=headers,
    stream=True
)

# Process streaming response
total_noncompliance = 0.0
for line in response.iter_lines():
    if line:
        supply_shed = json.loads(line)
        props = supply_shed['properties']
        if 'noncompliance_area_ha' in props:
            total_noncompliance += props['noncompliance_area_ha']

print(f"Total non-compliant area: {total_noncompliance} ha")

JavaScript

const axios = require('axios');

const headers = {
  'Authorization': 'Bearer <your_token>'
};

// Fetch supply shed data
async function fetchSupplyShedData() {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_supply_shed',
      {
        params: {
          commodity: 'palm',
          stat_type: 'supply_shed',
          stats: 'eudr_deforestation,luc_emissions,biodiversity,water',
          monitoring_start: '2020-01-01',
          monitoring_end: '2023-12-31',
          limit: 25
        },
        headers,
        responseType: 'stream'
      }
    );

    response.data.on('data', (chunk) => {
      const lines = chunk.toString().split('\n');
      lines.forEach(line => {
        if (line.trim()) {
          const supplyShed = JSON.parse(line);
          const props = supplyShed.properties;
          console.log(`${props.company_name}: ${props.noncompliance_area_ha} ha non-compliant`);
        }
      });
    });

  } catch (error) {
    console.error('Error fetching supply shed data:', error);
  }
}

// Fetch data for specific facility
async function fetchFacilityData(facilityId) {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_supply_shed',
      {
        params: {
          facility_id: facilityId,
          stats: 'eudr_deforestation,luc_emissions,biodiversity,water'
        },
        headers
      }
    );

    console.log('Facility data:', response.data);
  } catch (error) {
    console.error('Error fetching facility data:', error);
  }
}

cURL

# Fetch supply shed data for palm oil
curl -X GET "https://epoch-sco2-api.com/fetch_supply_shed" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "commodity=palm" \
  -d "stat_type=supply_shed" \
  -d "stats=eudr_deforestation,luc_emissions,biodiversity,water" \
  -d "monitoring_start=2020-01-01" \
  -d "monitoring_end=2023-12-31" \
  -d "limit=25"

# Fetch data for specific facility
curl -X GET "https://epoch-sco2-api.com/fetch_supply_shed" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "facility_id=f881a77f-17f4-5da3-9870-e7730938a6bf" \
  -d "stats=eudr_deforestation,luc_emissions,biodiversity,water"

# Fetch all supply sheds (no limit, returns all matching records)
curl -X GET "https://epoch-sco2-api.com/fetch_supply_shed" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "stat_type=all" \
  -d "monitoring_start=2020-01-01" \
  -d "monitoring_end=2023-12-31" \
  --no-buffer

# Fetch watershed data instead of supply sheds
curl -X GET "https://epoch-sco2-api.com/fetch_supply_shed" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "stat_type=watershed" \
  -d "stats=eudr_deforestation,luc_emissions,biodiversity,water"

Response Fields

Core Supply Shed Information

Field Type Description
uuid string Unique identifier for the supply shed
collection_id string Collection identifier (hash)
collection_name string Collection name
stat_type string Type of statistical region (supply_shed, watershed, admin_area)
facility_id string Unique identifier of the processing facility
facility_name string Name of the facility
facility_address string Physical address of the facility
facility_certainty string Certainty level (high, medium, low)
company_name string Name of the company operating the facility
country string Country name
admin1 string Administrative level 1 (state/province)
centroid object Centroid coordinates {"long": float, "lat": float}
travel_time_min float Travel time in minutes to supply shed edge
commodity string Commodity type (palm, coffee, timber, rubber, cocoa)

Area Measurements

Field Type Description
area_ha_supply_shed float Total supply shed area in hectares
area_ha_commodity float Commodity growing area in hectares
area_ha_smallholder float Smallholder commodity area in hectares
area_ha_estate float Estate commodity area in hectares
area_ha_forest float Forested area in hectares
commodity_plot_no integer Number of commodity plots

Temporal Information

Field Type Description
monitoring_start string Start of monitoring period (YYYY-MM-DD)
monitoring_end string End of monitoring period (YYYY-MM-DD)
ingestion_date string Date data was ingested (YYYY-MM-DD)

EUDR Deforestation Metrics

Field Type Description
noncompliance_area_ha float Total non-compliant area in hectares
noncompliance_area_perc float Percentage of forest area deforested
noncompliance_area_rate float Annual deforestation rate
noncompliance_plot_count integer Number of non-compliant plots
annual_defor_ha object Annual deforestation by year (e.g., {"defor_ha_2021": 3.91, ...})
deforestation_thumbnail_url string URL to deforestation visualization thumbnail
emissions_thumbnail_url string URL to emissions visualization thumbnail (if available)
diversity_thumbnail_url string URL to biodiversity visualization thumbnail (if available)

LUC Emissions

Field Type Description
luc_tco2eyear float Total LUC emissions in tCO2e/year
luc_tco2ehayear float LUC emissions per hectare in tCO2e/ha/year
nonluc_tco2eyear float Total practices-based (non-LUC) emissions in tCO2e/year (calculated from emissions factors)
nonluc_tco2ehayear float Practices-based emissions per hectare in tCO2e/ha/year
biogenic_tco2eyear float Total biogenic emissions in tCO2e/year (from batch processing tables)
biogenic_tco2ehayear float Biogenic emissions per hectare in tCO2e/ha/year
removal_tco2eyear float Total carbon removal in tCO2e/year (negative value)
removal_tco2ehayear float Carbon removal per hectare in tCO2e/ha/year (negative value)
soc_tco2eyear float Total soil organic carbon emissions in tCO2e/year
soc_tco2ehayear float SOC emissions per hectare in tCO2e/ha/year
total_tco2eyear float Total emissions in tCO2e/year (sum of LUC and non-LUC emissions, excluding biogenic)
total_tco2ehayear float Total emissions per hectare in tCO2e/ha/year (sum of LUC and non-LUC emissions, excluding biogenic)
intensity_ratio_tco2et float Intensity ratio (tCO2e per ton of commodity)
annual_agb_tco2eha object Annual above-ground biomass emissions by year (tCO2e/ha)
annual_bgb_tco2eha object Annual below-ground biomass emissions by year (tCO2e/ha)
annual_soc_tco2eha object Annual soil organic carbon emissions by year (tCO2e/ha)
emissions_thumbnail_url string URL to emissions visualization thumbnail

Biodiversity

Field Type Description
diversity_score float Biodiversity diversity score (0.0 to 1.0)
annual_chm_m object Annual canopy height model statistics by year (meters)
diversity_thumbnail_url string URL to biodiversity visualization thumbnail

Water Stress

Field Type Description
precipitation_pet_ratio float Ratio of precipitation to potential evapotranspiration
soil_moisture_percentile float Soil moisture percentile (0-100)
evapotranspiration_anomaly float Evapotranspiration anomaly
water_stress_index float Water stress index (0.0 to 1.0, higher = more stress)
annual_water_stress object Annual water stress index by year

Performance Considerations

Streaming Responses

  • All responses are streamed in NDJSON format
  • Use --no-buffer with cURL for real-time streaming
  • Process responses incrementally for large datasets

Caching

  • Results are cached for 4 hours
  • Schema information is cached for 8 hours
  • Table discovery is cached for 2 hours

Rate Limiting

  • Standard API rate limits apply
  • Large datasets may take time to process
  • Monitor response headers for progress indicators

Error Handling

Common Errors

{
  "detail": "No data found for the specified criteria",
  "status_code": 404
}

{
  "detail": "Invalid stat_type. Must be one of: supply_shed, watershed, admin_area, all",
  "status_code": 422
}

Error Codes

Code Description
400 Bad Request - Invalid parameters
403 Forbidden - Insufficient permissions
404 Not Found - No data found
422 Validation Error - Invalid parameter format
500 Internal Server Error - Processing error

Best Practices

  1. Use appropriate filters: Filter by commodity, facility_id, or company_name to reduce response size
  2. Choose relevant statistics: Only request needed statistics to improve performance
  3. Set reasonable limits: Use limit parameter to control response size
  4. Monitor temporal ranges: Use monitoring_start and monitoring_end to focus on relevant time periods
  5. Handle streaming: Process streaming responses incrementally for large datasets
  6. Cache results: Implement client-side caching for frequently accessed data