API Reference¶

This document describes the REST API endpoints available in the dd1 service. All endpoints are accessed via the base URL https://api.spacedotsdata.io.

Interactive Documentation: For live testing and interactive exploration of the API, visit the Swagger UI at https://api.spacedotsdata.io/api-docs.

Overview¶

This API exposes DD1 (Data Dot 1) sensor payload frames in various formats, organized around logical resource groups and functionality. Most endpoints require authentication using client credentials (client ID and secret) obtained via the token endpoint.

Authentication¶

Authentication is required for all endpoints except /health/public and /token. You can obtain a bearer token using client credentials via the /token endpoint, or use Basic authentication directly with client credentials.

Authentication Methods¶

Bearer Token: Obtain a token via POST /token and include it in the Authorization: Bearer <token> header
Basic Authentication: Include Authorization: Basic base64(client_id:secret) header directly

Endpoints by Resource Group¶

Health Endpoints¶

Public health check endpoints.

`GET /health/public`¶

Check if the service is running and healthy (public endpoint, no authentication required).

Response:

{
  "status": "ok",
  "timestamp": "2025-02-26T18:07:29.123Z"
}

`GET /health/protected`¶

Check if the service is running with authentication verification (requires authentication).

Response:

{
  "status": "authenticated",
  "timestamp": "2025-02-26T18:07:29.123Z"
}

Authentication Endpoints¶

Authentication token management.

`POST /token`¶

Obtain a bearer token using client credentials.

Headers:

Authorization: Basic authentication header containing client_id:secret encoded in base64

Example Request:

POST /token
Authorization: Basic Y2xpZW50X2lkOnNlY3JldA==

Success Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "email profile"
}

Error Responses:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

{
  "error": "invalid_request",
  "error_description": "Missing or invalid Authorization header. Use Basic auth format: Basic base64(client_id:secret)"
}

DD1 Raw Frame Endpoints¶

Endpoints for accessing raw time series data in denormalized format.

`GET /dd1-raw-frame`¶

Get paginated time-series data frames containing dd1 data at an ascending time order from oldest to newest.

Query Parameters:

page (optional): Page number, default: 1
limit (optional): Items per page (max: 500), default: 50

Response:

{
  "data": [
    {
      "unixTimestampMs": 1704067200000,
      "datasetId": "mission-001",
      "positionEciXKm": 6871.0,
      "positionEciYKm": 0.0,
      "positionEciZKm": 0.0,
      "positionInterpolationFlag": "NONE",
      "velocityEciVxKmS": 7.6,
      "velocityEciVyKmS": 0.0,
      "velocityEciVzKmS": 0.0,
      "latitudeDeg": 0.0,
      "longitudeDeg": 0.0,
      "altitudeKm": 6871.0,
      "omegaXRadS": 0.001,
      "omegaYRadS": 0.0,
      "omegaZRadS": 0.0,
      "quaternionQ0": 1.0,
      "quaternionQ1": 0.0,
      "quaternionQ2": 0.0,
      "quaternionQ3": 0.0,
      "quaternionInterpolationFlag": "LINEAR",
      "pt1000Data0SensorId": 30,
      "pt1000Data0Temperature": 25.5,
      "magnetometerData0SensorId": 50,
      "magnetometerData0Temperature": 25.0,
      "magnetometerData0MagneticField0": 25.3,
      "magnetometerData0MagneticField1": -12.7,
      "magnetometerData0MagneticField2": 42.1,
      "source": "telemetry-stream-1"
    }
  ],
  "meta": {
    "total": 1000,
    "page": 1,
    "limit": 50,
    "totalPages": 20
  }
}

`GET /dd1-raw-frame/range`¶

Get paginated time series data frames within a specific Unix timestamp range.

Query Parameters:

start (required): Start Unix timestamp (seconds or milliseconds)
end (required): End Unix timestamp (seconds or milliseconds)
sensorId (optional): Filter by specific sensor ID
page (optional): Page number, default: 1
limit (optional): Items per page (max: 500), default: 50

Response: Returns paginated results with metadata:

{
  "data": [
    {
      "unixTimestampMs": 1704067200000,
      "datasetId": "mission-001",
      "positionEciXKm": 6871.0,
      "positionEciYKm": 0.0,
      "positionEciZKm": 0.0,
      "positionInterpolationFlag": "NONE",
      "velocityEciVxKmS": 7.6,
      "velocityEciVyKmS": 0.0,
      "velocityEciVzKmS": 0.0,
      "latitudeDeg": 0.0,
      "longitudeDeg": 0.0,
      "altitudeKm": 6871.0,
      "omegaXRadS": 0.001,
      "omegaYRadS": 0.0,
      "omegaZRadS": 0.0,
      "quaternionQ0": 1.0,
      "quaternionQ1": 0.0,
      "quaternionQ2": 0.0,
      "quaternionQ3": 0.0,
      "quaternionInterpolationFlag": "LINEAR",
      "pt1000Data0SensorId": 30,
      "pt1000Data0Temperature": 25.5,
      "magnetometerData0SensorId": 50,
      "magnetometerData0Temperature": 25.0,
      "magnetometerData0MagneticField0": 25.3,
      "magnetometerData0MagneticField1": -12.7,
      "magnetometerData0MagneticField2": 42.1,
      "source": "telemetry-stream-1"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 50,
    "totalPages": 2
  }
}

`GET /dd1-raw-frame/query`¶

Query frames by time and location with flexible search parameters.

Query Parameters:

start (optional): Start Unix timestamp for range (seconds or milliseconds)
end (optional): End Unix timestamp for range (seconds or milliseconds)
lat (optional): Latitude for geographic search (degrees)
lon (optional): Longitude for geographic search (degrees)
alt (optional): Altitude for 3D geographic search (kilometers)
radius (optional): Search radius in kilometers
page (optional): Page number, default: 1
limit (optional): Items per page (max: 500), default: 50

Response: Returns paginated query results in the same format as GET /dd1-raw-frame.

DD1 Data Frame Endpoints¶

Endpoints for accessing transformed dd1 data in Dd1DataFrame format with nested sensor arrays. All endpoints require authentication.

`GET /dd1-data-frame`¶

Get paginated data frames in Dd1DataFrame format with nested sensor data at an ascending time order from oldest to newest.

Query Parameters:

page (optional): Page number, default: 1
limit (optional): Items per page (max: 500), default: 50

Response Structure:

{
  "data": [
    {
      "unixTimestampMs": 1738197122102,
      "datasetId": "op_quac_fm_space-acquisition_001",
      "telemetry": {
        "telemetryTimestamp": 1738197125.741833,
        "interpolationMethod": "nearest",
        "positionLla": [
          50.93193820717789, 102.75497643750353, 533.7226754132596
        ],
        "positionEciKm": [
          -963.5567016601562, 4256.590332031251, 5343.1572265625
        ],
        "velocityEciKmS": [
          2.814931869506836, -5.266892433166504, 4.696627140045166
        ],
        "quaternion": [0.653, -0.032, 0.264, 0.708]
      },
      "pt1000Data": [
        {
          "sensorId": 2,
          "temperature": -27.977
        }
      ],
      "magnetometerData": [
        {
          "sensorId": 13,
          "temperature": -0.027667518615722655,
          "magneticField": [
            -8.171945571899414, -43.715877532958984, -24.683975219726562
          ]
        }
      ],
      "accelerometerData": [
        {
          "sensorId": 11,
          "temperature": -0.02765234375,
          "acceleration": [
            0.00555428396910429, 0.0008545052260160446, 0.019836727529764175
          ]
        }
      ],
      "gyroscopeData": [
        {
          "sensorId": 11,
          "angularRate": [
            -0.3662165403366089, 0.4272526204586029, -0.24414435029029846
          ]
        }
      ],
      "powerMonitorData": [
        {
          "sensorId": 1,
          "voltage": [5.281, 0.0, 0.002, 0.002],
          "current": [0.008, 0.0, 0.0, 0.001]
        }
      ],
      "dosimeterData": [
        {
          "sensorId": 15,
          "radiationCount": 0,
          "millisievertsPerHour": 0.0,
          "uptimeS": 0,
          "voltage": 0.0,
          "temperatureDegc": 0
        }
      ]
    }
  ],
  "meta": {
    "total": 1000,
    "page": 1,
    "limit": 50,
    "totalPages": 20
  }
}

`GET /dd1-data-frame/range`¶

Get paginated Dd1DataFrame objects within a specific Unix timestamp range.

Query Parameters:

start (required): Start Unix timestamp (seconds or milliseconds)
end (required): End Unix timestamp (seconds or milliseconds)
sensorId (optional): Filter by specific sensor ID
page (optional): Page number, default: 1
limit (optional): Items per page (max: 500), default: 50

Response: Returns paginated results with metadata:

{
  "data": [
    {
      "unixTimestampMs": 1738197122102,
      "datasetId": "op_quac_fm_space-acquisition_001",
      "telemetry": {
        "telemetryTimestamp": 1738197125.741833,
        "interpolationMethod": "nearest",
        "positionLla": [
          50.93193820717789, 102.75497643750353, 533.7226754132596
        ],
        "positionEciKm": [
          -963.5567016601562, 4256.590332031251, 5343.1572265625
        ],
        "velocityEciKmS": [
          2.814931869506836, -5.266892433166504, 4.696627140045166
        ],
        "quaternion": [0.653, -0.032, 0.264, 0.708]
      },
      "pt1000Data": [
        {
          "sensorId": 2,
          "temperature": -27.977
        }
      ],
      "magnetometerData": [
        {
          "sensorId": 13,
          "temperature": -0.027667518615722655,
          "magneticField": [
            -8.171945571899414, -43.715877532958984, -24.683975219726562
          ]
        }
      ],
      "accelerometerData": [
        {
          "sensorId": 11,
          "temperature": -0.02765234375,
          "acceleration": [
            0.00555428396910429, 0.0008545052260160446, 0.019836727529764175
          ]
        }
      ],
      "gyroscopeData": [
        {
          "sensorId": 11,
          "angularRate": [
            -0.3662165403366089, 0.4272526204586029, -0.24414435029029846
          ]
        }
      ],
      "powerMonitorData": [
        {
          "sensorId": 1,
          "voltage": [5.281, 0.0, 0.002, 0.002],
          "current": [0.008, 0.0, 0.0, 0.001]
        }
      ],
      "dosimeterData": [
        {
          "sensorId": 15,
          "radiationCount": 0,
          "millisievertsPerHour": 0.0,
          "uptimeS": 0,
          "voltage": 0.0,
          "temperatureDegc": 0
        }
      ]
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 50,
    "totalPages": 2
  }
}

Example Response:

[
  {
    "unixTimestampMs": 1746401980839,
    "datasetId": "acq-data-op_quac_fm_space-acquisition_024",
    "telemetry": {
      "telemetryTimestamp": 1746401980839,
      "interpolationMethod": "valid",
      "positionLla": [-51.534, 157.635, 596.599],
      "positionEciKm": [4178.557, 1149.524, -5448.215],
      "velocityEciKmS": [-5.483, -3.156, -4.316],
      "quaternion": [0.653, -0.032, 0.264, 0.708]
    },
    "pt1000Data": [
      {
        "sensorId": 2,
        "temperature": -10855
      }
    ],
    "magnetometerData": [
      {
        "sensorId": 13,
        "temperature": -3.623,
        "magneticField": [-63.39, -35.37, -9.0]
      }
    ],
    "accelerometerData": [
      {
        "sensorId": 11,
        "acceleration": [0.004, -0.001, 0.014]
      }
    ],
    "gyroscopeData": [
      {
        "sensorId": 11,
        "angularRate": [-0.183, 0.244, -0.244]
      }
    ],
    "powerMonitorData": [
      {
        "sensorId": 1,
        "voltage": [5284, 0, 1, 2],
        "current": [9, 2, 0, 0]
      }
    ],
    "dosimeterData": [
      {
        "sensorId": 15,
        "radiationCount": 28,
        "millisievertsPerHour": 0.002,
        "uptimeS": 0,
        "voltage": 0.0,
        "temperatureDegc": 0
      }
    ]
  }
]

`GET /dd1-data-frame/query`¶

Query frames by time and location with flexible search parameters.

Query Parameters:

start (optional): Start Unix timestamp for range (seconds or milliseconds)
end (optional): End Unix timestamp for range (seconds or milliseconds)
lat (optional): Latitude for geographic search (degrees)
lon (optional): Longitude for geographic search (degrees)
alt (optional): Altitude for 3D geographic search (kilometers)
radius (optional): Search radius in kilometers
page (optional): Page number, default: 1
limit (optional): Items per page (max: 500), default: 50

Response: Returns paginated query results in the same format as GET /dd1-data-frame.

Data Structures¶

For detailed information about the data structures returned by the API, including comprehensive field descriptions and examples, please refer to the Data Structures documentation.

The API returns two primary data structure types:

Dd1RawFrame: Raw dd1 telemetry data in a flat, denormalized format (returned by /dd1-raw-frame endpoints)
Dd1DataFrame: Transformed dd1 telemetry data with nested sensor arrays organized by sensor type (returned by /dd1-data-frame endpoints)

See the Data Structures page for complete documentation of all fields, data formats, and usage examples.

API Reference¶

Overview¶

Authentication¶

Authentication Methods¶

Endpoints by Resource Group¶

Health Endpoints¶

GET /health/public¶

GET /health/protected¶

Authentication Endpoints¶

POST /token¶

DD1 Raw Frame Endpoints¶

GET /dd1-raw-frame¶

GET /dd1-raw-frame/range¶

GET /dd1-raw-frame/query¶

DD1 Data Frame Endpoints¶

GET /dd1-data-frame¶

GET /dd1-data-frame/range¶

GET /dd1-data-frame/query¶

Data Structures¶

`GET /health/public`¶

`GET /health/protected`¶

`POST /token`¶

`GET /dd1-raw-frame`¶

`GET /dd1-raw-frame/range`¶

`GET /dd1-raw-frame/query`¶

`GET /dd1-data-frame`¶

`GET /dd1-data-frame/range`¶

`GET /dd1-data-frame/query`¶