Events API

Get Catalogue Events

Get all events for a specific catalogue with pagination.

Endpoint: GET /api/catalogues/{id}/events

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Catalogue UUID

Query Parameters:

The API supports three pagination strategies:

1. Cursor-Based Pagination (Recommended for Large Datasets)

Most efficient for large datasets. Uses stable cursors to navigate through results.

Parameter	Type	Required	Default	Description
cursor	string	No		Cursor for pagination (format: “timestamp:id”)
limit	number	No	100	Number of items to return (1-1000)
direction	string	No	‘desc’	Sort direction (‘asc’ or ‘desc’)

Example Request: .. code-block:: text

GET /api/catalogues/{id}/events?limit=50&direction=desc

Response: 200 OK

{
  "data": [
    {
      "id": "event-001",
      "catalogue_id": "550e8400-e29b-41d4-a716-446655440000",
      "time": "2024-10-24T12:34:56.789Z",
      "latitude": -41.2865,
      "longitude": 174.7762,
      "depth": 33.0,
      "magnitude": 5.2,
      "magnitude_type": "ML",
      "region": "Wellington Region",
      "source": "GeoNet",
      "latitude_uncertainty": 0.5,
      "longitude_uncertainty": 0.5,
      "depth_uncertainty": 2.0,
      "azimuthal_gap": 120,
      "used_phase_count": 25,
      "used_station_count": 15,
      "quality_score": 85.5,
      "created_at": "2024-10-24T12:35:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "2024-10-24T12:34:56.789Z:event-001",
    "prevCursor": null,
    "hasMore": true,
    "limit": 50
  }
}

Navigating Pages:

To get the next page, use the nextCursor value: .. code-block:: text

GET /api/catalogues/{id}/events?cursor=2024-10-24T12:34:56.789Z:event-001&limit=50&direction=desc

To get the previous page, use the prevCursor value with opposite direction: .. code-block:: text

GET /api/catalogues/{id}/events?cursor=2024-10-24T12:34:56.789Z:event-001&limit=50&direction=asc

2. Page-Based Pagination

Traditional page-based pagination.

Parameter	Type	Required	Default	Description
page	number	No	1	Page number
pageSize	number	No	50	Items per page (1-1000)

Example Request: .. code-block:: text

GET /api/catalogues/{id}/events?page=1&pageSize=50

Response: 200 OK

{
  "events": [...],
  "total": 1434,
  "page": 1,
  "pageSize": 50
}

3. Limit/Offset Pagination

SQL-style limit/offset pagination.

Parameter	Type	Required	Default	Description
limit	number	No	100	Number of items to return (1-1000)
offset	number	No	0	Number of items to skip

Example Request: .. code-block:: text

GET /api/catalogues/{id}/events?limit=50&offset=100

Performance Notes: - Cursor-based pagination is recommended for large datasets (>10,000 events) as it provides consistent O(1) performance - Page-based pagination is suitable for smaller datasets and UI pagination controls - Limit/offset pagination is provided for backward compatibility but may be slower on large datasets

Get Filtered Events

Get events filtered by various criteria.

Endpoint: GET /api/catalogues/{id}/events/filtered

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Catalogue UUID

Query Parameters:

Parameter	Type	Required	Description
minMagnitude	number	No	Minimum magnitude
maxMagnitude	number	No	Maximum magnitude
minDepth	number	No	Minimum depth (km)
maxDepth	number	No	Maximum depth (km)
startTime	string	No	Start time (ISO 8601)
endTime	string	No	End time (ISO 8601)
minLatitude	number	No	Minimum latitude
maxLatitude	number	No	Maximum latitude
minLongitude	number	No	Minimum longitude
maxLongitude	number	No	Maximum longitude
eventType	string	No	Event type filter
magnitudeType	string	No	Magnitude type (ML, Mw, etc.)
evaluationStatus	string	No	Evaluation status
evaluationMode	string	No	Evaluation mode

Response: 200 OK

{
  "events": [...],
  "count": 234
}