Each location has a location_type attribute indicating the underlying entity:

Use convenience routes to filter by type:

GET /locations/facilities
GET /locations/sheds
GET /locations/plots
GET /locations/commodity/palm

Location list and single-location responses can attach related payloads under a relationships object via the include query parameter (comma-separate to combine, e.g. ?include=assessment,deforestation):

GET /locations/facilities?include=deforestation
→ { "type": "location", "id": "...", "attributes": { ... },
    "relationships": {
      "deforestation": {
        "total_plots": 10, "compliant_plots": 7, "non_compliant_plots": 2,
        "unknown_plots": 1, "total_area_ha": 100.5, "compliant_area_ha": 70.25
      }
    } }

The deforestation block is the same roll-up returned on GET /ingestions/assets?include=deforestation, but read from a per-location cache and reflecting the latest figure across all tasks rather than a single asset-task. Facilities and sheds only for now — plot rows omit the block, and a location with no cached roll-up yet omits it too (rather than emitting all-zeros). Plot support will follow.

# Non-compliant facilities, with the roll-up attached
GET /locations/facilities?filter[compliance]=eq:non_compliant&include=deforestation

# Compliant sheds
GET /locations/sheds?filter[compliance]=eq:compliant

# High legality-risk facilities, with the assessment block attached
GET /locations/facilities?filter[legality_risk_level]=eq:high&include=assessment

# Facilities ranked worst-first by Article 10 country-risk
GET /locations/facilities?sort=-article10_risk_level

Metrics are namespaced by location type because each level returns different fields (facility metrics include aggregated summaries, plot metrics have per-plot detail).

GET /metrics/{location_type}/{metric}
GET /metrics/{location_type}/{metric}/latest
GET /metrics/{location_type}/{metric}/{commodity}
GET /metrics/{location_type}/{metric}/{commodity}/latest

GET /locations/:location_id/deforestation
GET /locations/:location_id/biodiversity
GET /locations/:location_id/emissions
GET /locations/:location_id/water_stress

# All plots' deforestation under a given facility
GET /metrics/plots/deforestation?filter[location_id]=eq:<facility_location_id>

# All sheds' deforestation under a given facility
GET /metrics/sheds/deforestation?filter[location_id]=eq:<facility_location_id>

# Latest deforestation for plots under a shed (singular-ID route)
GET /metrics/plots/<shed_location_id>/deforestation

Every location and metric resource carries its parents' location_ids, so you can group a mixed result set into its hierarchy client-side, from the response bodies alone — no follow-up request:

These are plain location_id values (null where not applicable — a facility has neither, a shed has only parent_facility_location_id). Match them to a parent's own location_id:

// GET /metrics/plots/deforestation
{ "attributes": {
    "location_id": "<plot location_id>",
    "parent_shed_location_id": "<shed location_id>",
    "parent_facility_location_id": "<facility location_id>"
} }

// Group plot metrics under a facility you already fetched
const plotsForFacility = plotMetrics.filter(
  (p) => p.attributes.parent_facility_location_id === facility.attributes.location_id,
);

Use whichever direction fits: drill-down (filter[location_id]) when you want the server to return a facility's descendants; parent_*_location_id when you've already pulled a set of plot/shed metrics and want to roll them up locally.

Each location and metric resource also exposes a tile_ids object with the stable identifier of the underlying entity. Only the field matching the resource's own type is populated:

// a plot resource / plot metric
"tile_ids": { "plot_id": "<id>", "supply_shed_id": null, "facility_id": null }

// a shed resource / shed metric
"tile_ids": { "plot_id": null, "supply_shed_id": "<id>", "facility_id": null }

// a facility resource / facility metric
"tile_ids": { "plot_id": null, "supply_shed_id": null, "facility_id": "<id>" }

These IDs match the feature properties on Epoch's plot vector tiles (PMTiles plot_id / supply_shed_id / facility_id). If you render that map layer, join a tile feature straight to its API resource:

// clicked map feature → its plot metric
feature.properties.plot_id === plotMetric.attributes.tile_ids.plot_id;

For callers that don't use the tiles, tile_ids is simply a stable per-entity identifier you can use as a join/dedup key across responses.

Every metric resource names its collection — the ingestion task whose upload produced the row:

"attributes": {
  "asset_task_id": "<task id>",          // the collection
  "parent_supply_shed_id": "<shed id>",  // plot rows: the parent shed's shed.id
  // ...
}

asset_task_id echoes filter[assets.task_id] when you supplied it, otherwise it is the most recent ingestion task for that location. It is null on the /history and streaming variants, and on a parent-id drill-down, where resolving it would mean an unbounded scan.

Use it to fetch the collection's data export:

GET /v1/artifacts?filter[assets.task_id]=eq:<asset_task_id>&filter[status]=eq:succeeded

Results are already newest-first. If none exists, POST /v1/artifacts with that same task scope filter generates one; pass an Idempotency-Key so concurrent callers share a single job. See Artifacts.

parent_supply_shed_id is the parent shed's shed.id, not a location_id — it is the value that joins to supply_shed_id on plot vector-tile features and to sheds.shed_id inside an artifact export. Use parent_shed_location_id when you instead want to join to the parent's own shed metric.

"links": {
  "self": "/metrics/deforestation",
  "dashboard": "https://platform.epoch.blue/artifact?task=<task>&shed=<shed>"
}

Locations are scoped to your organisation. Two organisations can monitor the same physical site independently — each sees only their own data. Parent organisations can see their children's data; use x-acting-as header or filter[organization_id] to narrow the scope.

All endpoints support four response formats via the Accept header:

Geometry is opt-in on JSON formats. application/json and application/x-ndjson omit the geo attribute by default — pass ?include_geometries=true to include it. The GeoJSON formats (application/geo+json, application/x-ndgeo+json) always carry geometry, so the flag isn't needed there. See Query Parameters → Geometry.