Locations

Locations are the fundamental unit of the Location Exchange API. Each location represents a point in a network operator's coverage area.

The location model uses a composable object design, allowing network operators to share precisely the data relevant to their specific use cases while maintaining a consistent API contract.

Location Data Model

Structure Overview

json

{
  // Core fields (always present)
  "id": "UUID",
  "createdAt": "ISO 8601 DateTime",
  "updatedAt": "ISO 8601 DateTime",
  
  // Optional core fields
  "notes": "string",
  "locationGroupId": "UUID",
  
  // Required sub-object
  "geography": { /* geographic context */ },
  
  // Optional sub-objects (at least one of address or coordinates required)
  "address": { /* street-level details */ },
  "coordinates": { /* lat/long positioning */ },
  
  // Optional sub-objects
  "fiberAccessDetails": { /* fiber infrastructure details and serviceability */ },
  "customFields": { /* operator-defined data */ }
}

Core Fields

All locations must include these fields at the root level:

Field	Type	Required	Description
`id`	UUID	Yes	Unique identifier generated by network operator
`createdAt`	ISO 8601 DateTime	Yes	When the location was first created (UTC with Z suffix)
`updatedAt`	ISO 8601 DateTime	Yes	When the location was last modified (UTC with Z suffix)
`notes`	String	No	Free-form text for additional location information, special instructions, or RSP-specific context
`locationGroupId`	UUID	No	Reference to location group for business/operational grouping

Location Requirements

Every location must have:

geography object (required)
At least one of: address or coordinates

A location with only geography is not valid.

Geography Object (Required)

Provides geographic context for the location:

Field	Type	Required	Description	Example
`country`	String	Yes	ISO 3166-1 alpha-2 code	`US`
`region`	String	Yes	State/province code	`TX`
`locality`	String	Yes	City/town name	`Austin`
`postalCode`	String	Yes	Postal/ZIP code	`78701`

Address Object (Optional)

Provides street-level addressing when available:

Field	Type	Required	Description
`streetNumber`	String	Yes*	House/building number
`streetName`	String	Yes*	Street name
`streetDirection`	Enum	No	Directional prefix (N, S, E, W, NE, NW, SE, SW)
`streetType`	String	Yes*	Street type (accepts various formats and abbreviations)
`streetSuffix`	String	No	Street suffix (extensions, spurs, loops, service roads)
`subunitType`	String	No	Type of subunit (accepts various formats and abbreviations)
`subunitIdentifier`	String	Conditional	Required if `subunitType` is provided
`addressGroupId`	UUID	No	Reference to address group for logical association

*Required when an address object is provided

Coordinates Object (Optional)

Provides geographic positioning:

Field	Type	Required	Description
`latitude`	Number	Yes	WGS84 latitude (-90 to 90)
`longitude`	Number	Yes	WGS84 longitude (-180 to 180)

Fiber Access Details Object (Optional)

Provides fiber infrastructure and access information:

Field	Type	Required	Description
`circuitId`	String	No	Circuit identifier
`fda`	String	No	Fiber Distribution Area identifier
`fdh`	String	No	Fiber Distribution Hub identifier
`splitterPort`	String	No	Splitter port identifier
`layer2AccessProtocol`	Enum	No	Layer 2 access protocol type (see Enumerations)
`dropStatus`	Enum	No	Status of the fiber drop installation (see Enumerations)
`serviceability`	Object	No	Fiber service availability status

Serviceability Sub-object

When included within fiberAccessDetails, indicates fiber network service availability:

Field	Type	Required	Description
`status`	Enum	Yes	Current lifecycle status (see Enumerations)
`availableDate`	ISO 8601 Date	No	When service is/was available (UTC, e.g., 2025-06-08)

Custom Fields Object (Optional)

Allows network operators to include additional data not covered by standard fields:

Field	Type	Description
`customFields`	Object	Key-value pairs for operator-specific data. Keys must be strings. Values can be strings, numbers, booleans, or arrays of these types.

Examples

Location with Address and Coordinates

json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-06-01T10:30:00Z",
  "updatedAt": "2025-06-08T14:22:00Z",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "AUSTIN",
    "postalCode": "78701"
  },
  "address": {
    "streetNumber": "1234",
    "streetDirection": "N",
    "streetName": "CONGRESS",
    "streetType": "AVENUE"
  },
  "coordinates": {
    "latitude": 30.2672,
    "longitude": -97.7431
  },
  "fiberAccessDetails": {
    "serviceability": {
      "status": "ACTIVE",
      "availableDate": "2025-06-01"
    }
  }
}

Location with Coordinates Only

json

{
  "id": "456e7890-f12b-34c5-d678-901234567890",
  "createdAt": "2025-05-15T08:00:00Z",
  "updatedAt": "2025-05-15T08:00:00Z",
  "notes": "Property entrance at cattle guard, blue gate, mailbox #4421",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "DRIPPING SPRINGS",
    "postalCode": "78620"
  },
  "coordinates": {
    "latitude": 30.1905,
    "longitude": -98.0867
  },
  "fiberAccessDetails": {
    "serviceability": {
      "status": "CONSTRUCTION",
      "availableDate": "2025-09-01"
    }
  }
}

Location with Address Group (MDU)

json

{
  "id": "789abc12-3def-4567-890a-bcdef1234567",
  "createdAt": "2025-04-01T12:00:00Z",
  "updatedAt": "2025-04-01T12:00:00Z",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "AUSTIN",
    "postalCode": "78704"
  },
  "address": {
    "streetNumber": "2500",
    "streetName": "RIVERSIDE",
    "streetType": "DRIVE",
    "subunitType": "APARTMENT",
    "subunitIdentifier": "101",
    "addressGroupId": "550e8400-e29b-41d4-a716-446655440001"
  },
  "coordinates": {
    "latitude": 30.2450,
    "longitude": -97.7298
  },
  "fiberAccessDetails": {
    "serviceability": {
      "status": "ACTIVE",
      "availableDate": "2025-04-01"
    }
  }
}

Location with Subunit (Office Building)

json

{
  "id": "234def45-6789-0abc-def1-234567890abc",
  "createdAt": "2025-03-15T09:00:00Z",
  "updatedAt": "2025-06-01T10:00:00Z",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "AUSTIN",
    "postalCode": "78759"
  },
  "address": {
    "streetNumber": "9800",
    "streetDirection": "N",
    "streetName": "CAPITAL OF TEXAS",
    "streetType": "HIGHWAY",
    "subunitType": "SUITE",
    "subunitIdentifier": "300",
    "addressGroupId": "660e8400-e29b-41d4-a716-446655440002"
  },
  "fiberAccessDetails": {
    "serviceability": {
      "status": "ACTIVE",
      "availableDate": "2025-03-01"
    }
  }
}

Location with Location Group

json

{
  "id": "345efg56-789a-bcde-f012-3456789abcde",
  "createdAt": "2025-06-08T16:00:00Z",
  "updatedAt": "2025-06-08T16:00:00Z",
  "locationGroupId": "770e8400-e29b-41d4-a716-446655440003",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "BUDA",
    "postalCode": "78610"
  },
  "address": {
    "streetNumber": "123",
    "streetName": "OAK",
    "streetType": "DRIVE"
  },
  "fiberAccessDetails": {
    "serviceability": {
      "status": "ACTIVE",
      "availableDate": "2025-06-01"
    }
  }
}

Location with Fiber Access Details

json

{
  "id": "456fgh67-890b-cdef-0123-456789bcdefg",
  "createdAt": "2025-06-10T11:30:00Z",
  "updatedAt": "2025-06-10T11:30:00Z",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "AUSTIN",
    "postalCode": "78702"
  },
  "address": {
    "streetNumber": "456",
    "streetName": "MAIN",
    "streetType": "STREET"
  },
  "coordinates": {
    "latitude": 30.2640,
    "longitude": -97.7361
  },
  "fiberAccessDetails": {
    "circuitId": "CKT-78702-001",
    "fda": "FDA-001-TX-AUSTIN-78702",
    "fdh": "FDH-MAIN-ST-001",
    "splitterPort": "PORT-16-04",
    "layer2AccessProtocol": "GPON",
    "dropStatus": "UNDERGROUND_COMPLETE",
    "serviceability": {
      "status": "ACTIVE",
      "availableDate": "2025-06-01"
    }
  }
}

Location with Custom Fields

json

{
  "id": "567ghi78-901c-defg-1234-56789cdefgh",
  "createdAt": "2025-06-10T12:00:00Z",
  "updatedAt": "2025-06-10T12:00:00Z",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "AUSTIN",
    "postalCode": "78701"
  },
  "address": {
    "streetNumber": "789",
    "streetName": "MAIN",
    "streetType": "STREET"
  },
  "fiberAccessDetails": {
    "serviceability": {
      "status": "ACTIVE",
      "availableDate": "2025-06-01"
    }
  },
  "customFields": {
    "fiberType": "single-mode",
    "buildPartner": "ABC Construction",
    "permitNumber": "2025-12345",
    "internalCode": "LOC-78701-001"
  }
}

Location with Temporary Drop

json

{
  "id": "678hij89-012d-efgh-2345-67890defghi",
  "createdAt": "2025-06-12T09:00:00Z",
  "updatedAt": "2025-06-12T09:00:00Z",
  "geography": {
    "country": "US",
    "region": "TX",
    "locality": "CEDAR PARK",
    "postalCode": "78613"
  },
  "address": {
    "streetNumber": "2100",
    "streetName": "CYPRESS",
    "streetType": "CREEK",
    "streetSuffix": "ROAD"
  },
  "coordinates": {
    "latitude": 30.5083,
    "longitude": -97.8203
  },
  "fiberAccessDetails": {
    "circuitId": "CKT-78613-TMP-001",
    "dropStatus": "TEMP_DROP",
    "serviceability": {
      "status": "ACTIVE",
      "availableDate": "2025-06-10"
    }
  }
}

Implementation Notes

Group References

To retrieve full details about address or location groups referenced in a location:

Use /address-groups/{id} for address group information
Use /location-groups/{id} for location group information

Address Groups

Address groups are simple identifiers (id, name, type) that allow locations to be logically associated. Referenced by addressGroupId within the address object. The address group itself contains no address information - locations with the same addressGroupId can have completely different addresses or the same address with different subunits.

Location Groups

Location groups link locations for business or operational purposes. Referenced by locationGroupId at the location root level.

Status Transitions

Terminal states (CANCELLED and RETIRED) cannot transition to other states. See the Implementation Guide for the complete state diagram.

Custom Fields Usage

Network operators define their own field names and meanings
RSPs should preserve custom fields even if they don't process them
Field names should be descriptive and consistent
Avoid duplicating data available in standard fields

Composable Object Benefits

The location model's composable design provides:

Flexibility: Include only relevant data for each location
Clarity: Each sub-object has a clear, single purpose
Extensibility: New sub-objects can be added without breaking existing implementations
Efficiency: Minimize data transfer by omitting irrelevant fields

Locations

Bulk Exports

Locations ​

Location Data Model ​

Structure Overview ​

Core Fields ​

Location Requirements ​

Geography Object (Required) ​

Address Object (Optional) ​

Coordinates Object (Optional) ​

Fiber Access Details Object (Optional) ​

Serviceability Sub-object ​

Custom Fields Object (Optional) ​

Examples ​

Location with Address and Coordinates ​

Location with Coordinates Only ​

Location with Address Group (MDU) ​

Location with Subunit (Office Building) ​

Location with Location Group ​

Location with Fiber Access Details ​

Location with Custom Fields ​

Location with Temporary Drop ​

Implementation Notes ​

Group References ​

Address Groups ​

Location Groups ​

Status Transitions ​

Custom Fields Usage ​

Composable Object Benefits ​

Locations

Location Data Model

Structure Overview

Core Fields

Location Requirements

Geography Object (Required)

Address Object (Optional)

Coordinates Object (Optional)

Fiber Access Details Object (Optional)

Serviceability Sub-object

Custom Fields Object (Optional)

Examples

Location with Address and Coordinates

Location with Coordinates Only

Location with Address Group (MDU)

Location with Subunit (Office Building)

Location with Location Group

Location with Fiber Access Details

Location with Custom Fields

Location with Temporary Drop

Implementation Notes

Group References

Address Groups

Location Groups

Status Transitions

Custom Fields Usage

Composable Object Benefits