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_rmse_2021": 0.0,
      "defor_ha_2022": 0.0,
      "defor_ha_rmse_2022": 0.0,
      "defor_ha_2023": 0.0,
      "defor_ha_rmse_2023": 0.0,
      "defor_ha_2024": 0.0,
      "defor_ha_rmse_2024": 0.0,
      "defor_ha_2025": 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 object 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) - keys are interleaved by 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": "high", // (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_rmse_2021": 0,
      "defor_ha_2022": 18.16032,
      "defor_ha_rmse_2022": 2.90354,
      "defor_ha_2023": 3.28448,
      "defor_ha_rmse_2023": 0,
      "defor_ha_2024": 3.56976,
      "defor_ha_rmse_2024": 0,
      "defor_ha_2025": 0.159,
      "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. locations_confidence — see locations_confidence below
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. JSON object containing 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) - keys are interleaved by 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 {})

locations_confidence

The locations_confidence property (and the same field in stat_supply_shed) indicates the confidence level for the collection’s location data. It is not computed by this endpoint: it comes from the validation assessment stored when the collection was validated (e.g. via validate_facilities or validate_locations with batch supply shed), or from a skip reason when processing did not run.

Status codes — Only the following values are used; no custom or free-form messages are returned.

Value	Meaning
high	Collection-level validation result: high confidence (score ≥ 0.7).
medium	Collection-level validation result: medium confidence (score ≥ 0.45, < 0.7).
low	Collection-level validation result: low confidence (score < 0.45 or failed checks). Processing may have run or been skipped depending on skip_on_low_confidence.
invalid	Validation set this for invalid/empty geometry (e.g. all facilities invalid).
not processed: validation confidence too low	Processing skipped because validation confidence was low. Used for all low-confidence skips (no free-form reason; e.g. latitude/commodity comments are not passed through).
not processed: geocoding failed	Geocoding failed or all facilities were ungeocoded; processing skipped.
not processed: geocoding too imprecise	Geocoding succeeded but the result was too imprecise; processing skipped.

For how validation produces this assessment and how it is stored and exposed, see Facility validation.

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 objects
• 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)