Source code for space_pv_connectors.n2yo

"""Optional server-side N2YO calculated-position connector."""

from __future__ import annotations

import math
import os
from typing import Any
from urllib.parse import quote

import httpx

from .http_base import HttpConnector


[docs] class N2YOConnector(HttpConnector): """N2YO REST v1. Keep API keys on the server, outside browser bundles. Positions are provider predictions, not satellite GPS telemetry. The free service documents 1,000 position calls/hour and at most 300 samples/call. No retries are made here. Bulk tracking should use cached GP + local SGP4. https://www.n2yo.com/api/ """ def __init__(self, *, api_key: str | None = None, timeout_s: float = 30): key = api_key or os.environ.get("N2YO_API_KEY") if not key or not key.strip(): raise ValueError("Set N2YO_API_KEY or provide api_key") super().__init__(timeout_s=timeout_s) self._api_key = key
[docs] def positions( self, norad_id: int, *, observer_lat: float, observer_lon: float, observer_alt_m: float = 0, seconds: int = 60, ) -> dict[str, Any]: """Return the provider's timestamped position JSON, including provenance. ``sataltitude`` in the provider payload is km; observer altitude is m. Element epoch is not supplied by this endpoint and remains unknown. """ if ( isinstance(norad_id, bool) or not isinstance(norad_id, int) or not 1 <= norad_id <= 999999999 ): raise ValueError("norad_id must be an integer in 1..999999999") if isinstance(seconds, bool) or not isinstance(seconds, int) or not 1 <= seconds <= 300: raise ValueError("seconds must be an integer in 1..300") if not all(math.isfinite(v) for v in (observer_lat, observer_lon, observer_alt_m)): raise ValueError("Observer coordinates must be finite") if not -90 <= observer_lat <= 90 or not -180 <= observer_lon <= 180: raise ValueError("Invalid observer latitude/longitude") url = ( f"https://api.n2yo.com/rest/v1/satellite/positions/{norad_id}/" f"{observer_lat}/{observer_lon}/{observer_alt_m}/{seconds}/" ) try: response = self._client.get( f"{url}&apiKey={quote(self._api_key, safe='')}", follow_redirects=False ) response.raise_for_status() payload = response.json() except (httpx.HTTPError, ValueError): # HTTPX errors can include URLs containing the API key. raise RuntimeError( "N2YO request failed; check service status and credentials" ) from None if ( not isinstance(payload, dict) or payload.get("error") or not isinstance(payload.get("positions"), list) or str(payload.get("info", {}).get("satid")) != str(norad_id) ): raise ValueError("N2YO returned no valid positions for the requested satellite") return { **payload, "source": "N2YO", "position_kind": "predicted", "element_epoch": None, "sataltitude_unit": "km", }