Shed Ingestion

End-to-end workflow for ingesting supply shed (sourcing area) locations, processing environmental metrics, and visualizing results. A supply shed represents a broader sourcing region that contains many plots and optionally a single facility. The shed polygon defines the geographic extent of a sourcing area, while the plots within it represent the individual farm-level land parcels.

The workflow is split into two asynchronous phases — a validate-only upload, then an explicit metrics-processing trigger — because the two do very different amounts of work. Uploading only checks the geometries, so it returns quickly; metrics processing sends the shed boundaries to the sco2 API, which generates the plots inside each shed and computes the requested metrics, which is far slower. Keeping them separate lets you inspect and correct the validated sheds before committing to the expensive processing step.

Use cases

  • Sourcing area mapping — upload shed boundaries to define the geographic extent of your supply regions
  • Regional risk assessment — compute deforestation and emissions metrics at the shed level for portfolio-wide analysis
  • Supplier onboarding — ingest shed data provided by suppliers to establish sourcing area baselines
  • Aggregate reporting — generate summary metrics across entire sourcing regions rather than individual plots

Step overview

  1. Upload a file containing shed location data via POST /ingestions/assets
  2. Poll GET /ingestions/:id/summary until validation completes (overall_status is staged)
  3. Review validated shed entities via GET /ingestions/assets/:id
  4. Trigger metric processing via PUT /ingestions/assets with desired metrics
  5. Poll GET /ingestions/:id/summary until processing completes
  6. Retrieve processed sheds and metrics via the locations and metrics endpoints
  7. Visualize shed polygons and risk scores on a map

Workflow diagram

Upload Shed ──→ Check Validation ──→ Get Validated Assets
     │                                       │
     │              ┌────────────────────────┘
     ▼              ▼
Process With Stats ──→ Check Processing ──→ View Results

Prerequisites

  • Valid API key in the x-api-key header
  • A file containing shed location data (CSV, GeoJSON, or other supported format)