Group By Tag Prefix
Group your facilities and supply sheds by the namespaced tags they carry โ answering "which of my locations supply each part / SKU / batch?".
Tags follow a namespace:value convention (e.g. partno:12345). Given a
namespace as the :prefix path segment, this endpoint returns one group
per distinct prefix:value tag in your organization, with the locations
carrying that tag bucketed into facilities and sheds.
GET /locations/groups/partno
โถWhat a group contains
Each location_group resource carries:
| Field | Description |
|---|---|
id / attributes.tag | The full tag name (namespace:value). |
attributes.namespace | The requested prefix. |
attributes.value | The tag value (the part of the tag after the first colon). |
attributes.facility_count / attributes.shed_count | Member counts. |
attributes.truncated | true when the group has more members than the per-group cap (1000); only the first cap members are returned. Page the underlying /locations?filter[tags]=<tag> endpoint for the full set. |
relationships.facilities.data / relationships.sheds.data | The member locations, as full location resources. |
โถPlots roll up to their shed
Plots are never returned as members. A tagged plot is rolled up to its
parent supply shed, which appears in the group's sheds. So a group's
members are always facilities and sheds โ the aggregation level a sourcing
question is asked at. (Facilities and sheds tagged directly appear directly.)
โถThe prefix
The :prefix is the namespace only โ it must be colon-free (word
characters and hyphens). It is normalised to lowercase snake_case to match
how tag namespaces are stored (so Part-No resolves to part_no). A prefix
containing a colon, or one that normalises to empty, returns 400.
โถNarrowing to specific tags
Pass ?filter[tags]= to restrict the groups to specific tag names within the
prefix (the same tag filter the location list endpoints accept):
GET /locations/groups/partno?filter[tags]=in:partno:12345,partno:678
โถPagination & ordering
Groups are paged with ?page / ?page_size, ordered by tag value. A group is
never split across pages โ a page returns whole groups with all their
(capped) members. meta.total is the number of matching groups (capped;
meta.total_is_approx when the cap is exceeded โ pass ?meta[count]=exact
to force an unbounded count).
โถResponse formats
- JSON (default) โ the envelope of
location_groupresources shown above. - NDJSON (
Accept: application/x-ndjson) โ one group resource per line. - GeoJSON (
Accept: application/geo+json) โ flattens every group's members into a singleFeatureCollection; each feature carriesgroup(the tag value) andtag(the full tag name) properties so you can regroup client-side.?include_geometries=trueadds geometry to the JSON/NDJSON forms (GeoJSON always includes it).
โถOrg scoping
Groups and their members are scoped to your effective organizations. A tag value present in both a parent and child org merges into one group with its members deduplicated; a group whose members are all invisible to you does not appear.
โถErrors
| Status | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR / BAD_REQUEST | :prefix contains a colon/whitespace or normalises to empty; or filter[organization_id] outside your scope. |
| 401 | MISSING_API_KEY / INVALID_API_KEY | Auth missing or invalid. |
| 403 | FORBIDDEN | API key lacks locations:read. |
Required scope:
locations:read