Location Groups

Location Groups are simple identifiers that allow multiple locations to be logically associated together for operational or business purposes. They consist only of an ID, name, and type.

Overview

Location groups provide flexible organization without constraints:

• Groups are just identifiers referenced by locations
• Locations in the same group can be anywhere in the service area
• The group itself has no knowledge of the locations that reference it

Get Location Group by ID

GET /location-groups/{id}
Authorization: Bearer {access_token}

Path Parameters

Parameter	Type	Description
id	UUID	Location group identifier

Response

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Downtown Service Area",
  "type": "OTHER"
}

List Location Groups

GET /location-groups
Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Required	Description
type	String	No	Filter by group type
name	String	No	Filter by name (partial match)
limit	Integer	No	Maximum results to return (default: 100)
offset	Integer	No	Pagination offset (default: 0)

Response

{
  "locationGroups": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Downtown Service Area",
      "type": "OTHER"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440002",
      "name": "Phase 3 Deployment",
      "type": "OTHER"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2
  }
}

Data Model

Field	Type	Description
id	UUID	Unique identifier for the location group
name	String	Human-readable name of the group
type	Enum	Currently only OTHER is valid

How It Works

Locations reference location groups through the locationGroupId field at the root level:

// Location Group
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Downtown Service Area",
  "type": "OTHER"
}

// Location 1 in group
{
  "id": "loc-001",
  "locationGroupId": "660e8400-e29b-41d4-a716-446655440001",
  "address": {
    "streetNumber": "100",
    "streetName": "MAIN",
    "streetType": "STREET"
  }
}

// Location 2 in same group (different area)
{
  "id": "loc-002",
  "locationGroupId": "660e8400-e29b-41d4-a716-446655440001",
  "address": {
    "streetNumber": "500",
    "streetName": "COMMERCE",
    "streetType": "AVENUE"
  }
}

Common Use Cases

Location groups can be used for any organizational need:

• Service areas or territories
• Deployment phases
• Customer segments
• Network segments
• Operational zones
• Any custom grouping

Finding Locations in a Group

# Get all locations in a group
GET /locations?locationGroupId=660e8400-e29b-41d4-a716-446655440001

# Export locations in a group
POST /locations/exports
{
  "filters": {
    "locationGroupId": "660e8400-e29b-41d4-a716-446655440001"
  }
}

# Get statistics for a group
GET /locations/statistics?locationGroupId=660e8400-e29b-41d4-a716-446655440001

Error Responses

404 Not Found

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Location group not found"
  }
}

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid UUID format"
  }
}

Related Resources

• Locations Data Model - How locations reference location groups
• Address Groups - Groups for MDU addresses