astra.spacebook module

ASTRA Core — COMSPOC Spacebook Data Integration Module.

Provides free, unauthenticated access to COMSPOC Corporation’s Spacebook platform (https://spacebook.com), which exposes a suite of high-quality Space Situational Awareness (SSA) data products via public HTTP APIs.

No account or credentials are required. All endpoints are freely accessible via standard HTTP GET requests.

Available Data Products

  1. Standard TLE Catalog — full public-catalog TLEs, refreshed frequently.

  2. Historical TLE Catalog — archived TLEs for a specific past date.

  3. XP-TLE Catalog — Extended-Precision TLEs, numerically refined by COMSPOC for higher positional accuracy.

  4. Space Weather (F10.7, Kp, Ap) — CSSI/CelesTrak-compatible fixed-width format, used to drive ASTRA’s empirical atmospheric drag model.

  5. Earth Orientation Parameters (EOP) — polar motion (xp, yp) and UT1-UTC, used for precise ECI↔ECEF coordinate frame transformations.

  6. Satellite Catalog — JSON/CSV catalog mapping object names, NORAD IDs, and COMSPOC GUIDs, with optional extended physical metadata.

  7. Synthetic Covariance Ephemeris — per-satellite STK-format ephemeris containing COMSPOC’s numerically propagated state vectors in TEME frame.

Environment Variables

ASTRA_SPACEBOOK_ENABLED (default: "true")

Set to "false" to fully disable all Spacebook calls. When disabled, astra.data_pipeline.get_space_weather() will fall back to CelesTrak, and per-object GUID-based endpoints will raise SpacebookError.

ASTRA_DATA_DIR (default: ~/.astra/data)

Root directory for local data caches. Spacebook files are stored in a spacebook/ subdirectory underneath this root.

Cache TTLs

  • Space Weather: 6 hours (recent), 7 days (full)

  • EOP: 24 hours (recent), 7 days (full)

  • TLE/XP-TLE: 6 hours

  • Satellite Catalog (JSON): 12 hours (background refresh)

  • Historical TLE: permanent (immutable past data)

  • Synthetic Covariance: 1 hour (changes as new tracking data arrives)

References

astra.spacebook.is_available(timeout=4)[source]

Return True if the Spacebook API is reachable.

Performs a lightweight HEAD-style GET against the Space Weather recent endpoint with a short timeout. Safe to call at startup to decide whether to prefer Spacebook or fall back to CelesTrak.

Parameters:

timeout – Network timeout in seconds (default: 4).

Returns:

True if Spacebook responds with HTTP 200, False otherwise.

astra.spacebook.get_space_weather_sb(t_jd)[source]

Retrieve F10.7 and Ap indices from Spacebook for a given Julian Date.

Downloads and caches the Space Weather data on first call. Subsequent calls resolve directly from the in-memory cache (O(1)). The cache is automatically refreshed when data is more than 6 hours old.

Parameters:

t_jd – Julian Date (UTC scale).

Returns:

Tuple (f107_obs, f107_adj, ap_daily) for the calendar date corresponding to t_jd.

Raises:

SpacebookError – If SPACEBOOK_ENABLED=false or the download fails and no local cache file exists as a fallback.

astra.spacebook.get_eop_sb(t_jd)[source]

Return Earth Orientation Parameters from Spacebook for a given Julian Date.

Parameters:

t_jd – Julian Date (UTC scale).

Returns:

Tuple (xp_arcsec, yp_arcsec, dut1_s) — polar motion X/Y in arcseconds, and UT1-UTC offset in seconds. If no data exists for the exact MJD, linear interpolation between the two nearest records is used. Returns (0.0, 0.0, 0.0) if the cache is completely empty.

Raises:

SpacebookError – If Spacebook is disabled.

astra.spacebook.get_norad_guid(norad_id)[source]

Resolve a NORAD Catalog ID to a COMSPOC GUID.

The GUID is required by all per-object Spacebook endpoints (synthetic covariance, reference ephemeris, etc.). The satellite catalog is downloaded and cached locally on first call, then served from memory.

Parameters:

norad_id – Integer NORAD Catalog number. Leading zeros are ignored.

Returns:

COMSPOC UUID string (e.g. "bf72c797-cee3-45b2-8de1-5bc16ac62ea8").

Raises:
astra.spacebook.refresh_satcat_cache()[source]

Force a full re-download of the Spacebook satellite catalog.

Use this when get_norad_guid() raises SpacebookLookupError for a recently launched satellite that should be in the catalog. This function is also exported as astra.refresh_satcat_cache() for user-facing cache recovery workflows.

Returns:

Number of objects in the refreshed catalog.

Raises:

SpacebookError – If the download fails.

Example

>>> import astra
>>> count = astra.refresh_satcat_cache()
>>> count > 0
True
astra.spacebook.fetch_tle_catalog()[source]

Fetch the current standard TLE catalog from Spacebook.

Returns:

List of SatelliteTLE objects parsed from the Spacebook catalog. Each object carries source="spacebook_tle" in its name field to distinguish data provenance.

Raises:

SpacebookError – If Spacebook is unreachable and no local cache exists.

astra.spacebook.fetch_xp_tle_catalog()[source]

Fetch the Extended-Precision XP-TLE catalog from Spacebook.

XP-TLEs are COMSPOC’s numerically refined state vectors expressed in standard TLE format. They are more accurate than public Space-Track TLEs but still represent ephemeris best estimated at the TLE epoch.

When used as initial conditions for ASTRA’s Cowell RK87 propagator, XP-TLEs significantly reduce the starting-state error compared to standard public TLEs.

Returns:

List of SatelliteTLE objects tagged with source="spacebook_xptle".

Raises:

SpacebookError – If Spacebook is unreachable and no local cache exists.

astra.spacebook.fetch_historical_tle(date)[source]

Fetch the full TLE catalog for a specific historical date from Spacebook.

Historical catalog files are immutable — once fetched for a given date, the file is cached permanently and never re-downloaded.

Parameters:

date – The historical date (UTC). Only the date component is used; time-of-day is ignored.

Returns:

List of SatelliteTLE objects from the catalog for that date.

Raises:

SpacebookError – If the download fails (e.g. future date, or date precedes the Spacebook archive start).

astra.spacebook.fetch_synthetic_covariance_stk(norad_id)[source]

Fetch COMSPOC SynCoPate ephemeris with covariance for a satellite.

The response is an AGI/STK .e (DotE) format ephemeris containing: - COMSPOC’s numerically propagated state vectors (TEME frame, km, km/s) - EphemerisTimePosVel block: per-epoch position + velocity - Inline 6×6 covariance data (lower-triangular format) - Coordinate system: TEMEOfDate - Distance unit: Kilometers

This is the highest-fidelity state-vector timeseries available from Spacebook. Parse with astra.ocm.parse_stk_ephemeris() to obtain a list of NumericalState objects for direct use in ASTRA propagation or benchmark validation.

Parameters:

norad_id – NORAD Catalog number of the satellite.

Returns:

Raw STK ephemeris text string. The caller is responsible for parsing.

Raises:
astra.spacebook.fetch_satcat_details(norad_id)[source]

Fetch detailed physical parameters for a satellite from Spacebook.

Returns COMSPOC-derived physical metadata from the DISCOSweb and Jonathan McDowell catalogs, including: - adoptedMass — best-estimate total mass (kg) - ballisticCoefficient — COMSPOC-derived B* (m²/kg) - crossSectionMedian — median radar cross section (m²) - solarRadiationPressure — CR × (A/m) coefficient

Parameters:

norad_id – NORAD Catalog number.

Returns:

Dictionary with the satellite’s detail record, or an empty dict if the satellite is not found in the details catalog.

Raises:

SpacebookError – If the download fails and no cache exists.