spb/satelliteindex

1/** Public API catalogue for /developers — mirrors the FastAPI routers (verified against /api/v1/openapi.json). */23export interface EndpointDoc {4  method: 'GET' | 'POST';5  path: string;6  summary: string;7  params?: string[];8  example: string;9  bucket?: 'search' | 'positions' | 'position';10}1112export const ENDPOINT_GROUPS: { title: string; endpoints: EndpointDoc[] }[] = [13  {14    title: 'Satellites',15    endpoints: [16      { method: 'GET', path: '/satellites', summary: 'Paginated catalog with filters (status, object_type, orbit_class, mission_type, country, operator, constellation, launch, launch_site, on_orbit, has_gp, launched_after/before, decayed_after, min/max_perigee, tag, q, sort).', params: ['page', 'page_size', 'sort', '…'], example: '/satellites?status=ACTIVE&orbit_class=LEO&sort=-launch_date&page_size=25' },17      { method: 'GET', path: '/satellites/facets', summary: 'Facet counts (status, object type, orbit class, mission type, country, constellation) for the same filters.', example: '/satellites/facets?constellation=starlink' },18      { method: 'GET', path: '/satellites/{ident}', summary: 'One object by slug, NORAD id or COSPAR id — canonical record, latest elements, live position, provenance, freshness, events, siblings.', example: '/satellites/25544' },19      { method: 'GET', path: '/satellites/{ident}/position', summary: 'Geodetic position (lat, lon, altitude, velocity) at `time` (default now), propagated on demand with SGP4.', params: ['time'], example: '/satellites/25544/position', bucket: 'position' },20      { method: 'GET', path: '/satellites/{ident}/live', summary: 'Lightweight live position for polling UIs (30 s cache).', example: '/satellites/25544/live', bucket: 'position' },21      { method: 'GET', path: '/satellites/{ident}/track', summary: 'Ground track: points `before`/`after` now (minutes) every `step` seconds, with a `future` flag.', params: ['before', 'after', 'step'], example: '/satellites/25544/track?before=45&after=90&step=60' },22      { method: 'GET', path: '/satellites/{ident}/orbit', summary: 'Orbital element history (append-only), newest first.', params: ['limit'], example: '/satellites/25544/orbit?limit=50' },23      { method: 'GET', path: '/satellites/{ident}/history', summary: 'Field change log (status, operator, orbit class…) plus a daily altitude/period/inclination series.', example: '/satellites/25544/history' },24    ],25  },26  {27    title: 'Search',28    endpoints: [29      { method: 'GET', path: '/search', summary: 'Full-text search across satellites, operators, constellations, countries, launches and launch sites; returns ranked results with hrefs and filter shortcuts.', params: ['q', 'limit', 'types'], example: '/search?q=starlink&limit=10', bucket: 'search' },30      { method: 'GET', path: '/search/suggest', summary: 'Typeahead suggestions.', params: ['q'], example: '/search/suggest?q=sent', bucket: 'search' },31    ],32  },33  {34    title: 'Entities',35    endpoints: [36      { method: 'GET', path: '/constellations', summary: 'Constellations with fleet counts, growth and activity score.', params: ['service', 'orbit', 'sort', 'page', 'page_size'], example: '/constellations?sort=-active' },37      { method: 'GET', path: '/constellations/{slug}', summary: 'Constellation detail: shells, histograms, launches, memberships, match patterns and CelesTrak groups used.', example: '/constellations/starlink' },38      { method: 'GET', path: '/operators', summary: 'Operators / organizations with payload counts.', params: ['kind', 'country', 'sort', 'q', 'page', 'page_size'], example: '/operators?sort=-active_payloads' },39      { method: 'GET', path: '/operators/{slug}', summary: 'Operator detail: fleet, constellations, launches, distributions.', example: '/operators/spacex' },40      { method: 'GET', path: '/countries', summary: 'Countries ranked by active payloads, on-orbit objects or debris.', params: ['sort'], example: '/countries?sort=active' },41      { method: 'GET', path: '/countries/{ident}', summary: 'Country detail by ISO code or slug.', example: '/countries/CA' },42    ],43  },44  {45    title: 'Launches, debris, reentries',46    endpoints: [47      { method: 'GET', path: '/launches', summary: 'Launches derived from international designators, with payload/object counts.', params: ['year', 'site', 'country', 'owner', 'min_payloads', 'after', 'before', 'q', 'sort', 'page', 'page_size'], example: '/launches?year=2026&sort=-launch_date' },48      { method: 'GET', path: '/launches/timeline', summary: 'Launches and payloads per year and month, plus launch sites.', example: '/launches/timeline' },49      { method: 'GET', path: '/launches/{cospar}', summary: 'One launch by designator prefix (YYYY-NNN) with all catalogued objects.', example: '/launches/1998-067' },50      { method: 'GET', path: '/launch-sites', summary: 'Launch sites with coordinates and counts.', example: '/launch-sites' },51      { method: 'GET', path: '/launch-sites/{slug}', summary: 'Launch site detail with yearly series and recent launches.', example: '/launch-sites/kennedy-space-center' },52      { method: 'GET', path: '/debris', summary: 'Debris and rocket-body totals by country, altitude, launch; growth and decay series.', example: '/debris' },53      { method: 'GET', path: '/reentries', summary: 'Recently decayed objects (paginated), monthly series and a low-perigee watch list.', params: ['object_type', 'days', 'page', 'page_size'], example: '/reentries?days=30' },54    ],55  },56  {57    title: 'Events and statistics',58    endpoints: [59      { method: 'GET', path: '/events', summary: 'Detected events (launch catalogued, decay, status change, orbit change…) with linked entities.', params: ['type', 'since', 'entity', 'page', 'page_size'], example: '/events?type=DECAY&page_size=20' },60      { method: 'GET', path: '/events/{event_id}', summary: 'One event.', example: '/events/evt_…' },61      { method: 'GET', path: '/stats', summary: 'Latest global statistics snapshot: totals, by orbit class / object type / mission, yearly series, top entities, orbital buckets, connector state.', example: '/stats' },62      { method: 'GET', path: '/rankings', summary: 'Ranked lists by metric (e.g. active_payloads, debris, launches_365d).', params: ['metric', 'limit'], example: '/rankings?metric=active_payloads&limit=20' },63      { method: 'GET', path: '/orbit/density', summary: 'Orbital density: objects per perigee bucket, 25 km LEO profile, 5° inclination profile. Informational, not a risk metric.', example: '/orbit/density' },64    ],65  },66  {67    title: 'Orbit (batch)',68    endpoints: [69      { method: 'GET', path: '/orbit/positions', summary: 'Positions of every tracked object at t0 and t0+step, as compact parallel arrays (see below).', params: ['t', 'step'], example: '/orbit/positions?step=60', bucket: 'positions' },70    ],71  },72  {73    title: 'Transparency',74    endpoints: [75      { method: 'GET', path: '/sources', summary: 'Source catalog with license, attribution, connectors, snapshot and provenance counts, freshness.', example: '/sources' },76      { method: 'GET', path: '/sources/status', summary: 'Connector health (last success, schedule, failures, circuit breaker) and orbital element age.', example: '/sources/status' },77      { method: 'GET', path: '/methodology', summary: 'Versioned metric definitions, constellation rules and owner-code table.', example: '/methodology' },78      { method: 'GET', path: '/health', summary: 'Liveness + component checks (also at /health without the prefix).', example: '/health' },79    ],80  },81];8283export const RATE_LIMITS: { bucket: string; perMinute: number; applies: string }[] = [84  { bucket: 'default', perMinute: 600, applies: 'every endpoint not listed below' },85  { bucket: 'search', perMinute: 120, applies: '/search, /search/suggest' },86  { bucket: 'position', perMinute: 240, applies: '/satellites/{ident}/position, /live' },87  { bucket: 'positions', perMinute: 60, applies: '/orbit/positions (batch)' },88];89