Source code for space_pv_connectors.space_track

from __future__ import annotations

import hashlib
import json
from datetime import UTC, datetime
from pathlib import Path
from typing import Any

import pandas as pd

from .gp_cache import GPCache, GPSnapshot
from .http_base import HttpConnector


[docs] class SpaceTrackConnector(HttpConnector): """Authenticated Space-Track GP/GP-history connector. Credentials should be supplied by environment/secrets management, never committed. """ BASE_URL = "https://www.space-track.org" def login(self, identity: str, password: str) -> None: response = self._client.post( f"{self.BASE_URL}/ajaxauth/login", data={"identity": identity, "password": password}, ) response.raise_for_status() if "login" in str(response.url).lower() and response.status_code == 200: text = response.text.lower() if "password" in text and "identity" in text: raise PermissionError("Space-Track authentication did not establish a session") def latest_gp(self, norad_cat_id: int) -> list[dict[str, Any]]: if isinstance(norad_cat_id, bool) or not isinstance(norad_cat_id, int) or norad_cat_id < 1: raise ValueError("norad_cat_id must be a positive integer") url = ( f"{self.BASE_URL}/basicspacedata/query/class/gp/" f"norad_cat_id/{norad_cat_id}/orderby/EPOCH%20desc/limit/1/format/json" ) response = self._client.get(url) response.raise_for_status() payload = response.json() if not isinstance(payload, list): raise ValueError("Unexpected Space-Track GP response") return payload
[docs] def latest_gp_cached(self, norad_cat_id: int, *, cache_path: str | Path) -> GPSnapshot: """Reuse current OMM for two hours; authenticate first on a cache miss. Shares the same persistent snapshot/provenance contract as CelesTrak. This conservative interval also satisfies Space-Track's hourly GP limit. """ if ( isinstance(norad_cat_id, bool) or not isinstance(norad_cat_id, int) or not 1 <= norad_cat_id <= 999999999 ): raise ValueError("norad_cat_id must be an integer in 1..999999999") return GPCache(cache_path).get( "Space-Track", f"CATNR={norad_cat_id}", lambda: self.latest_gp(norad_cat_id) )
[docs] def gp_history( self, norad_cat_id: int, *, start: str, end: str, cache_dir: str | Path, max_records: int = 100_000, ) -> list[dict[str, Any]]: """Fetch and cache a bounded, complete EPOCH interval in chronological order. Space-Track requests that GP history be downloaded once and reused from disk. A mandatory cache prevents repeated calls for an identical interval. ``start`` and ``end`` are inclusive, timezone-aware element epochs, not publication dates. Authentication is required for a cache miss. Queries over one year should use provider bulk/year files instead. Source: https://www.space-track.org/documentation """ if isinstance(norad_cat_id, bool) or not isinstance(norad_cat_id, int) or norad_cat_id < 1: raise ValueError("norad_cat_id must be a positive integer") first, last = pd.Timestamp(start), pd.Timestamp(end) if pd.isna(first) or pd.isna(last) or first.tzinfo is None or last.tzinfo is None: raise ValueError("start and end require explicit timezones") first, last = first.tz_convert("UTC"), last.tz_convert("UTC") if first >= last or last - first > pd.Timedelta(days=366): raise ValueError("Use a positive interval of at most 366 days, or provider bulk files") if not 1 <= max_records <= 100_000: raise ValueError("max_records must be 1..100000") # Space-Track accepts epoch dates to seconds. Do not silently broaden a # subsecond request, which would invalidate alignment to telemetry. if first != first.floor("s") or last != last.floor("s"): raise ValueError("Space-Track history bounds must have whole-second precision") interval = f"{first.strftime('%Y-%m-%dT%H:%M:%S')}--{last.strftime('%Y-%m-%dT%H:%M:%S')}" url = ( f"{self.BASE_URL}/basicspacedata/query/class/gp_history/norad_cat_id/{norad_cat_id}" f"/EPOCH/{interval}/orderby/EPOCH%20asc/limit/{max_records + 1}/format/json" ) key = hashlib.sha256(url.encode()).hexdigest() directory = Path(cache_dir) directory.mkdir(parents=True, exist_ok=True) path = directory / f"gp_history_{norad_cat_id}_{key[:20]}.json" if path.exists(): cached = json.loads(path.read_text(encoding="utf-8")) serialized = json.dumps(cached.get("records"), sort_keys=True, separators=(",", ":")) if ( cached.get("url") != url or cached.get("sha256") != hashlib.sha256(serialized.encode()).hexdigest() ): raise ValueError("Space-Track history cache failed provenance verification") payload = cached["records"] else: response = self._client.get(url) response.raise_for_status() payload = response.json() if not isinstance(payload, list) or any(not isinstance(row, dict) for row in payload): raise ValueError("Unexpected Space-Track GP-history response") if len(payload) > max_records: raise ValueError("History exceeds max_records; narrow the interval to avoid truncation") for row in payload: if "EPOCH" not in row or str(row.get("NORAD_CAT_ID")) != str(norad_cat_id): raise ValueError("GP-history record lacks the requested satellite or EPOCH") epoch = pd.to_datetime(row["EPOCH"], utc=True, errors="raise") if pd.isna(epoch) or not first <= epoch <= last: raise ValueError("GP-history record falls outside the requested EPOCH interval") payload.sort(key=lambda row: pd.to_datetime(row["EPOCH"], utc=True)) if not path.exists(): serialized = json.dumps(payload, sort_keys=True, separators=(",", ":")) record = { "url": url, "retrieved_at": datetime.now(UTC).isoformat(), "sha256": hashlib.sha256(serialized.encode()).hexdigest(), "records": payload, } temporary = path.with_suffix(".tmp") temporary.write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8") temporary.replace(path) return payload