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, or plot_id bridge 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]:

PathEquivalent
GET /locations/facilitiesfilter[location_type]=eq:facility
GET /locations/shedsfilter[location_type]=eq:shed
GET /locations/plotsfilter[location_type]=eq:plot
GET /locations/commodity/:commodityfilter[commodity]=eq::commodity

Filters

Use filter[field]=condition:value syntax. See Query Parameters for details.

FilterTypeDescription
filter[location_type]enumfacility, shed, or plot
filter[commodity]enumCommodity type (palm, cocoa, coffee, etc.)
filter[country_code]iso-countryISO 3166-1 alpha-2
filter[name]stringLocation name (supports eq, contains, startsWith)
filter[organization_id]uuidNarrow to a specific child org
filter[facility_id]stringFacility ID (text) bridge filter
filter[shed_id]uuidShed UUID bridge filter
filter[plot_id]uuidPlot UUID bridge filter
filter[supplier_id]uuidGlobal 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]stringCaller'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)

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 โ€” geo present only with include_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=)

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.

ValueAddsNotes
assessmentrelationships.assessmentPer-assessment-group payloads visible to your org. EUDR-scope partitions (art9 / art10 / eudr_profile) require the assessments:read scope.
deforestationrelationships.deforestationCached 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).
suppliersattributes.suppliersRegistry suppliers linked to the location itself. Works in all four response formats.

include=deforestation

Returns 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

Lists 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

Attaches 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 โ€” gives meta.total for "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.

RouteSortable keys
GET /locations (this route, mixed types)id
GET /locations/commodity/:commodityid
GET /locations/facilities | /sheds | /plotsid, 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_at is not index-backed โ€” sorting by it scales with the number of locations of that type in your org (fast for facilities/sheds; on /locations/plots it can take seconds for very large orgs). id is O(page_size) at any depth.

Response schema (data[])

FieldTypeDescription
type"location"Always "location"
iduuidStable location identifier (the location_id)

attributes

FieldTypeDescription
namestring | nullNormalised location name
citystring | nullNormalised city
admin_regionstring | nullState/province
countrystring | nullCountry name
country_codestring | nullISO 3166-1 alpha-2
location_type"facility" | "shed" | "plot"Underlying entity type
commoditystring | nullCommodity type
geoGeoJSON | nullLocation 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_atISO 8601 | nullCreation timestamp
updated_atISO 8601 | nullLast update timestamp

relationships

Present only when requested via include= (see Includes).

KeyPresent withDescription
assessmentinclude=assessmentPer-assessment-group payloads
deforestationinclude=deforestationCached EUDR compliance roll-up (facilities/sheds)
KeyDescription
selfThis location
deforestationLatest deforestation metrics for this location
biodiversityLatest biodiversity metrics
emissionsLatest emissions metrics
water_stressLatest water stress metrics

Required scope: locations:read