Spacedata

CI npm license

Aggregated public space data — satellite positions, passes, orbits, catalogs and launches — as a single AI-friendly CLI.

Instead of teaching an agent (or yourself) four different APIs, query languages and data formats, spacedata exposes one command vocabulary and always answers with a single JSON document. Caching and circuit breakers are built in so heavy automated use never violates the upstream sources' usage policies.

Status

v0.5 — CelesTrak (orbital elements, catalog search), Launch Library 2 (upcoming launches) and NOAA SWPC (space weather, aurora) with no account needed, plus Space-Track (SATCAT, element history, conjunctions, re-entry predictions) using your own free account. New in 0.5: space weather — planetary Kp with forecast, NOAA R/S/G scales, solar wind, flare class, and OVATION aurora probability for any location. Planned next: ESA DISCOSweb (physical metadata) and a cross-source sat info.

Usage

spacedata position 25544                             # where is the ISS right now (lat/lon/alt, sunlit?)
spacedata passes 25544 --lat 40.42 --lon -3.70       # when does the ISS pass over Madrid (next 3 days)
spacedata passes 25544 --lat 40.42 --lon -3.70 --visible-only   # only passes you can actually see
spacedata overhead --lat 40.42 --lon -3.70           # bright satellites above that spot right now
spacedata spaceweather                               # Kp + forecast, NOAA scales, solar wind, flare class
spacedata aurora --lat 64.13 --lon -21.90            # aurora probability over Reykjavik right now
spacedata tle 25544                                  # latest orbital elements for the ISS
spacedata sat search STARLINK-32000                  # search the catalog by name
spacedata launches upcoming --limit 5                # next 5 orbital launches
spacedata launches upcoming --search starlink        # filter launches
spacedata --pretty tle 25544                         # human-readable JSON
spacedata --fresh tle 25544                          # bypass the local cache
spacedata sat catalog 25544                          # full SATCAT record: type, status, owner, launch, RCS
spacedata conjunctions --limit 20                    # upcoming close approaches (CelesTrak SOCRATES)

position, passes and overhead are computed locally with SGP4 (satellite.js) from the latest CelesTrak elements — pass predictions include AOS/culmination/LOS times, azimuths, max elevation and whether each pass is optically visible (satellite sunlit while your sky is dark).

Two datasets only exist behind a free Space-Track account (set SPACEDATA_SPACETRACK_IDENTITY and SPACEDATA_SPACETRACK_PASSWORD):

spacedata sat history 25544 --limit 30               # orbital element history (orbit evolution/decay)
spacedata reentries --limit 10                       # re-entry predictions (TIP)
spacedata conjunctions --source spacetrack           # official public CDMs instead of SOCRATES

MCP server

spacedata serve runs the same data layer as an MCP server over stdio, for Claude Desktop, Claude Code, Cursor and any other MCP client. Twelve tools: get_orbit, search_satellites, get_satellite_catalog, get_satellite_position, get_satellite_passes, get_satellites_overhead, get_space_weather, get_aurora_forecast, get_conjunctions, get_upcoming_launches, get_orbit_history, get_reentries — with the same caching and rate-limit protection as the CLI.

Claude Code:

claude mcp add spacedata -- npx -y spacedata serve

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "spacedata": {
      "command": "npx",
      "args": ["-y", "spacedata", "serve"]
    }
  }
}

To enable the two Space-Track tools, add "env": {"SPACEDATA_SPACETRACK_IDENTITY": "...", "SPACEDATA_SPACETRACK_PASSWORD": "..."} to the server entry.

Tip: if your agent can run shell commands (like Claude Code), the plain CLI is cheaper in context tokens than loading MCP tool schemas — serve shines in clients without a shell (Claude Desktop, claude.ai).

Using with AI agents

spacedata is designed to be driven by AI agents: single JSON document per invocation, semantic exit codes, no interactive prompts, and built-in caching/rate limiting so an agent in a loop can never get you banned from an upstream source.

For Claude Code, add this to your ~/.claude/CLAUDE.md (or a project CLAUDE.md); other agents (Cursor, etc.) have equivalent instruction files:

- `spacedata` — CLI for public space data (no API keys needed). Use it via the shell
  for anything about satellites, orbits, passes, conjunctions or launches:
  `spacedata position <norad-id>` (live location), `spacedata passes <norad-id> --lat .. --lon ..`
  (when it flies over, incl. visibility), `spacedata overhead --lat .. --lon ..` (what's above),
  `spacedata tle <norad-id>`, `spacedata sat search <name>`, `spacedata sat catalog <norad-id>`,
  `spacedata conjunctions [--norad id]`, `spacedata launches upcoming [--search text]`.
  Always outputs one JSON document; exit 2 = not found. Run `spacedata --help` for details.

Example output (spacedata tle 25544):

{"ok":true,"source":"celestrak","cached":false,"fetchedAt":"2026-07-03T14:20:17.278Z",
 "data":[{"noradId":25544,"name":"ISS (ZARYA)","internationalDesignator":"1998-067A",
 "epoch":"2026-07-01T12:11:46.289760","meanMotionRevPerDay":15.49503254,
 "eccentricity":0.00042241,"inclinationDeg":51.6311,
 "derived":{"semiMajorAxisKm":6796.315,"perigeeAltitudeKm":415.307,
 "apogeeAltitudeKm":421.049,"periodMinutes":92.933}}]}

Output contract

Stable, designed for AI agents:

• stdout: one JSON document — {ok: true, source, cached, fetchedAt, data}
• stderr: one JSON document — {ok: false, error: {code, message, ...}}
• exit codes: 0 ok · 1 usage error · 2 not found · 3 upstream/network error · 4 circuit open or rate limited · 5 unexpected upstream schema · 6 missing or rejected credentials · 7 computation failed

tle and sat search include derived geometry per object: perigee/apogee altitude (km), period (minutes) and semi-major axis, computed from the mean elements. Locally computed results (position, passes, overhead) report source: "celestrak+sgp4" plus the element epoch and age, and warn when element age degrades SGP4 accuracy.

Caching and upstream policies

Responses are cached in ~/.cache/spacedata (override with --cache-dir or XDG_CACHE_HOME):

Source	TTL	Why
CelesTrak	2 h	GP data updates every 2 h; policy asks for one download per cycle
Launch Library 2	1 h	Free tier allows 15 calls/hour per IP
NOAA SWPC	5 min (real-time) / 30 min (forecasts)	Products refresh every 1-5 min; one cache per refresh cycle

On any non-200 response the source's circuit breaker opens and spacedata refuses to query it again until the cooldown expires (CelesTrak's M2M policy requires stopping immediately on errors; ignoring it gets your IP firewalled).

Environment variables

• SPACEDATA_LL2_TOKEN — Launch Library 2 API token (Patreon tiers) for higher rate limits.
• SPACEDATA_LL2_BASE_URL — override the LL2 base URL, e.g. https://lldev.thespacedevs.com/2.3.0 (no rate limits, stale data) while developing.

Development

Bun monorepo (packages/*), TypeScript, Biome, Zod for all external data, neverthrow for results.

make setup     # install deps
make build     # typecheck + bundle to packages/cli/dist
make test      # bun test
make check     # biome lint

Run from source without building:

cd packages/cli && bun src/cli.ts tle 25544

Data sources & credits

• Orbital data: CelesTrak (Dr. T.S. Kelso)
• Launch data: Launch Library 2 by The Space Devs
• Space weather and aurora data: NOAA SWPC
• SGP4 propagation: satellite.js