Deforestation Methodology

Both modes share the same response shape — only the values change. Every deforestation row carries an enhanced_deforestation flag so consumers can tell which methodology produced it.

The same JSON keys appear in both modes. The values shift:

The thumbnail PNG also differs: the red "forest change" overlay is GLAD ∪ TMF in Standard and GLAD ∪ TMF ∪ time-series in Enhanced. Green (natural forest) and blue (commodity) channels are unaffected by the methodology choice.

Worth stating plainly, because the names collide and the numbers are unrelated:

The roll-up is derived from per-plot verdicts, which are derived from the metric. So they move together, but they are not the same figure and neither is a substitute for the other. A dashboard that reports "deforestation" should say which one it means.

Two caveats on the roll-up's counts, both of which change numbers a customer may have recorded earlier:

• It counts the plots of current records only. A plot whose record a later upload replaced is excluded (EPO-2331). A count that fell after a re-upload usually means this, not lost data.
• It still double counts across entity generations for a small number of locations: one current record's location can own two generations of plots, and both are counted, until EPO-1899 lands the read-side lineage fix. So a roll-up total can exceed the plot count a caller counts by hand.

enhanced_deforestation lives inside the metric_options block on POST /ingestions/assets and PUT /ingestions/assets. It is a per-metric option: it can only be set when metrics includes "deforestation". The API rejects the request with a 400 otherwise. Default is false — omit metric_options to keep Standard.

Schema rule: metric_options.enhanced_deforestation requires metrics to include 'deforestation'. Sending it without that metric — or under the assessments block, where it lived in earlier drafts — returns a VALIDATION_ERROR.

POST /ingestions/assets
Content-Type: application/json
x-api-key: <KEY>

{
  "location_type": "plot",
  "commodity_type": "palm",
  "metrics": ["deforestation"],
  "end_date": "2024-12-31",
  "assessments": {
    "include_core": true,
    "include_hazard": true
  }
}

curl -sS -X POST https://fm.epoch.blue/ingestions/assets \
  -H "x-api-key: $EPOCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "location_type": "plot",
    "commodity_type": "palm",
    "metrics": ["deforestation"],
    "end_date": "2024-12-31",
    "assessments": { "include_core": true, "include_hazard": true }
  }'

POST /ingestions/assets
Content-Type: application/json
x-api-key: <KEY>

{
  "location_type": "plot",
  "commodity_type": "palm",
  "metrics": ["deforestation"],
  "end_date": "2024-12-31",
  "assessments": {
    "include_core": true,
    "include_hazard": true
  },
  "metric_options": {
    "enhanced_deforestation": true
  }
}

curl -sS -X POST https://fm.epoch.blue/ingestions/assets \
  -H "x-api-key: $EPOCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "location_type": "plot",
    "commodity_type": "palm",
    "metrics": ["deforestation"],
    "end_date": "2024-12-31",
    "assessments": { "include_core": true, "include_hazard": true },
    "metric_options": { "enhanced_deforestation": true }
  }'

PUT /ingestions/assets?filter[tags]=eq:batch-q1
Content-Type: application/json
x-api-key: <KEY>

{
  "metrics": ["deforestation"],
  "assessments": { "include_core": true, "include_hazard": true },
  "metric_options": { "enhanced_deforestation": true }
}

curl -sS -X PUT 'https://fm.epoch.blue/ingestions/assets?filter[tags]=eq:batch-q1' \
  -H "x-api-key: $EPOCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "metrics": ["deforestation"],
    "assessments": { "include_core": true, "include_hazard": true },
    "metric_options": { "enhanced_deforestation": true }
  }'

curl -sS -X POST https://fm.epoch.blue/ingestions/assets \
  -H "x-api-key: $EPOCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "location_type": "plot",
    "commodity_type": "palm",
    "metrics": ["biodiversity"],
    "metric_options": { "enhanced_deforestation": true }
  }'

{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "title": "metric_options.enhanced_deforestation requires `metrics` to include 'deforestation'"
    }
  ]
}

curl -sS /metrics/plots/deforestation \
  -H "x-api-key: $EPOCH_API_KEY"

{
  "data": [
    {
      "id": "8a1b…",
      "type": "deforestation",
      "attributes": {
        "noncompliance_area": 0.12,
        "uncertainty_rrmse": 0,
        "deforestation_alert": "non-critical",
        "deforestation_confidence": "low",
        "is_compliant": true,
        "enhanced_deforestation": false
      }
    }
  ]
}

# Only Enhanced rows
curl -sS '/metrics/plots/deforestation?filter[enhanced_deforestation]=eq:true' \
  -H "x-api-key: $EPOCH_API_KEY"

# Only Standard rows
curl -sS '/metrics/plots/deforestation?filter[enhanced_deforestation]=eq:false' \
  -H "x-api-key: $EPOCH_API_KEY"

curl -sS '/metrics/facilities/deforestation?filter[enhanced_deforestation]=eq:true' \
  -H "x-api-key: $EPOCH_API_KEY"

Every plot, shed, and facility deforestation response carries enhanced_deforestation: boolean. The flag is filterable (?filter[enhanced_deforestation]=eq:true|false) on every list endpoint.

Aggregate rows (shed, facility) inherit the value from their constituent plots: true if any underlying plot was processed with Enhanced. Within a single ingestion task, all plots share one methodology, so an aggregate is uniform. Across multiple tasks, callers should filter by enhanced_deforestation before aggregating to avoid mixing methodologies.

Standard is the right default for:

• High-volume initial scans where you only need to flag known deforestation events.
• Cost-sensitive recurring monitoring on stable supply bases.
• Exploratory due diligence before committing to an EUDR submission.

Enhanced is the right call for:

• EUDR-critical due diligence (DDS submission, audit response).
• Any workflow where false negatives — missing real deforestation — would be unacceptable.
• Plots in regions where sub-canopy / progressive deforestation is common and GLAD/TMF alone tend to under-call.

You can re-process an existing task with the alternative methodology via PUT /ingestions/assets (see above). Existing rows keep their original methodology — enhanced_deforestation does not change retroactively.

A 12 ha cocoa plot in Côte d'Ivoire, monitored against the EUDR cut-off (monitoring_start = 2020-12-31, end_date = 2024-12-31):

Enhanced surfaces an additional 0.43 ha of progressive change in 2023 that GLAD and TMF didn't flag. That pushes noncompliance_area over the EUDR 0.5 ha de minimis, which flips is_compliant and lifts both deforestation_alert and deforestation_confidence.

Note: is_compliant is true/false only when the row's monitoring_start falls within ±14 days of the EUDR cut-off (2020-12-31). Outside that window it is null — uploads with an explicit user start_date far from the cut-off produce a second, user-period row whose is_compliant is undefined. See Metric Methodology — How is_compliant is computed for the full rules.

• Enhanced is slower and more compute-intensive. Expect longer task durations and higher processing cost. Reserve for plots that warrant the extra sensitivity.
• Don't mix methodologies in a single aggregation. When comparing or aggregating across tasks, filter by enhanced_deforestation first. The shed and facility roll-ups within one task are already uniform.
• Backfilled historical rows are flagged enhanced_deforestation = false. Data ingested before this feature shipped was processed with Standard. If you need Enhanced values for historical data, re-ingest the task with enhanced_deforestation: true.
• uncertainty_rrmse = 0 is informational, not "perfect confidence". Standard simply doesn't compute the time-series RMSE — it's not that the prediction is certain.
• The toggle only affects deforestation metrics. Biodiversity, emissions, water and other metrics are unaffected.