Satellite Telemetry API

Interact with the real-time telemetry stream from AeroVance satellite constellations. Retrieve state vectors, health metrics, and downlink data.

ℹ️

Rate Limits

Standard tier is limited to 100 requests/minute. Enterprise clients can configure dedicated uplinks.

Overview

The Telemetry API provides access to live and historical data from all active AeroVance assets. Data is transmitted via WebSocket for real-time updates or REST endpoints for historical queries.

All coordinates are returned in TEME reference frame by default. Use the ?frame=ECI parameter to convert to Earth-Centered Inertial coordinates.

Authentication

Access to telemetry endpoints requires a valid API key with read:telemetry scope. Include the key in the header:

HTTP Header

Authorization: Bearer av_live_your_api_key_here

Retrieve Satellite State

Fetch the current orbital elements and status for a specific satellite by its NORAD ID or internal UUID.

GET /v1/satellites/{sat_id}/state

Parameters

Parameter	Type	Description
sat_id	string	The unique identifier of the satellite. Can be NORAD ID (integer) or UUID.
frame	string	Coordinate frame. Options: TEME, ECI, ECEF.
include_ephemeris	boolean	Include raw TLE data in the response.

Response

JSON

{
  "satellite_id": "58290",
  "name": "Orion-7B",
  "timestamp": "2025-03-14T08:42:00Z",
  "status": "NOMINAL",
  "orbit": {
    "frame": "TEME",
    "position_km": {
      "x": -4123.84,
      "y": 3850.12,
      "z": 2910.45
    },
    "velocity_km_s": {
      "x": 2.104,
      "y": 5.332,
      "z": -1.882
    },
    "altitude_km": 540.2,
    "inclination_deg": 97.4
  },
  "health": {
    "battery_pct": 88,
    "temp_celsius": 14.2,
    "reaction_wheel_rpm": [1200, 1150, 1180]
  }
}

Real-time Stream

For low-latency applications, establish a WebSocket connection to receive streaming telemetry updates.

JavaScript

import { AeroClient } from '@aerovance/sdk';

const client = new AeroClient({
  apiKey: process.env.AERO_API_KEY,
  region: 'us-east-1'
});

const stream = client.telemetry.subscribe({
  noradId: 58290,
  interval: '1s'
});

stream.onMessage(async (packet) => {
  console.log(`Position: ${packet.orbit.position_km}`);
  await saveToDatabase(packet);
});

stream.onError((err) => {
  console.error('Stream disconnected', err);
});

⚠️

Connection Limits

Maximum 5 concurrent WebSocket connections per API key. Exceeding this limit will result in a 429 Too Many Connections error.

Downlink Payload Data

Access sensor payloads (optical, SAR, SAR) stored on the satellite. Use the Data Catalog API to search for available files.

cURL

curl -X POST https://api.aerovance.com/v1/catalog/search \n  -H "Authorization: Bearer $API_KEY" \n  -H "Content-Type: application/json" \n  -d '{
    "bbox": [-180, 30, 180, 60],
    "sensor_type": "SAR",
    "date_range": { "start": "2025-03-01", "end": "2025-03-14" },
    "min_resolution_m": 1.0
  }'

Error Codes

Code	Status	Description
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Key lacks required scope (e.g., read:telemetry).
404	Not Found	Satellite ID does not exist or is de-orbited.
429	Rate Limit	Too many requests. Check Retry-After header.
503	Service Unavailable	Ground station link down. Retry in 30s.

🔒

Classification Warning

Defense-grade payloads require IL4 clearance. Accessing restricted endpoints without proper attestation will trigger an immediate key revocation and security audit.