> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotastellar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Satellite Tracking

> Real-time positions for 10,000+ active satellites

# Satellite Tracking

Track any satellite in Earth orbit with real-time position data, orbital parameters, and historical trajectories.

<Info>
  **Status:** Early Access — [Request API key](https://rotastellar.com/developers)
</Info>

## Overview

The Satellite Tracking API provides:

* **Real-time positions** — Current lat/lon/altitude for any tracked object
* **Orbital parameters** — Keplerian elements, period, inclination
* **Propagation** — Future position predictions
* **Historical data** — Past trajectory archive

## Catalog Coverage

| Category          | Count   | Sources                 |
| ----------------- | ------- | ----------------------- |
| Active satellites | 10,000+ | Space-Track, commercial |
| Debris objects    | 35,000+ | Space-Track             |
| Total tracked     | 45,000+ | Multiple sources        |

## Quick Start

<CodeGroup>
  ```python Python theme={null}
  from rotastellar import RotaStellarClient

  client = RotaStellarClient(api_key="rs_...")

  # Get satellite by NORAD ID
  iss = client.get_satellite("25544")  # ISS

  # Current position
  print(f"Location: {iss.position.latitude}, {iss.position.longitude}")
  print(f"Altitude: {iss.position.altitude_km} km")

  # Orbital parameters
  print(f"Period: {iss.orbit.orbital_period_minutes} minutes")
  print(f"Inclination: {iss.orbit.inclination_deg} deg")
  ```

  ```typescript Node.js theme={null}
  import { RotaStellarClient } from '@rotastellar/sdk';

  const client = new RotaStellarClient({ apiKey: 'rs_...' });

  // Get satellite
  const iss = await client.getSatellite('25544');  // ISS

  // Current position
  console.log(`Location: ${iss.position?.latitude}, ${iss.position?.longitude}`);
  console.log(`Altitude: ${iss.position?.altitudeKm} km`);

  // Orbital parameters
  console.log(`Period: ${iss.orbit?.periodMin} minutes`);
  ```

  ```rust Rust theme={null}
  use rotastellar::types::{Position, Orbit};

  fn main() -> Result<(), Box<dyn std::error::Error>> {
      // Rust SDK provides types only (HTTP client coming soon)
      // Use Python or Node.js SDK for full API access

      let pos = Position::new(41.264, -95.123, 420.5)?;
      println!("Location: {}, {}", pos.latitude, pos.longitude);
      println!("Altitude: {} km", pos.altitude_km);

      Ok(())
  }
  ```

  ```bash cURL theme={null}
  curl https://api.rotastellar.com/v1/satellites/ISS \
    -H "Authorization: Bearer rs_your_api_key"
  ```
</CodeGroup>

## Get Satellite

Retrieve information about a specific satellite.

```
GET /v1/satellites/{satellite_id}
```

<ParamField path="satellite_id" type="string" required>
  NORAD catalog ID or common name (e.g., "25544" or "ISS")
</ParamField>

### Response

```json theme={null}
{
  "id": "25544",
  "name": "ISS (ZARYA)",
  "names": ["ISS", "ZARYA", "INTERNATIONAL SPACE STATION"],
  "type": "PAYLOAD",
  "operator": "NASA/Roscosmos",
  "launch_date": "1998-11-20",
  "position": {
    "lat": 41.264,
    "lon": -95.123,
    "altitude_km": 420.5,
    "velocity_km_s": 7.66,
    "timestamp": "2026-01-21T12:00:00Z"
  },
  "orbit": {
    "period_min": 92.9,
    "inclination_deg": 51.64,
    "apogee_km": 422,
    "perigee_km": 418,
    "eccentricity": 0.0002
  }
}
```

## List Satellites

Query the satellite catalog with filters.

```
GET /v1/satellites
```

<ParamField query="type" type="string">
  Filter by object type: `PAYLOAD`, `ROCKET_BODY`, `DEBRIS`
</ParamField>

<ParamField query="operator" type="string">
  Filter by operator (e.g., "SpaceX", "OneWeb")
</ParamField>

<ParamField query="constellation" type="string">
  Filter by constellation (e.g., "Starlink", "OneWeb")
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum results (1-1000)
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor for next page
</ParamField>

### Example: List Starlink Satellites

<CodeGroup>
  ```python Python theme={null}
  starlinks = client.list_satellites(
      constellation="Starlink",
      limit=100
  )

  for sat in starlinks:
      print(f"{sat.name}: {sat.position.altitude_km} km")
  ```

  ```bash cURL theme={null}
  curl "https://api.rotastellar.com/v1/satellites?constellation=Starlink&limit=100" \
    -H "Authorization: Bearer rs_your_api_key"
  ```
</CodeGroup>

## Get Position

Get current or predicted position.

```
GET /v1/satellites/{satellite_id}/position
```

<ParamField query="at" type="string">
  ISO 8601 timestamp for prediction (default: now)
</ParamField>

### Example: Predict Future Position

<CodeGroup>
  ```python Python theme={null}
  from datetime import datetime, timedelta

  # Where will ISS be in 2 hours?
  future = (datetime.utcnow() + timedelta(hours=2)).isoformat()

  pos = client.get_satellite_position("25544", at=future)
  print(f"Predicted: {pos.latitude}, {pos.longitude}")
  ```

  ```bash cURL theme={null}
  curl "https://api.rotastellar.com/v1/satellites/ISS/position?at=2026-01-21T14:00:00Z" \
    -H "Authorization: Bearer rs_your_api_key"
  ```
</CodeGroup>

## Get Trajectory

Get position history or predictions over a time range.

```
GET /v1/satellites/{satellite_id}/trajectory
```

<ParamField query="start" type="string" required>
  Start time (ISO 8601)
</ParamField>

<ParamField query="end" type="string" required>
  End time (ISO 8601)
</ParamField>

<ParamField query="interval_sec" type="integer" default="60">
  Time between points in seconds
</ParamField>

### Example: Get 24-hour Trajectory

<CodeGroup>
  ```python Python theme={null}
  from datetime import datetime, timedelta

  trajectory = client.get_trajectory(
      satellite_id="25544",
      start=datetime.utcnow().isoformat(),
      end=(datetime.utcnow() + timedelta(hours=24)).isoformat(),
      interval_sec=300  # Every 5 minutes
  )

  for point in trajectory:
      print(f"{point['timestamp']}: {point['lat']}, {point['lon']}")
  ```

  ```bash cURL theme={null}
  curl "https://api.rotastellar.com/v1/satellites/ISS/trajectory?start=2026-01-21T00:00:00Z&end=2026-01-22T00:00:00Z&interval_sec=300" \
    -H "Authorization: Bearer rs_your_api_key"
  ```
</CodeGroup>

## Data Formats

### Position Object

```json theme={null}
{
  "lat": 41.264,
  "lon": -95.123,
  "altitude_km": 420.5,
  "velocity_km_s": 7.66,
  "timestamp": "2026-01-21T12:00:00Z"
}
```

### Orbit Object

```json theme={null}
{
  "epoch": "2026-01-21T00:00:00Z",
  "period_min": 92.9,
  "inclination_deg": 51.64,
  "raan_deg": 123.45,
  "arg_perigee_deg": 234.56,
  "eccentricity": 0.0002,
  "mean_anomaly_deg": 45.67,
  "apogee_km": 422,
  "perigee_km": 418
}
```

## Rate Limits

| Endpoint        | Free   | Pro     | Enterprise |
| --------------- | ------ | ------- | ---------- |
| Get Satellite   | 10/min | 100/min | Custom     |
| List Satellites | 5/min  | 50/min  | Custom     |
| Get Trajectory  | 2/min  | 20/min  | Custom     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Conjunction Analysis" icon="triangle-exclamation" href="/intelligence/conjunctions">
    Analyze collision risks between objects
  </Card>

  <Card title="Pattern Detection" icon="chart-line" href="/intelligence/patterns">
    Detect anomalies in satellite behavior
  </Card>
</CardGroup>