Skip to content

Fetch Deforestation Check

The /fetch_deforestation_check endpoint retrieves deforestation detection data for individual plots or aggregated statistics. This endpoint is designed for EUDR (European Union Deforestation Regulation) compliance monitoring and deforestation detection analysis.

Key EUDR Applications

Article 9 Compliance

The data returned by this endpoint directly supports EUDR Article 9 requirements for: - Deforestation-free production: Identifying areas where deforestation has occurred - Land use verification: Confirming the legality of land use changes - Supply chain transparency: Providing traceable plot-level data - Due diligence documentation: Supporting audit trail requirements

Risk Assessment Support

The deforestation data serves as input for EUDR Article 10 risk assessments, particularly for: - Prevalence of deforestation in production areas - Forest degradation analysis - Supply chain complexity evaluation - Circumvention risk assessment

Endpoint

GET /fetch_deforestation_check

Parameters

Parameter Type Required Default Description
filename string No None Collection identifier
monitoring_start string No "2020-12-31" Monitoring start date (YYYY-MM-DD)
monitoring_end string No None Monitoring end date (YYYY-MM-DD)
limit integer No None Number of plots to fetch. If not provided, returns by default up to 10000 plots for aggregate=False case, or returns the first matching case for aggregate=True case.
aggregate boolean No false Aggregate results into a single row
plots_only boolean No false Return plots only without statistics. When true, returns base collection data without any statistical calculations

Dynamic Filtering

You can filter results using any column name from the batch table as a query parameter:

# Filter by plot ID (returns first matching plot, limit=1)
/fetch_deforestation_check?plotid=12345

# Filter by collection ID
/fetch_deforestation_check?collection_id=abc123

# Filter by facility ID
/fetch_deforestation_check?facility_id=xyz789

# Filter by custom metadata fields (e.g., from batch uploads)
# Returns all matching rows across all matching collections (limit=10000)
/fetch_deforestation_check?clientid=ABC123
/fetch_deforestation_check?producerid=PROD456

# Combine multiple filters
/fetch_deforestation_check?collection_id=abc123&monitoring_start=2020-01-01
/fetch_deforestation_check?clientid=ABC123&plotid=12345

Note on limit behavior: - When filtering by custom metadata fields (like clientid, producerid, partid) that were provided during batch upload, the endpoint returns all matching rows across all matching collections (default limit=10000) - When filtering by fields from the uploaded file (like plotid, uuid, name), the endpoint returns the first matching row (default limit=1) - The filename parameter takes priority - if provided, it queries only that specific collection and ignores custom metadata collection lookup

Response Format

The endpoint returns streaming NDJSON (Newline Delimited JSON) responses. Each line is a complete GeoJSON (Geographic JSON) Feature.

Non-Aggregate Response (aggregate=false)

When aggregate=false (default), the endpoint returns individual plot features with deforestation detection data.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "uuid": "15bdfb54-e621-40cc-80ce-bb4704562b26", // (1)!
    "plotid": "ec166918-b7a2-47ac-bff4-010776a4a999", // (2)!
    "collection_id": "0x5413dd21974a6356416165ea35e2de07357e3c486934710aa71a6123b1273fcb", // (3)!
    "facility_id": null, // (4)!
    "area": 1.201948, // (5)!
    "forest_area": 1.170768, // (6)!
    "ingestion_date": "2025-11-18T13:38:23+00:00", // (7)!
    "monitoring_start": "2020-12-31T00:00:00+00:00", // (8)!
    "monitoring_end": "2025-12-31T00:00:00+00:00", // (9)!
    "noncompliance_area": 0.0, // (10)!
    "noncompliance_area_perc": 0.0, // (11)!
    "deforestation_start": "1970-01-01T00:00:00+00:00", // (12)!
    "deforestation_end": "1970-01-01T00:00:00+00:00", // (13)!
    "uncertainty_rrmse": 0.0, // (14)!
    "deforestation_confidence": "no detection", // (15)!
    "deforestation_alert": "no deforestation", // (16)!
    "agreement": { // (17)!
      "all": 0.0,
      "dynamic_world": 0.0,
      "glad": 0.0,
      "tmf": 0.0
    },
    "overlap": { // (18)!
      "jrc_forest": 0.0,
      "tmf_forest": 0.0,
      "natural_forest": 0.0,
      "wdpa": 0.0,
      "wdpa_mandate": 0.0,
      "palm": 0.0,
      "cocoa": 0.03118, // (19)!
      "rubber": 0.0,
      "coffee": 0.0,
      "soy": 0.0,
      "cattle": 0.0,
      "timber": 0.0
    },
    "annual_defor": { // (20)!
      "defor_ha_2021": 0.0,
      "defor_ha_2022": 0.0,
      "defor_ha_2023": 0.0,
      "defor_ha_2024": 0.0,
      "defor_ha_2025": 0.0,
      "defor_ha_rmse_2021": 0.0,
      "defor_ha_rmse_2022": 0.0,
      "defor_ha_rmse_2023": 0.0,
      "defor_ha_rmse_2024": 0.0,
      "defor_ha_rmse_2025": 0.0
    },
    "thumbnail_url": null, // (21)!
    "soliditysha3_256_hash": "0xceea120d0dbe8167f39fbe80465646e268d8f61c52625bdd537dfdfc89638f3a", // (22)!
    "metadata": { // (23)!
      "area": 1.18,
      "farmerCode": "SCH_BEO_AXE1_BON_BON_0030",
      "farmerId": "d6938606-158a-43d2-be0a-cb6c1eb998ef",
      "farmerName": "KOUADIO Adjoua ",
      "name": "KOUADIO Adjoua",
      "plotArea": 1.18,
      "plotCode": null,
      "plotId": "ec166918-b7a2-47ac-bff4-010776a4a999"
    }
  }
}
  1. Unique identifier for the plot
  2. Plot identifier from the original collection
  3. Collection identifier (hash)
  4. Facility identifier associated with the plot, or null if not applicable
  5. Plot area in hectares
  6. Forest area within the plot in hectares
  7. Date when the plot was ingested into the system (ISO 8601 timestamp)
  8. Start date of the monitoring period (ISO 8601 timestamp)
  9. End date of the monitoring period (ISO 8601 timestamp)
  10. Area of non-compliance (deforestation) in hectares
  11. Percentage of plot area that is non-compliant (0.0 to 1.0)
  12. Date when deforestation was first detected (YYYY-MM-DD format, or null if no deforestation)
  13. Date when deforestation detection period ended (YYYY-MM-DD format, or null if no deforestation)
  14. Relative RMSE (Root Mean Square Error) for deforestation detection uncertainty
  15. Confidence level of deforestation detection ("no detection", "low", "medium", "high")
  16. Alert level for deforestation ("no deforestation", "non-critical", "critical")
  17. JSON string containing agreement scores between different detection methods. When parsed, contains: all (overall agreement score 0.0-1.0), dynamic_world (agreement with Dynamic World dataset), glad (agreement with GLAD (Global Land Analysis & Discovery) alerts), tmf (agreement with TMF (Tropical Moist Forest) dataset)
  18. JSON string containing overlap information with third-party datasets. When parsed, contains overlap values for: jrc_forest (JRC (Joint Research Centre) forest datasets), tmf_forest (TMF (Tropical Moist Forest) forest datasets), natural_forest, wdpa (WDPA (World Database on Protected Areas)), wdpa_mandate (WDPA mandate areas).
  19. Commodity overlap areas in hectares (e.g. palm, cocoa, rubber, coffee, soy, cattle, timber). Only some keys may be non-zero depending on what’s present in the plot/region.
  20. JSON string containing annual deforestation statistics. When parsed, contains: defor_ha_YYYY (deforestation area for specific year in hectares), defor_ha_rmse_YYYY (RMSE (Root Mean Square Error) for deforestation area for specific year)
  21. URL to thumbnail image showing deforestation detection visualization, or null if not available
  22. SHA-256 hash identifier for the plot
  23. Custom metadata from the original collection upload. This object contains user-provided attributes that were included during batch processing. The structure varies by collection and may include fields like farmerName, plotCode, plotId, farmerId, or any other custom attributes provided during upload.

Aggregate Response (aggregate=true)

When aggregate=true, the endpoint returns a single feature with aggregated deforestation statistics across all matching plots.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "collection_id": "0x7e0669fd8b18aef64093431286f1b63920ca7a72d1c5ccadeb2e5d60f2a18ef3", // (1)!
    "collection_name": "scoops_houkabe_2025_11_13_1762781282666", // (2)!
    "uuid": "1100926160", // (3)!
    "stat_type": "watershed", // (4)!
    "facility_id": null, // (5)!
    "facility_name": null, // (6)!
    "facility_address": null, // (7)!
    "facility_certainty": null, // (8)!
    "company_name": null, // (9)!
    "country": "Ivory Coast", // (10)!
    "admin1": "Vallée du Bandama", // (11)!
    "centroid": { // (12)!
      "lat": 7.490705200935917,
      "long": -5.410874737455942
    },
    "travel_time_min": null, // (13)!
    "commodity": "Cocoa", // (14)!
    "area_ha_supply_shed": 150883.768929, // (15)!
    "area_ha_commodity": 1010.018455, // (16)!
    "area_ha_smallholder": 1010.018455, // (17)!
    "area_ha_estate": 0.0, // (18)!
    "area_ha_forest": 424.041879, // (19)!
    "commodity_plot_no": 586, // (20)!
    "monitoring_start": "2020-12-31T00:00:00+00:00", // (21)!
    "monitoring_end": "2025-12-31T00:00:00+00:00", // (22)!
    "ingestion_date": "2025-11-13T20:08:14+00:00", // (23)!
    "facility_geo": "POINT(-5.41087473745594 7.49070520093592)", // (24)!
    "locations_confidence": null, // (25)!
    "noncompliance_area_ha": 1.18919, // (26)!
    "noncompliance_area_perc": 0.001177, // (27)!
    "noncompliance_area_rate": 0.000236, // (28)!
    "noncompliance_plot_count": 3, // (29)!
    "annual_defor_ha": { // (30)!
      "defor_ha_2021": 5.00966,
      "defor_ha_2022": 18.16032,
      "defor_ha_2023": 3.28448,
      "defor_ha_2024": 3.56976,
      "defor_ha_2025": 0.159,
      "defor_ha_rmse_2021": 0,
      "defor_ha_rmse_2022": 2.90354,
      "defor_ha_rmse_2023": 0,
      "defor_ha_rmse_2024": 0,
      "defor_ha_rmse_2025": 0.77848
    },
    "deforestation_thumbnail_url": null, // (31)!
    "legality_risk": null, // (32)!
    "dds_reference_number": null, // (33)!
    "dds_verification_number": null, // (34)!
    "dds_submission_date": null, // (35)!
    "metadata": {} // (36)!
  }
}
  1. Collection identifier (hash)
  2. Human-readable collection name
  3. Unique identifier for the aggregated region
  4. Type of statistical region (e.g., "watershed", "admin_area", "supply_shed")
  5. Facility identifier, if applicable
  6. Facility name, if applicable
  7. Facility address, if applicable
  8. Confidence level for facility location
  9. Company name associated with the facility
  10. Country name
  11. Administrative level 1 (state/province) name
  12. Geographic centroid of the region: lat (latitude), long (longitude)
  13. Travel time to facility in minutes
  14. Commodity type (e.g., "Cocoa", "Palm", "Coffee")
  15. Total supply shed area in hectares
  16. Commodity production area in hectares
  17. Smallholder production area in hectares
  18. Estate production area in hectares
  19. Forest area in hectares
  20. Number of commodity plots
  21. Earliest monitoring start date (ISO 8601 timestamp)
  22. Latest monitoring end date (ISO 8601 timestamp)
  23. Most recent ingestion date (ISO 8601 timestamp)
  24. WKT (Well-Known Text) representation of facility location
  25. Confidence level for location data
  26. Total non-compliance area across all plots (hectares)
  27. Percentage of total area that is non-compliant
  28. Rate of non-compliance per year
  29. Number of plots with deforestation detected
  30. Aggregated annual deforestation statistics (summed across all plots). When parsed, contains: defor_ha_YYYY (deforestation area for specific year in hectares), defor_ha_rmse_YYYY (RMSE (Root Mean Square Error) for deforestation area for specific year)
  31. URL to thumbnail image showing aggregated deforestation visualization, or null if not available
  32. Legality risk assessment, if available
  33. DDS (Due Diligence Statement) reference number, if available
  34. DDS verification number, if available
  35. DDS submission date, if available
  36. Custom metadata from the original collection (may be empty object {})

Plots Only Response (plots_only=true)

When plots_only=true, the endpoint returns base collection data without deforestation statistics. This is useful when statistics haven't been computed yet or when you only need plot geometries and basic metadata.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "uuid": "15bdfb54-e621-40cc-80ce-bb4704562b26", // (1)!
    "plotid": "ec166918-b7a2-47ac-bff4-010776a4a999", // (2)!
    "ingestion_date": "2025-11-18T13:38:23+00:00", // (3)!
    "area": 1.201948, // (4)!
    "metadata": { // (5)!
      "area": 1.18,
      "farmerCode": "SCH_BEO_AXE1_BON_BON_0030",
      "farmerId": "d6938606-158a-43d2-be0a-cb6c1eb998ef",
      "farmerName": "KOUADIO Adjoua ",
      "name": "KOUADIO Adjoua",
      "plotArea": 1.18,
      "plotCode": null,
      "plotId": "ec166918-b7a2-47ac-bff4-010776a4a999"
    }
  }
}
  1. Unique identifier for the plot
  2. Plot identifier from the original collection
  3. Date when the plot was ingested into the system (ISO 8601 timestamp)
  4. Plot area in hectares
  5. Custom metadata from the original collection upload. This object contains user-provided attributes that were included during batch processing. The structure varies by collection and may include fields like farmerName, plotCode, plotId, farmerId, or any other custom attributes provided during upload. Note: No deforestation detection fields are included when plots_only=true.

Usage Examples

Python Example

import requests
import json

headers = {
    "Authorization": "Bearer <your_token>"
}

# Fetch individual plots with deforestation data
response = requests.get(
    "https://epoch-sco2-api.com/fetch_deforestation_check",
    params={
        "filename": "your_collection_name",
        "monitoring_start": "2020-12-31",
        "monitoring_end": "2024-01-10",
        "limit": 100
    },
    headers=headers,
    stream=True
)

for line in response.iter_lines():
    if line:
        feature = json.loads(line)
        props = feature["properties"]
        print(f"Plot {props['uuid']}: "
              f"Non-compliance area: {props['noncompliance_area']} ha, "
              f"Confidence: {props['deforestation_confidence']}")

# Fetch aggregated deforestation statistics
response = requests.get(
    "https://epoch-sco2-api.com/fetch_deforestation_check",
    params={
        "filename": "your_collection_name",
        "monitoring_start": "2020-12-31",
        "monitoring_end": "2024-01-10",
        "aggregate": True
    },
    headers=headers
)

aggregated_data = json.loads(response.text)
props = aggregated_data["properties"]
print(f"Total plots: {props['aggregate_plot_count']}")
print(f"Total non-compliance area: {props['noncompliance_area']} ha")
print(f"Non-compliance plots: {props['noncompliance_plot_count']}")

JavaScript Example

const axios = require('axios');

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

// Fetch deforestation data for specific plot
async function fetchDeforestationData() {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_deforestation_check',
      {
        params: {
          filename: 'your_collection_name',
          plotid: '12345',
          monitoring_start: '2020-12-31',
          monitoring_end: '2024-01-10'
        },
        headers,
        responseType: 'stream'
      }
    );

    response.data.on('data', (chunk) => {
      const lines = chunk.toString().split('\n');
      lines.forEach(line => {
        if (line.trim()) {
          const feature = JSON.parse(line);
          const props = feature.properties;
          console.log(`Plot ${props.uuid}: Non-compliance area: ${props.noncompliance_area} ha`);
        }
      });
    });
  } catch (error) {
    console.error('Error fetching deforestation data:', error);
  }
}

// Fetch aggregated deforestation statistics
async function fetchAggregatedDeforestation() {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_deforestation_check',
      {
        params: {
          filename: 'your_collection_name',
          monitoring_start: '2020-12-31',
          monitoring_end: '2024-01-10',
          aggregate: true
        },
        headers
      }
    );

    const aggregatedData = response.data;
    console.log(`Total plots: ${aggregatedData.properties.aggregate_plot_count}`);
    console.log(`Total non-compliance area: ${aggregatedData.properties.noncompliance_area} ha`);
  } catch (error) {
    console.error('Error fetching aggregated deforestation data:', error);
  }
}

cURL Example

# Fetch deforestation data for specific plot
curl -X GET "https://epoch-sco2-api.com/fetch_deforestation_check" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "plotid=12345" \
  -d "monitoring_start=2020-12-31" \
  -d "monitoring_end=2024-01-10"

# Fetch aggregated deforestation statistics
curl -X GET "https://epoch-sco2-api.com/fetch_deforestation_check" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "monitoring_start=2020-12-31" \
  -d "monitoring_end=2024-01-10" \
  -d "aggregate=true"

Notes

  • All responses are streamed in NDJSON (Newline Delimited JSON) format
  • JSON fields (agreement, overlap, annual_defor) are returned as JSON strings and need to be parsed
  • The deforestation_confidence and deforestation_alert fields are computed based on agreement scores, overlap with protected areas, and commodity presence (see Deforestation Check documentation for detailed risk matrix)
  • When aggregate=true, the limit parameter defaults to 1 (returns first matching case)
  • When aggregate=false and no specific filters are provided, the limit parameter defaults to 10000
  • Acronyms: EUDR (European Union Deforestation Regulation), GLAD (Global Land Analysis & Discovery), TMF (Tropical Moist Forest), JRC (Joint Research Centre), WDPA (World Database on Protected Areas), DDS (Due Diligence Statement), RMSE (Root Mean Square Error), WKT (Well-Known Text), ISO 8601 (International Organization for Standardization)