List Locations
List all locations for your organization.
Returns a paginated list of locations visible to your organization. Each location represents a single physical site (facility, supply shed, or plot) and is identified by a stable location_id that persists across processing runs.
โถUse Cases
- Browse all monitored sites in your supply chain with a single request.
- Filter by entity type (
facility,shed,plot) without tracking multiple internal IDs. - Use
facility_id,shed_id, orplot_idbridge filters to look up a location by its underlying entity ID.
โถConvenience routes
Pre-filtered sub-paths that are equivalent to using filter[location_type]:
| Path | Equivalent |
|---|---|
GET /locations/facilities | filter[location_type]=eq:facility |
GET /locations/sheds | filter[location_type]=eq:shed |
GET /locations/plots | filter[location_type]=eq:plot |
GET /locations/commodity/:commodity | filter[commodity]=eq::commodity |
โถFilters
Use filter[field]=condition:value syntax. See Query Parameters for details.
| Filter | Type | Description |
|---|---|---|
filter[location_type] | enum | facility, shed, or plot |
filter[commodity] | enum | Commodity type (palm, cocoa, coffee, etc.) |
filter[country_code] | iso-country | ISO 3166-1 alpha-2 |
filter[name] | string | Location name (supports eq, contains, startsWith) |
filter[organization_id] | uuid | Narrow to a specific child org |
filter[facility_id] | string | Facility ID (text) bridge filter |
filter[shed_id] | uuid | Shed UUID bridge filter |
filter[plot_id] | uuid | Plot UUID bridge filter |
filter[supplier_id] | uuid | Global supplier ID. On /locations/sheds and /locations/plots, also returns descendants of a parent (facility/shed) linked to the supplier; on /locations/facilities and the bare /locations, matches the location's own supplier link only |
filter[supplier_external_id] | string | Caller's org-local supplier identifier (supports eq, in, contains, startsWith). Drills through parents on sheds/plots like supplier_id |
filter[compliance] | enum (eq only) | EUDR deforestation status from the cached roll-up, the first that applies: non_compliant (โฅ1 non-compliant plot), pending (no non-compliant plot, โฅ1 awaiting adjudication review), not_assessed (not a verdict: some plot has no deforestation result yet, or no cached roll-up), compliant (every non-excluded plot has a compliant result), or excluded (every plot excluded from the filing). Facilities and sheds read the cached roll-up; a plot location reads every plot of its latest upload, each with its latest deforestation result and operator decision. Pairs naturally with include=deforestation. |
โถContent negotiation
Accept: application/json(default) โ Paginated JSON envelope.Accept: application/x-ndjsonโ Streams all matching locations as NDJSON (ignores pagination).Accept: application/geo+jsonโ GeoJSON FeatureCollection.Accept: application/x-ndgeo+jsonโ Streaming NDGeoJSON Features.
โถGeometry (include_geometries)
include_geometries)Geometry is opt-in on the JSON formats. By default the geo attribute is
omitted (the server doesn't read it from the database, keeping responses small
and fast). Pass ?include_geometries=true to include it:
application/json/application/x-ndjsonโgeopresent only withinclude_geometries=true.application/geo+json/application/x-ndgeo+jsonโ geometry is always included; the flag isn't needed.
Accepted values are true / false (default false); any other value is 400. See Query Parameters โ Geometry.
โถIncludes (include=)
include=)Opt-in related payloads, attached under each location's relationships
object (suppliers is an attribute). Combine multiple with a comma
(?include=assessment,deforestation). Any unrecognised value returns 400.
| Value | Adds | Notes |
|---|---|---|
assessment | relationships.assessment | Per-assessment-group payloads visible to your org. EUDR-scope partitions (art9 / art10 / eudr_profile) require the assessments:read scope. |
deforestation | relationships.deforestation | Cached EUDR compliance roll-up over the location's catchment plots. Facilities and sheds only โ plot rows omit the block (plot support is a follow-up). |
suppliers | attributes.suppliers | Registry suppliers linked to the location itself. Works in all four response formats. |
โถinclude=deforestation
include=deforestationReturns the same six-field roll-up as the ?include=deforestation block on
Ingestion Assets,
read from a per-location cache (no live catchment scan). Unlike the ingestion
block โ which is scoped to a single asset-task โ the locations roll-up is the
latest cached figure for the location across all tasks, so the same
facility may show different totals on the two endpoints.
// GET /locations/facilities?include=deforestation
"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
}
}
A location with no cached roll-up yet (or a plot) omits the deforestation
key entirely rather than emitting an all-zero block.
โถinclude=suppliers
include=suppliersLists the registry suppliers (GET /parties/suppliers) linked to each
location, as [{ "id", "name" }] sorted by name. A location with no
supplier gets []. These are the location's own links, the same ones
filter[supplier_id] matches on /locations/facilities: a shed or plot
does not inherit its parent facility's suppliers. Deleted suppliers are left
out.
Supplier identities are parties:read data, the same scope
GET /parties/suppliers needs. A scoped key without it gets the location
with no suppliers attribute, not an error.
Within one organisation a location has at most one supplier, because a
later upload replaces the link. A parent organisation also sees its child
organisations' links, so it can see more than one. x-acting-as narrows the
list to that child's links.
// GET /locations/facilities?include=suppliers
"attributes": {
"name": "Mill A",
"suppliers": [
{ "id": "55555555-5555-4555-a555-555555555555", "name": "Acme Co" }
]
}
โถinclude=assessment
include=assessmentAttaches each location's full assessment aggregate under
relationships.assessment โ confidence, hazard, infrastructure,
deforestation screen, and (with assessments:read) the EUDR-scope legality /
country-risk / EUDR-profile partitions โ in one fetch, no per-partition
round-trip. The base list stays gated on locations:read; the three
EUDR-scope partitions additionally require assessments:read. See
Assessments on Ingestion Responses
for the shape and scope gate, and the Assessments API
for the dedicated, filterable per-partition endpoints.
โถSparse fields
Use fields[location]=name,country_code to return only specific attributes.
โถPagination
Two modes are supported on the same endpoint โ see Query Parameters โ Pagination for the full contract.
- Page-number (default):
?page[number]=2&page[size]=50โ givesmeta.totalfor "page X of Y" UIs. - Cursor (keyset):
?page[cursor]=<value>&page[size]=50โ O(page_size) regardless of depth; right choice for >10k results or full-dataset walks.
Every response includes meta.next_cursor and links.next so a client paging by number can switch to cursor mode at any point without losing position.
Approximate counts are the default: meta.total is clamped at LOCATIONS_COUNT_CAP (10,000) and meta.total_is_approx=true is set when the cap was hit. Pass ?meta[count]=exact to force an unbounded count.
โถSorting
Use ?sort= to override the default order (leading - = descending). The sort key is folded into the cursor, so it composes with page[cursor]=. Any key not listed below returns 400. See Query Parameters โ Client-controlled sort.
| Route | Sortable keys |
|---|---|
GET /locations (this route, mixed types) | id |
GET /locations/commodity/:commodity | id |
GET /locations/facilities | /sheds | /plots | id, created_at |
created_at is exposed only on the typed convenience routes (it sorts by the per-org earliest-link timestamp, MIN over your org's pivot rows โ the same value returned in attributes.created_at). On the untyped /locations and /commodity routes a created_at sort returns 400.
Performance note:
created_atis not index-backed โ sorting by it scales with the number of locations of that type in your org (fast for facilities/sheds; on/locations/plotsit can take seconds for very large orgs).idis O(page_size) at any depth.
โถResponse schema (data[])
data[])| Field | Type | Description |
|---|---|---|
type | "location" | Always "location" |
id | uuid | Stable location identifier (the location_id) |
โถattributes
attributes| Field | Type | Description |
|---|---|---|
name | string | null | Normalised location name |
city | string | null | Normalised city |
admin_region | string | null | State/province |
country | string | null | Country name |
country_code | string | null | ISO 3166-1 alpha-2 |
location_type | "facility" | "shed" | "plot" | Underlying entity type |
commodity | string | null | Commodity type |
geo | GeoJSON | null | Location geometry. Omitted unless include_geometries=true (or a GeoJSON Accept format). |
suppliers | { id, name }[] | Registry suppliers linked to the location. Omitted unless include=suppliers. |
created_at | ISO 8601 | null | Creation timestamp |
updated_at | ISO 8601 | null | Last update timestamp |
โถrelationships
relationshipsPresent only when requested via include= (see Includes).
| Key | Present with | Description |
|---|---|---|
assessment | include=assessment | Per-assessment-group payloads |
deforestation | include=deforestation | Cached EUDR compliance roll-up (facilities/sheds) |
โถlinks
links| Key | Description |
|---|---|
self | This location |
deforestation | Latest deforestation metrics for this location |
biodiversity | Latest biodiversity metrics |
emissions | Latest emissions metrics |
water_stress | Latest water stress metrics |
Required scope:
locations:read