Skip to main content

API Reference

The SSA Backend API is organized around REST principles with predictable resource-oriented URLs, JSON-encoded request/response bodies, and standard HTTP response codes. All endpoints require JWT authentication and support both live and test modes.

Base URL​

http://localhost:85

Authentication​

JWT Bearer Token Authentication​

All API requests require a valid JWT Bearer token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Token Types​

  • Live Mode Tokens: Issued for production users, affect live data
  • Test Mode Tokens: Issued for test users, don't affect production data

Security Requirements​

  • HTTPS Required: All production requests must use HTTPS
  • Token Security: Keep tokens secure, don't share in public repositories or client-side code
  • Token Expiration: Tokens expire after 1 hour, use refresh tokens to renew

Common Response Formats​

Success Response​

{
  "data": {...},
  "message": "Operation completed successfully",
  "status": "success"
}

Error Response​

{
  "detail": "Error message description",
  "status_code": 400
}

Validation Error Response​

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "Validation error message",
      "type": "value_error"
    }
  ]
}

Core Endpoints​

Root Endpoint​

Endpoint: GET /

Description: Basic health check and application status.

Authentication: Required (JWT Bearer Token)

Response (200 OK):

{
  "message": "SSA Backend API is running",
  "version": "1.0.0",
  "status": "healthy",
  "timestamp": 1705315200.0
}

Health Check​

Endpoint: GET /health

Description: Detailed health check with system information.

Authentication: Required (JWT Bearer Token)

Response (200 OK):

{
  "status": "healthy",
  "timestamp": 1705315200.0,
  "version": "1.0.0",
  "services": {
    "api": "healthy",
    "database": "unknown",
    "logging": "healthy"
  },
  "system": {
    "hostname": "server-hostname",
    "platform": "Linux",
    "python_version": "3.11.0"
  }
}

Metrics​

Endpoint: GET /metrics

Description: Prometheus metrics endpoint for monitoring and alerting.

Authentication: Not required

Response: Prometheus-formatted metrics text

Example Response:

# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",endpoint="/v1/satellites"} 1234

# HELP http_request_duration_seconds Duration of HTTP requests
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.1"} 1000

Debug Endpoints​

Active Users Tracking​

Endpoint: GET /debug/active-users

Description: Debug information about active users tracking.

Authentication: Required (JWT Bearer Token)

Response (200 OK):

{
  "total_active_users": 5,
  "cleanup_interval_seconds": 300,
  "user_timeout_seconds": 1800,
  "current_time": 1705315200.0,
  "active_users": {
    "123": {
      "last_activity": 1705314900.0,
      "time_since_activity_seconds": 300.0,
      "time_since_activity_minutes": 5.0,
      "will_be_removed_in_seconds": 1500.0
    }
  }
}

Authentication Endpoints​

Register User​

Endpoint: POST /auth/register

Description: Register a new user account.

Request Body:

{
  "email": "[email protected]",
  "name": "John Doe",
  "password": "P@ssw0rd!Strong"
}

Field Specifications:

  • email (Required): string
    • Format: Valid email address
    • Length: 3-100 characters
    • Must be unique
  • name (Required): string
    • Length: 1-100 characters
    • Must be unique
  • password (Required): string
    • Length: 8-128 characters
    • Must contain at least one uppercase letter, one lowercase letter, one number, and one special character

Response (201 Created):

{
  "id": 123,
  "email": "[email protected]",
  "name": "John Doe",
  "is_active": true,
  "is_admin": false,
  "is_staff": false,
  "is_superuser": false,
  "date_joined": "2024-01-15T12:00:00Z"
}

Error Responses:

  • 400 Bad Request: Invalid request data
  • 409 Conflict: Email or name already exists
  • 422 Unprocessable Entity: Validation errors

Login​

Endpoint: POST /auth/login

Description: Authenticate user and obtain JWT tokens.

Request Body:

{
  "email": "[email protected]",
  "password": "P@ssw0rd!Strong"
}

Field Specifications:

  • email (Required): string - User's email address
  • password (Required): string - User's password

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": 123,
    "email": "[email protected]",
    "name": "John Doe",
    "is_active": true,
    "is_admin": false
  }
}

Error Responses:

  • 401 Unauthorized: Invalid credentials
  • 422 Unprocessable Entity: Validation errors

Refresh Token​

Endpoint: POST /auth/refresh

Description: Refresh expired access token using refresh token.

Request Body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Field Specifications:

  • refresh_token (Required): string - Valid refresh token

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Error Responses:

  • 401 Unauthorized: Invalid or expired refresh token
  • 422 Unprocessable Entity: Validation errors

Advanced Satellite Operations​

Pass Analyzer​

Endpoint: POST /v1/pass_analyzer/

Description: Analyze satellite passes over ground locations (point, trajectory, or polygon).

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "ground_location": {
    "type": "Feature",
    "geometry": {
      "type": "Point|LineString|Polygon",
      "coordinates": [...]
    },
    "properties": {}
  },
  "date": ["2024-01-15T12:00:00+00:00", "2024-01-15T18:00:00+00:00"],
  "time_resolution": 60,
  "min_elv_constraint": 10,
  "max_elv_constraint": 90,
  "norad_ids": [25544, 37820, 43013],
  "name": "Optional analysis name"
}

Field Specifications:

ground_location (Required)​

GeoJSON Feature object defining the ground location for analysis.

Supported Geometry Types:

  1. Point Geometry

    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [longitude, latitude]
      },
      "properties": {}
    }
    • coordinates: [number, number] - [longitude, latitude] in decimal degrees
    • longitude: -180 to 180 degrees
    • latitude: -90 to 90 degrees
    • Use case: Fixed ground station, observatory, monitoring location

  2. LineString Geometry

    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [[longitude1, latitude1], [longitude2, latitude2], ...]
      },
      "properties": {}
    }
    • coordinates: [[number, number], ...] - Array of [longitude, latitude] pairs
    • Minimum points: 2 coordinate pairs
    • Use case: Mobile ground station, aircraft trajectory, satellite tracking vehicle

  3. Polygon Geometry

    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[longitude1, latitude1], [longitude2, latitude2], ...]]
      },
      "properties": {}
    }
    • coordinates: [[[number, number], ...]] - Array of coordinate rings
    • Minimum vertices: 3 coordinate pairs per ring
    • Use case: Regional coverage analysis, area monitoring, coverage planning

date (Required)​

Array of datetime strings in ISO 8601 format with timezone.

Specifications:

  • Type: string[]
  • Minimum length: 2 dates
  • Format: YYYY-MM-DDTHH:MM:SS+00:00 or YYYY-MM-DDTHH:MM:SSZ
  • Order: Must be strictly increasing (chronological)
  • Timezone: UTC recommended, timezone offset required
  • Range: Not older than February 4, 2025

time_resolution (Required)​

Time resolution in seconds for analysis calculations.

Specifications:

  • Type: integer
  • Range: 1 to 3600 seconds (1 second to 1 hour)
  • Recommended: 60 seconds (1 minute) for most use cases
  • High resolution: 10-30 seconds for detailed analysis
  • Low resolution: 300-600 seconds for large area analysis

min_elv_constraint (Required)​

Minimum elevation constraint in degrees.

Specifications:

  • Type: integer
  • Range: 0 to 90 degrees
  • Recommended: 10-15 degrees for most applications
  • Low elevation: 5-10 degrees for horizon tracking
  • High elevation: 20-30 degrees for quality observations

max_elv_constraint (Required)​

Maximum elevation constraint in degrees.

Specifications:

  • Type: integer
  • Range: 0 to 90 degrees
  • Must be: Greater than min_elv_constraint
  • Recommended: 85-90 degrees for most applications
  • Zenith tracking: 90 degrees for overhead passes

norad_ids (Required)​

List of NORAD IDs to analyze.

Specifications:

  • Type: integer[]
  • Range: 1 to 100 satellites per request
  • Format: Array of integers
  • Validation: Must be valid NORAD IDs
  • Duplicates: Not allowed

name (Optional)​

Optional name for the analysis request.

Specifications:

  • Type: string
  • Length: 1 to 255 characters
  • Purpose: Helps identify and organize requests
  • Included in: Responses and task status

Response (200 OK):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status_url": "/v1/pass_analyzer_callback/550e8400-e29b-41d4-a716-446655440000/status/",
  "status": "pending",
  "name": "New York Ground Station Analysis"
}

Error Responses:

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing JWT token
  • 422 Unprocessable Entity: Validation errors

Maneuver Detection​

Endpoint: POST /v1/manuaver/

Note: This endpoint has a typo in the URL ("manuaver" instead of "maneuver") but is kept for backward compatibility.

Description: Detect orbital maneuvers for specified satellites between dates.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "norad_ids": [25544, 37820],
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "maxdv": 50.0,
  "mindv": 0.01,
  "maneuver_detection_method": "ml",
  "force_data_source": null,
  "name": "ISS and GPS Maneuver Analysis"
}

Field Specifications:

norad_ids (Required)​

List of NORAD IDs to analyze for maneuvers.

Specifications:

  • Type: integer[]
  • Range: 1 to 100 satellites per request
  • Format: Array of integers
  • Validation: Must be valid NORAD IDs

start_date (Required)​

Start date for maneuver detection period.

Specifications:

  • Type: string
  • Format: YYYY-MM-DD
  • Range: Not older than 30 days from current date
  • Timezone: UTC

end_date (Required)​

End date for maneuver detection period.

Specifications:

  • Type: string
  • Format: YYYY-MM-DD
  • Range: Must be after start_date
  • Maximum period: 30 days
  • Timezone: UTC

maxdv (Optional)​

Maximum delta-V deviation threshold in m/s.

Specifications:

  • Type: float
  • Default: 50.0
  • Range: 0.1 to 1000.0
  • Unit: meters per second

mindv (Optional)​

Minimum delta-V deviation threshold in m/s.

Specifications:

  • Type: float
  • Default: 0.01
  • Range: 0.001 to 100.0
  • Unit: meters per second

maneuver_detection_method (Optional)​

Detection method to use.

Specifications:

  • Type: string
  • Default: "ml"
  • Options:
    • "ml": Machine learning-based detection
    • "inc": Inclination-based detection
    • "sma": Semi-major axis-based detection

force_data_source (Optional)​

Force specific data source for TLE data.

Specifications:

  • Type: string|null
  • Default: null (auto-select)
  • Options:
    • "spacetrack": Use SpaceTrack API
    • "timescaledb": Use local TimescaleDB
    • null: Auto-select based on availability

name (Optional)​

Optional name for the maneuver detection request.

Specifications:

  • Type: string
  • Length: 1 to 255 characters

Response (200 OK):

{
  "norad_ids": [25544, 37820],
  "date_range": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  },
  "maneuvers": [
    {
      "date": "2024-01-15T12:00:00Z",
      "delta_v": 15.5,
      "maneuver_type": "inc",
      "orbital_elements_before": {
        "semi_major_axis": 6778.137,
        "eccentricity": 0.0001,
        "inclination": 51.6423
      },
      "orbital_elements_after": {
        "semi_major_axis": 6778.137,
        "eccentricity": 0.0001,
        "inclination": 51.6423
      },
      "sgp4_delta_v_mps": 15.5,
      "maneuver_time_utc": "2024-01-15T12:00:00Z",
      "position_error_m": 150.0,
      "dv_vector_kmps": [0.015, 0.0, 0.0],
      "time_series_data": {}
    }
  ],
  "total_maneuvers": 1,
  "data_source": "spacetrack_api",
  "name": "ISS and GPS Maneuver Analysis",
  "time_series_plot_data": {},
  "Maneuver_magnitude": [15.5],
  "Epoch_start": ["2024-01-15T12:00:00Z"],
  "Epoch_end": ["2024-01-15T12:00:00Z"],
  "Maneuver_type": "inc",
  "probability": [0.95]
}

Query History​

Get Query History​

Endpoint: GET /v1/query_history/

Description: Retrieve query history for the authenticated user with optional filtering.

Authentication: Required (JWT Bearer Token)

Query Parameters:

  • attributes (Optional): string - Comma-separated list of attributes to return
  • alert (Optional): boolean - Filter by alert value (true/false)

Available Attributes:

  • id, user_id, user_email, request_type, request_body
  • response_body, task_id, status, alert, created_at, updated_at

Response (200 OK):

{
  "history": [
    {
      "id": 123,
      "type": "pass_analyzer",
      "user_email": "[email protected]",
      "request_body": {
        "norad_ids": [25544, 37820],
        "date": ["2024-01-15T12:00:00+00:00", "2024-01-15T18:00:00+00:00"],
        "time_resolution": 60,
        "min_elv_constraint": 10,
        "max_elv_constraint": 90,
        "name": "New York Analysis"
      },
      "response_body": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "result": {...}
      },
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "alert": false,
      "created_at": "2024-01-15T12:00:00.000Z",
      "updated_at": "2024-01-15T12:05:45.000Z"
    }
  ],
  "total_count": 1
}

Get Query History by ID​

Endpoint: GET /v1/query_history/{history_id}

Description: Get a specific query history entry by ID for the current user.

Authentication: Required (JWT Bearer Token)

Path Parameters:

  • history_id (Required): integer - Query history entry ID

Query Parameters:

  • attributes (Optional): string - Comma-separated list of attributes to return

Response (200 OK):

{
  "id": 123,
  "user_email": "[email protected]",
  "request_type": "pass_analyzer",
  "status": "completed",
  "alert": false,
  "created_at": "2024-01-15T12:00:00.000Z"
}

Description: Retrieve query history for the authenticated user.

Authentication: Required (JWT Bearer Token)

Query Parameters: None

Response (200 OK):

{
  "history": [
    {
      "id": 123,
      "type": "pass_analyzer",
      "user_email": "[email protected]",
      "request_body": {
        "norad_ids": [25544, 37820],
        "date": ["2024-01-15T12:00:00+00:00", "2024-01-15T18:00:00+00:00"],
        "time_resolution": 60,
        "min_elv_constraint": 10,
        "max_elv_constraint": 90,
        "name": "New York Analysis"
      },
      "response_body": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "result": {...}
      },
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "alert": false,
      "created_at": "2024-01-15T12:00:00.000Z",
      "updated_at": "2024-01-15T12:05:45.000Z"
    }
  ],
  "total_count": 1
}

Update Query History Alert​

Endpoint: PUT /v1/query_history/alert

Description: Update alert field for a query history entry by history_id or task_id.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "history_id": 123,
  "alert": true
}

Field Specifications:

  • history_id (Optional): integer - Query history entry ID
  • task_id (Optional): string - Task identifier (UUID)
  • alert (Required): boolean - Alert flag value

Note: Either history_id or task_id must be provided.

Response (200 OK):

{
  "id": 123,
  "user_email": "[email protected]",
  "request_type": "pass_analyzer",
  "alert": true,
  "updated_at": "2024-01-15T12:00:00.000Z",
  "message": "Query history entry updated successfully"
}

Description: Update alert flag for a query history entry.

Authentication: Required (JWT Bearer Token)

Path Parameters:

  • history_id (Required): integer - Query history entry ID

Request Body:

{
  "alert": true
}

Field Specifications:

  • alert (Required): boolean - Alert flag for the query history entry

Response (200 OK):

{
  "id": 123,
  "user_email": "[email protected]",
  "request_type": "pass_analyzer",
  "alert": true,
  "updated_at": "2024-01-15T12:00:00.000Z",
  "message": "Query history entry updated successfully"
}

Error Responses:

  • 404 Not Found: Query history entry not found or access denied
  • 401 Unauthorized: Invalid or missing JWT token
  • 422 Unprocessable Entity: Validation errors

Task Status​

Endpoint: GET /v1/pass_analyzer_callback/{task_id}/status/

Description: Get status of an async task (pass analyzer or maneuver detection).

Authentication: Required (JWT Bearer Token)

Path Parameters:

  • task_id (Required): string - Task identifier (UUID v4)

Response (200 OK):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed|pending|in_progress|failed",
  "progress": 1.0,
  "result": {
    "Access_norad": [[1, 0, 1], [0, 1, 0], [1, 1, 1]],
    "duration_norad": [[1800.0, 0.0, 1200.0], [0.0, 2400.0, 0.0], [900.0, 1500.0, 2100.0]],
    "timestamp": [
      [["2024-01-15T12:30:00+00:00", "2024-01-15T13:00:00+00:00"]],
      [["2024-01-15T13:45:00+00:00", "2024-01-15T14:25:00+00:00"]],
      [["2024-01-15T12:15:00+00:00", "2024-01-15T12:30:00+00:00"]]
    ],
    "blindstamp": [["2024-01-15T12:00:00+00:00", "2024-01-15T12:15:00+00:00"]]
  },
  "error": null,
  "name": "New York Ground Station Analysis",
  "created_at": "2024-01-15T12:00:00.000Z",
  "updated_at": "2024-01-15T12:05:45.000Z"
}

Error Responses:

  • 404 Not Found: Task not found
  • 401 Unauthorized: Invalid or missing JWT token

Satellite Operations​

Endpoint: POST /v1/norad_db

Description: Search NORAD database with comprehensive filters and attribute selection.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "country_operator": ["USA", "RUSSIA"],
  "detailed_purpose": ["Earth Observation", "Navigation"],
  "constellation_name": ["GPS", "GLONASS"],
  "attributes": ["norad_id", "cospar_id", "satellite_name", "country_operator"]
}

Field Specifications:

  • country_operator (Required): string[] - List of country operators
  • detailed_purpose (Optional): string[] - Filter by detailed purpose
  • constellation_name (Optional): string[] - Filter by constellation
  • attributes (Optional): string[] - Specific columns to return

Available Attributes:

  • id, norad_id, cospar_id, constellation_name
  • current_official_name_of_satellite, country_operator
  • class_of_orbit, purpose, detailed_purpose
  • date_of_launch, known_mass, expected_lifetime
  • apogee_km, perigee_km, eccentricity, inclination_degrees
  • period_minutes, longitude_of_geo_degrees
  • dry_mass_kg, power_watts, contractor, launch_site
  • launch_vehicle, comments, source
  • sensor_gsd_pan_m, sensor_gsd_ms_m, sensor_swath_km

Get Current Satellite Position​

Endpoint: POST /v1/get_current_position

Description: Get current satellite position and trajectory for the next 1.5 hours.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "norad_ids": [25544, 37820]
}

Field Specifications:

  • norad_ids (Required): integer[] - List of NORAD IDs

Get Constellation Data​

Endpoint: POST /v1/get_constellation

Description: Get unique constellation names for given countries.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "country_operator": ["USA", "RUSSIA"]
}

Field Specifications:

  • country_operator (Required): string[] - List of country operators

Get Detailed Purpose Data​

Endpoint: POST /v1/get_detailed_purpose

Description: Get unique detailed purpose names for given countries.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "country_operator": ["USA", "RUSSIA"]
}

Field Specifications:

  • country_operator (Required): string[] - List of country operators

Get Satellite Types​

Endpoint: POST /v1/get_satellite_types

Description: Get unique satellite types (EO, SAR, ELINT, Unknown sensor) for given countries.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "country_operator": ["USA", "RUSSIA"]
}

Field Specifications:

  • country_operator (Required): string[] - List of country operators

Endpoint: POST /v1/search

Description: Flexible search NORAD database with search text and field specification.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "search_text": "GPS",
  "search_field": "constellation_name",
  "attributes": ["norad_id", "satellite_name", "country_operator"]
}

Field Specifications:

  • search_text (Required): string - Text to search for
  • search_field (Required): string - Field to search in
  • attributes (Optional): string[] - Specific columns to return

Available Search Fields:

  • norad_id, cospar_id, constellation_name
  • current_official_name_of_satellite, country_operator
  • operator, users, class_of_orbit, purpose
  • detailed_purpose, date_of_launch, known_mass
  • contractor, launch_site, launch_vehicle

List Satellites​

Endpoint: GET /v1/satellites/

Description: Retrieve list of satellites with optional filtering.

Authentication: Required (JWT Bearer Token)

Query Parameters:

  • limit (Optional): integer - Number of results to return (default: 100, max: 1000)
  • offset (Optional): integer - Number of results to skip (default: 0)
  • search (Optional): string - Search term for satellite name or NORAD ID
  • constellation (Optional): string - Filter by constellation name
  • country (Optional): string - Filter by country/operator

Response (200 OK):

{
  "satellites": [
    {
      "norad_id": 25544,
      "cospar_id": "1998-067A",
      "constellation_name": "ISS",
      "satellite_name_official": "International Space Station",
      "country_org_un_registry": "United States",
      "country_operator": "United States",
      "operator": "NASA",
      "users": "Government",
      "class_of_orbit": "LEO",
      "type_of_orbit": "ISS",
      "purpose": "Human Spaceflight",
      "detailed_purpose": "Space Station",
      "date_of_launch": "1998-11-20",
      "known_mass": "419725",
      "expected_lifetime": "2030"
    }
  ],
  "total_count": 1,
  "limit": 100,
  "offset": 0
}

News Operations​

Get Latest News​

Endpoint: GET /v1/news/latest

Description: Retrieve the latest news articles from all sources.

Authentication: Required (JWT Bearer Token)

Query Parameters:

  • limit (Optional): integer - Number of articles to return (1-100, default: 10)
  • source (Optional): string - Filter by news source

Response (200 OK):

[
  {
    "id": "123",
    "title": "Satellite Launch Successful",
    "short_description": "New satellite launched into orbit",
    "source": "LaunchLibrary2",
    "mission_name": "Satellite Mission",
    "date": "2024-01-15T12:00:00Z",
    "url": "https://example.com/article",
    "slug": "satellite-launch-successful",
    "last_updated": "2024-01-15T12:00:00Z",
    "country_code": "USA",
    "mission_description": "Mission description",
    "off_url": "https://example.com/official",
    "insertion_time": "2024-01-15T12:00:00Z",
    "created_at": "2024-01-15T12:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
]

Get News by Time Range​

Endpoint: GET /v1/news/timerange

Description: Retrieve news articles within a specified time range.

Authentication: Required (JWT Bearer Token)

Query Parameters:

  • start_date (Required): datetime - Start date (ISO format)
  • end_date (Required): datetime - End date (ISO format)
  • page (Optional): integer - Page number (default: 1)
  • size (Optional): integer - Page size (1-100, default: 10)
  • source (Optional): string - Filter by news source

Response (200 OK):

{
  "news": [...],
  "total": 50,
  "page": 1,
  "size": 10,
  "has_next": true,
  "has_prev": false
}

Search News​

Endpoint: GET /v1/news/search

Description: Search news articles by title and description with multiple search terms.

Authentication: Required (JWT Bearer Token)

Query Parameters:

  • q (Required): string - Search term(s), comma-separated for multiple terms
  • search_mode (Optional): string - Search mode: 'AND', 'OR', 'EXACT' (default: 'OR')
  • page (Optional): integer - Page number (default: 1)
  • size (Optional): integer - Page size (1-100, default: 10)
  • source (Optional): string - Filter by news source

Search Modes:

  • AND: All search terms must be present
  • OR: Any search term can be present
  • EXACT: Treats query as exact phrase

Example: ?q=satellite,launch,space&search_mode=AND&page=1&size=20

Endpoint: POST /v1/news/search/advanced

Description: Advanced search with multiple search terms, filters, and search modes.

Authentication: Required (JWT Bearer Token)

Query Parameters:

  • search_terms (Required): string[] - List of search terms
  • search_mode (Optional): string - Search mode: 'AND', 'OR', 'EXACT' (default: 'OR')
  • page (Optional): integer - Page number (default: 1)
  • size (Optional): integer - Page size (1-100, default: 10)
  • source (Optional): string - Filter by news source
  • country_code (Optional): string - Filter by country code
  • mission_name (Optional): string - Filter by mission name
  • start_date (Optional): datetime - Filter by start date
  • end_date (Optional): datetime - Filter by end date

Response (200 OK):

{
  "news": [...],
  "total": 25,
  "page": 1,
  "size": 10,
  "has_next": true,
  "has_prev": false
}

Error Handling​

Common HTTP Status Codes​

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing JWT token
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource already exists
  • 422 Unprocessable Entity: Validation errors
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Error Response Format​

{
  "detail": "Error message description",
  "status_code": 400
}

Validation Error Format​

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "Validation error message",
      "type": "value_error"
    }
  ]
}

Rate Limiting​

  • Pass Analyzer: 10 requests per minute per user
  • Maneuver Detection: 5 requests per minute per user
  • Query History: 30 requests per minute per user
  • Task Status: 60 requests per minute per user
  • Satellite Operations: 100 requests per minute per user
  • News Operations: 50 requests per minute per user
  • Favorites Operations: 30 requests per minute per user
  • Alerts Operations: 20 requests per minute per user
  • Whitelist Operations: 100 requests per minute per user
  • Authentication: 10 requests per minute per IP

Best Practices​

Performance Optimization​

  1. Time Resolution: Use appropriate time resolution for your use case

    • High detail: 10-30 seconds
    • Standard: 60 seconds
    • Large areas: 300-600 seconds

  2. Date Ranges: Keep date ranges reasonable

    • Pass analysis: 1-7 days recommended
    • Maneuver detection: 7-30 days recommended

  3. Satellite Count: Limit to essential satellites

    • Pass analysis: 1-50 satellites
    • Maneuver detection: 1-20 satellites

Data Management​

  1. Request Naming: Use descriptive names for easy identification
  2. Alert Management: Mark important entries with alerts
  3. History Cleanup: Regularly review and clean up old entries

Integration Tips​

  1. Async Processing: Always check task status for long-running operations
  2. Error Handling: Implement proper error handling for all API calls
  3. Retry Logic: Implement exponential backoff for failed requests
  4. Caching: Cache task results for frequently accessed data
  5. Rate Limiting: Respect rate limits and implement appropriate delays

Favorites Operations​

Add Favorites​

Endpoint: POST /v1/favorites/add

Description: Add satellites to user favorites.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "norad_ids": [25544, 37820, 43013]
}

Field Specifications:

  • norad_ids (Required): integer[] - List of NORAD IDs to add

Response (200 OK):

{
  "message": "Favorites added successfully",
  "added_favorites": [25544, 37820, 43013],
  "already_favorites": [],
  "total_added": 3
}

Remove Favorites​

Endpoint: POST /v1/favorites/remove

Description: Remove satellites from user favorites.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "norad_ids": [25544, 37820]
}

Field Specifications:

  • norad_ids (Required): integer[] - List of NORAD IDs to remove

Response (200 OK):

{
  "message": "Favorites removed successfully",
  "removed_favorites": [25544, 37820],
  "not_found_favorites": [],
  "total_removed": 2
}

Get Favorites​

Endpoint: GET /v1/favorites/list

Description: Get user's favorite satellites.

Authentication: Required (JWT Bearer Token)

Query Parameters:

  • group_id (Optional): integer - Filter by specific group

Response (200 OK):

{
  "favorites": [
    {
      "norad_id": 25544,
      "satellite_name": "International Space Station",
      "country_operator": "United States",
      "group_id": 1,
      "group_name": "Default Group"
    }
  ],
  "total_count": 1
}

Move Favorites​

Endpoint: POST /v1/favorites/move

Description: Move favorites between groups.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "norad_ids": [25544, 37820],
  "target_group_id": 2
}

Field Specifications:

  • norad_ids (Required): integer[] - List of NORAD IDs to move
  • target_group_id (Required): integer - Target group ID

Response (200 OK):

{
  "message": "Favorites moved successfully",
  "moved_favorites": [25544, 37820],
  "target_group_name": "My Group",
  "total_moved": 2
}

Favorite Group Management​

Create Group​

Endpoint: POST /v1/favorites/groups

Description: Create a new favorite group.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "name": "My Group",
  "description": "Personal favorites",
  "color": "#3B82F6"
}

Field Specifications:

  • name (Required): string - Group name (1-100 characters)
  • description (Optional): string - Group description
  • color (Optional): string - Hex color code

Get Groups​

Endpoint: GET /v1/favorites/groups

Description: Get all favorite groups for the user.

Authentication: Required (JWT Bearer Token)

Response (200 OK):

{
  "groups": [
    {
      "id": 1,
      "name": "Default Group",
      "description": "Default favorites group",
      "color": "#3B82F6",
      "favorite_count": 5
    }
  ],
  "total_count": 1
}

Update Group​

Endpoint: PUT /v1/favorites/groups/{group_id}

Description: Update a favorite group.

Authentication: Required (JWT Bearer Token)

Path Parameters:

  • group_id (Required): integer - Group ID to update

Request Body:

{
  "name": "Updated Group Name",
  "description": "Updated description",
  "color": "#EF4444"
}

Delete Group​

Endpoint: DELETE /v1/favorites/groups/{group_id}

Description: Delete a favorite group.

Authentication: Required (JWT Bearer Token)

Path Parameters:

  • group_id (Required): integer - Group ID to delete

Response (200 OK):

{
  "message": "Group deleted successfully",
  "favorites_moved": 3,
  "group_name": "Deleted Group"
}

Alerts Operations​

Get Next Alerts​

Endpoint: GET /v1/alerts/next

Description: Get next alerts (access periods) for the current user within the next 15 minutes.

Authentication: Required (JWT Bearer Token)

Response (200 OK):

{
  "alerts": [
    {
      "satellite_name": "International Space Station",
      "norad_id": 25544,
      "access_periods": [
        {
          "start_time": "2024-01-15T12:00:00Z",
          "end_time": "2024-01-15T12:15:00Z",
          "alert": true
        }
      ]
    }
  ]
}

Slack Notification​

Endpoint: POST /v1/alerts/notify

Description: Send a message payload to Slack via configured webhook.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "text": "Satellite alert: ISS passing overhead in 5 minutes"
}

Field Specifications:

  • text (Optional): string - Plain text message
  • blocks (Optional): array - Slack block kit format

Response (200 OK):

{
  "ok": true
}

Whitelist Operations​

Get Whitelisted Entries​

Endpoint: POST /v1/get_whitelisted_entries

Description: Get whitelisted entries for a specific feature.

Authentication: Required (JWT Bearer Token)

Request Body:

{
  "feature": "country"
}

Field Specifications:

  • feature (Required): string - Feature type (currently supports "country")

Response (200 OK):

{
  "feature": "country",
  "entries": ["USA", "RUSSIA", "CHINA", "EUROPE", "JAPAN", "INDIA"],
  "count": 6,
  "message": "Retrieved 6 whitelisted entries for country"
}

Examples​

Complete Pass Analysis Workflow​

# 1. Submit pass analysis request
curl -X POST "http://localhost:85/v1/pass_analyzer/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ground_location": {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.006, 40.7128]
      },
      "properties": {}
    },
    "date": [
      "2024-01-15T12:00:00+00:00",
      "2024-01-15T18:00:00+00:00"
    ],
    "time_resolution": 60,
    "min_elv_constraint": 10,
    "max_elv_constraint": 90,
    "norad_ids": [25544, 37820, 43013],
    "name": "New York Ground Station Analysis"
  }'

# 2. Check task status
curl -X GET "http://localhost:85/v1/pass_analyzer_callback/550e8400-e29b-41d4-a716-446655440000/status/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 3. Mark as alert if important
curl -X PUT "http://localhost:85/v1/query_history/alert" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "history_id": 123,
    "alert": true
  }'

Maneuver Detection Example​

curl -X POST "http://localhost:85/v1/maneuver_detection/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "norad_ids": [25544, 37820],
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "maxdv": 50.0,
    "mindv": 0.01,
    "maneuver_detection_method": "ml",
    "name": "ISS and GPS Maneuver Analysis"
  }'

Authentication Example​

# 1. Register user
curl -X POST "http://localhost:85/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "password": "P@ssw0rd!Strong"
  }'

# 2. Login
curl -X POST "http://localhost:85/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "P@ssw0rd!Strong"
  }'

# 3. Use access token
curl -X GET "http://localhost:85/v1/satellites/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

News Operations Example​

# Get latest news
curl -X GET "http://localhost:85/v1/news/latest?limit=20&source=LaunchLibrary2" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Search news
curl -X GET "http://localhost:85/v1/news/search?q=satellite,launch&search_mode=AND&page=1&size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Favorites Management Example​

# Add favorites
curl -X POST "http://localhost:85/v1/favorites/add" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "norad_ids": [25544, 37820, 43013]
  }'

# Create group
curl -X POST "http://localhost:85/v1/favorites/groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Satellites",
    "description": "Personal satellite collection",
    "color": "#10B981"
  }'

# Move favorites to group
curl -X POST "http://localhost:85/v1/favorites/move" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "norad_ids": [25544, 37820],
    "target_group_id": 2
  }'

Satellite Operations Example​

# Search NORAD database
curl -X POST "http://localhost:85/v1/norad_db" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country_operator": ["USA", "RUSSIA"],
    "detailed_purpose": ["Earth Observation"],
    "attributes": ["norad_id", "satellite_name", "country_operator", "purpose"]
  }'

# Get current position
curl -X POST "http://localhost:85/v1/get_current_position" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "norad_ids": [25544, 37820]
  }'

Alerts Example​

# Get next alerts
curl -X GET "http://localhost:85/v1/alerts/next" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Send Slack notification
curl -X POST "http://localhost:85/v1/alerts/notify" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Satellite alert: ISS passing overhead in 5 minutes"
  }'