Location Types

A location is one physical place the API monitors: a mill, a sourcing area, or a farm. Each location has a stable location_id across processing runs. Matching also considers the location's type and commodity, so two commodities at the same site can have separate locations.

There are three location types. They form one hierarchy:

  • Facility โ€” a processing or collection point, such as a mill, silo, warehouse or port. You give its position as a point or an address; a mapped facility footprint can also be used.
  • Shed (supply shed) โ€” a sourcing area. Epoch computes it as a travel-time isochrone around a facility, you supply the polygon, or the API creates it to group uploaded plots.
  • Plot โ€” one field or farm where the commodity grows.

Every plot belongs to one shed. A shed belongs to at most one facility.


How each upload builds the hierarchy

You choose the type with location_type on POST /ingestions/assets (see Asset Upload). The table shows the usual paths. Validation can reroute rows based on their geometry and identity; the exceptions are explained below.

Usual upload paths: facilities produce travel-time sheds and Epoch-detected plots; declared shed polygons produce sheds and Epoch-detected plots; plot uploads group the supplied plots under a shed. Facility metrics summarise plots. Shed metrics combine area measurements with plot summaries. Validation can reroute rows; see the notes below.
Facility uploadShed uploadPlot upload
You sendA point, address or facility footprint per rowYour sourcing-area polygon per rowA polygon or a point per row
The API createsThe facility, a supply shed around it, and the plots inside the shedThe shed, and the plots inside itYour plots, grouped under a shed
FacilityYesNoNo, unless site or address rows are split into a facility run
Shed geometryTravel-time isochrone from the facility, using the commodity's default travel time (Supply Sheds)Your polygonCreated by the API to group the upload
Plots assessedDetected by Epoch's commodity modelsDetected by Epoch's commodity modelsThe plots in your file
Answers the question"What is the risk in this facility's sourcing area?""What is the risk in this area?""What is the risk on these specific farms?"

Routing and derived boundaries

  • Facility and shed uploads assess modelled plots: places where Epoch's models predict the commodity grows. They are not your suppliers' registered plots. Upload plots when you know the actual farms.
  • Declared sheds and automatic catchments differ. A declared shed uses your polygon as the sourcing area. Automatic classification can identify catchment-like geometries; review the detected type before processing.
  • A shed file containing only points is processed as a facility upload. A shed file mixing points and polygons is rejected; separate those inputs.
  • Site and address rows in a mixed plot upload can be split into a sibling facility run. Inspect the returned task and routing results rather than assuming every row keeps the requested type. See File Profiling.
  • A point plot needs an area for assessment. Where available and permitted, the API first tries a cadastral parcel outline, then a forest-segmented outline. Points left unresolved within the lookup and segmentation budget use a square of the declared area, or 4 ha when no area is given. A derived outline is not a surveyed farm boundary. See Location Validation.

How metrics differ by type

All four metric categories โ€” deforestation, emissions, biodiversity and water_stress โ€” have routes at all three levels. The level is part of the path, because each level returns different fields:

GET /metrics/facilities/{metric}
GET /metrics/sheds/{metric}
GET /metrics/plots/{metric}
LevelHow to read the resultExample deforestation fields
PlotMeasurements and assessment for each plotplot_assessment, assessment_driver, assessment_method, plot_resolution, protected_area_overlap_ha
ShedArea measurements, plus summaries of its plotsplot_count, noncompliance_plot_count, exempt_plot_count, pending_plot_count
FacilitySummary of the plots under the facilitycompliant_plot_count, noncompliance_plot_count, exempt_plot_count, noncompliance_area_perc

These are examples, not fields exclusive to each level. Latest shed and facility deforestation results use decision-aware plot summaries when available: operator exclusions and verdict decisions can change the counts and loss figures. Historical rows retain the processing run's aggregate results, so they need not match the current summary. See Metric Methodology for fields, methods and units.

The /locations compliance filter distinguishes five statuses: non_compliant, pending, not_assessed, compliant and excluded. A facility or shed can be compliant when all its included plots are assessed as compliant and at least one remains included. Excluded plots do not prevent that result; an all-excluded location is excluded. Pending review and missing assessments remain distinct from a compliant result. See Locations โ†’ Filtering by compliance for the order in which the statuses are evaluated.


The diagram above shows the hierarchy. The API exposes it in these ways:

  • Parent fields. Each plot carries parent_shed_location_id and parent_facility_location_id. Each shed carries parent_facility_location_id. The value is null when that parent does not exist, for example the facility of an uploaded plot.
  • Drill down. Pass a location ID as filter[location_id]=eq:<location_id> on a metric route. The API returns that location and its descendants at the route's level. For example, a facility's location_id on /metrics/plots/deforestation returns the plots under that facility.
  • Collection. Each upload is a collection, identified by asset_task_id. A metric row carries an asset_task_id linking it to a collection. See Locations โ†’ Reaching the collection for the selection and null rules.
  • Supplier. A location can link to a supplier. See Suppliers.
  • Organisation. Locations are associated with your organisation. A parent organisation also sees the locations of its child organisations.

For the field reference, see Locations.


Which type to upload

  • You know the mills, but not the farms. Upload facilities. The API estimates the sourcing area and assesses the commodity plots in it.
  • You know the sourcing region, but not a facility. Upload sheds with your sourcing-area polygons.
  • You know the farms. Upload plots. The API assesses the farms you supply, deriving an assessment footprint where you have only a point.