Location API Endpoints

This page documents the API endpoints for working with locations in the OAF-100 Location Exchange API.

Get Location by ID

Retrieves the current state of a specific location.

GET /locations/{id}
Authorization: Bearer {access_token}

Path Parameters

Parameter	Type	Description
id	UUID	Location identifier

Response

Status Codes

• 200 OK - Location found and returned
• 401 Unauthorized - Invalid or missing authentication
• 404 Not Found - Location with specified ID does not exist

Success Response (200 OK)

{
  "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"
    }
  }
}

Error Response (404 Not Found)

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Location not found",
    "details": {
      "resourceType": "location",
      "resourceId": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

Example Usage

Event Verification

After receiving a location event via webhook, retrieve the full location to verify current state:

GET /locations/123e4567-e89b-12d3-a456-426614174000

Error Recovery

If event processing fails, fetch the current location state:

GET /locations/456e7890-f12b-34c5-d678-901234567890

Data Validation

Periodically validate specific locations to ensure synchronization:

GET /locations/789abc12-3def-4567-890a-bcdef1234567

Get Location Statistics

Retrieve aggregated counts of locations with optional filters.

GET /locations/statistics
Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Required	Description
status	String	No	Filter by serviceability status (comma-separated)
modifiedSince	ISO 8601 DateTime	No	Count locations modified after this time (UTC with Z suffix)
modifiedBefore	ISO 8601 DateTime	No	Count locations modified before this time (UTC with Z suffix)
hasAddress	Boolean	No	Filter locations with/without address data
hasCoordinates	Boolean	No	Filter locations with/without coordinates
hasLocationGroup	Boolean	No	Filter locations with/without group membership
addressGroupId	UUID	No	Filter by address group
locationGroupId	UUID	No	Filter by location group
country	String	No	Filter by country code
region	String	No	Filter by state/province
locality	String	No	Filter by city/town
postalCode	String	No	Filter by postal code

Response

{
  "totalCount": 45678,
  "countByStatus": {
    "PLANNED": 5000,
    "CONSTRUCTION": 2500,
    "ACTIVE": 38000,
    "INACTIVE": 150,
    "CANCELLED": 25,
    "RETIRED": 3
  },
  "countByType": {
    "addressOnly": 1200,
    "coordinatesOnly": 3400,
    "addressAndCoordinates": 40000,
    "grouped": 15000,
    "standalone": 30678
  },
  "queryTimestamp": "2025-06-08T16:45:00Z"
}

Response Fields

Field	Type	Description
totalCount	Integer	Total number of locations matching all specified filters
countByStatus	Object	Breakdown of locations by serviceability status
countByType	Object	Breakdown of locations by data completeness and grouping
queryTimestamp	ISO 8601 DateTime	Timestamp when the statistics were calculated

Count Type Definitions

The countByType object provides insights into data completeness:

• addressOnly: Locations that have address data but no coordinates
• coordinatesOnly: Locations that have coordinates but no address data
• addressAndCoordinates: Locations that have both address and coordinates
• grouped: Locations that belong to a location group
• standalone: Locations that do not belong to any location group

Example Usage

Basic Count Query

Get total count of all locations:

GET /locations/statistics

Active Locations Only

Count only active locations:

GET /locations/statistics?status=ACTIVE

Recent Changes

Count locations modified in the last 24 hours:

GET /locations/statistics?modifiedSince=2025-06-07T16:45:00Z

Data Quality Check

Find locations missing coordinates:

GET /locations/statistics?hasCoordinates=false&status=ACTIVE

Location Group Statistics

Get statistics for a specific location group:

GET /locations/statistics?locationGroupId=660e8400-e29b-41d4-a716-446655440001

Common Use Cases

Daily Synchronization Check

RSPs typically use location statistics to verify their data matches the network operator:

1. Get current active location count
2. Compare with local system count
3. If counts differ, initiate bulk export to resync

Data Quality Monitoring

Track locations with incomplete data:

1. Check locations missing coordinates: hasCoordinates=false
2. Check locations missing addresses: hasAddress=false
3. Monitor changes over time to ensure data quality improves

Change Tracking

Monitor recent modifications:

# Changes in last 7 days
GET /locations/statistics?modifiedSince=2025-06-01T00:00:00Z

# Changes in specific time window
GET /locations/statistics?modifiedSince=2025-06-01T00:00:00Z&modifiedBefore=2025-06-08T00:00:00Z

Error Codes

The following error codes are specific to location operations:

Code	Description
RESOURCE_NOT_FOUND	Location with specified ID does not exist
UNAUTHORIZED	Invalid or missing authentication token