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:

FieldDescription
id / attributes.tagThe full tag name (namespace:value).
attributes.namespaceThe requested prefix.
attributes.valueThe tag value (the part of the tag after the first colon).
attributes.facility_count / attributes.shed_countMember counts.
attributes.truncatedtrue 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.dataThe 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_group resources shown above.
  • NDJSON (Accept: application/x-ndjson) โ€” one group resource per line.
  • GeoJSON (Accept: application/geo+json) โ€” flattens every group's members into a single FeatureCollection; each feature carries group (the tag value) and tag (the full tag name) properties so you can regroup client-side. ?include_geometries=true adds 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

StatusCodeCause
400VALIDATION_ERROR / BAD_REQUEST:prefix contains a colon/whitespace or normalises to empty; or filter[organization_id] outside your scope.
401MISSING_API_KEY / INVALID_API_KEYAuth missing or invalid.
403FORBIDDENAPI key lacks locations:read.

Required scope: locations:read