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.
| Facility upload | Shed upload | Plot upload | |
|---|---|---|---|
| You send | A point, address or facility footprint per row | Your sourcing-area polygon per row | A polygon or a point per row |
| The API creates | The facility, a supply shed around it, and the plots inside the shed | The shed, and the plots inside it | Your plots, grouped under a shed |
| Facility | Yes | No | No, unless site or address rows are split into a facility run |
| Shed geometry | Travel-time isochrone from the facility, using the commodity's default travel time (Supply Sheds) | Your polygon | Created by the API to group the upload |
| Plots assessed | Detected by Epoch's commodity models | Detected by Epoch's commodity models | The 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}
| Level | How to read the result | Example deforestation fields |
|---|---|---|
| Plot | Measurements and assessment for each plot | plot_assessment, assessment_driver, assessment_method, plot_resolution, protected_area_overlap_ha |
| Shed | Area measurements, plus summaries of its plots | plot_count, noncompliance_plot_count, exempt_plot_count, pending_plot_count |
| Facility | Summary of the plots under the facility | compliant_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.
โถHow locations link together
The diagram above shows the hierarchy. The API exposes it in these ways:
- Parent fields. Each plot carries
parent_shed_location_idandparent_facility_location_id. Each shed carriesparent_facility_location_id. The value isnullwhen 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'slocation_idon/metrics/plots/deforestationreturns the plots under that facility. - Collection. Each upload is a collection, identified by
asset_task_id. A metric row carries anasset_task_idlinking 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.