Advanced Satellite Operations API

Base path: /v1
Authentication: Required (JWT Bearer Token)
Content-Type: application/json

Overview

The Advanced Satellite Operations API provides comprehensive satellite analysis capabilities including pass analysis, maneuver detection, and query history management. All operations support asynchronous processing with task status tracking.

Key Features

Pass Analysis: Analyze satellite passes over points, trajectories, or polygon areas
Maneuver Detection: Detect orbital maneuvers between specified dates
Query History: Track and manage all API requests with alert functionality
Async Processing: Long-running operations with real-time status updates
GeoJSON Support: Full GeoJSON Feature support for ground locations

Authentication

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

Authorization: Bearer YOUR_JWT_TOKEN

Pass Analyzer API

Endpoint

POST /v1/pass_analyzer/

Request Schema

{
  "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:

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
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
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
- Area constraint: Maximum area of 500 square kilometers
- Use case: Regional coverage analysis, area monitoring, coverage planning
Area Validation:
- The API automatically calculates the polygon area using geodesic calculations
- Areas exceeding 500 km² will return a validation error
- This limit ensures reasonable processing times and resource usage
- For larger areas, consider using multiple smaller polygons or point-based analysis

`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

Examples:

[
  "2024-01-15T12:00:00+00:00",
  "2024-01-15T18:00:00+00:00"
]

`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

Examples:

[25544, 37820, 43013]

`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 Schema

Initial Response (Task Created)

{
  "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"
}

Task Status Response

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed|pending|in_progress|failed",
  "progress": 0.75,
  "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"
}

Status Codes

200 OK: Task created successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or missing JWT token
422 Unprocessable Entity: Validation errors

Error Responses

{
  "detail": "Validation error message",
  "status_code": 422
}

Maneuver Detection API

Endpoint

POST /v1/maneuver_detection/

Request Schema

{
  "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 Schema

{
  "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 API

Get Query History

Endpoint

GET /v1/query_history/

Response Schema

{
  "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/{history_id}/alert

Request Schema

{
  "alert": true
}

Field Specifications

`history_id` (Path Parameter)

Query history entry ID to update.

Specifications:

Type: integer
Range: Positive integer
Validation: Must exist and belong to authenticated user

`alert` (Required)

Alert flag for the query history entry.

Specifications:

Type: boolean
Purpose: Mark important entries for attention
Default: false

Response Schema

{
  "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"
}

Task Status API

Endpoint

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

Path Parameters

`task_id` (Required)

Task identifier returned from pass analyzer or maneuver detection requests.

Specifications:

Type: string
Format: UUID v4
Validation: Must be valid task ID

Response Schema

{
  "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 Handling

Common Error Codes

400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or missing JWT token
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Error Response Format

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

Validation Errors

{
  "detail": [
    {
      "loc": ["body", "ground_location", "geometry", "coordinates"],
      "msg": "Point geometry must have exactly 2 coordinates",
      "type": "value_error"
    }
  ]
}

Common Validation Errors

Geometry Validation
- Point: Must have exactly 2 coordinates [longitude, latitude]
- LineString: Must have at least 2 coordinate pairs
- Polygon: Must have at least 3 coordinate pairs per ring
Coordinate Validation
- Longitude: Must be between -180 and 180 degrees
- Latitude: Must be between -90 and 90 degrees
Polygon Area Validation
- Area Limit: Maximum area of 500 square kilometers
- Error Message: "Polygon area (X.XX km²) exceeds the maximum allowed area of 500 km². Please use a smaller polygon."
Date Validation
- Minimum: At least 2 dates required
- Order: Dates must be strictly increasing
- Range: Not older than February 4, 2025
Elevation Constraints
- Relationship: min_elv_constraint must be less than max_elv_constraint
- Range: Both values must be between 0 and 90 degrees

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

Best Practices

Performance Optimization

Time Resolution: Use appropriate time resolution for your use case
- High detail: 10-30 seconds
- Standard: 60 seconds
- Large areas: 300-600 seconds
Date Ranges: Keep date ranges reasonable
- Pass analysis: 1-7 days recommended
- Maneuver detection: 7-30 days recommended
Satellite Count: Limit to essential satellites
- Pass analysis: 1-50 satellites
- Maneuver detection: 1-20 satellites
Polygon Size: Keep polygon areas reasonable
- Maximum: 500 square kilometers
- Recommended: 100-300 square kilometers for optimal performance
- Large areas: Consider using multiple smaller polygons or point-based analysis

Data Management

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

Integration Tips

Async Processing: Always check task status for long-running operations
Error Handling: Implement proper error handling for all API calls
Retry Logic: Implement exponential backoff for failed requests
Caching: Cache task results for frequently accessed data

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/123/alert" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Overview​

Key Features​

Authentication​

Pass Analyzer API​

Endpoint​

Request Schema​

Field Specifications​

ground_location (Required)​

date (Required)​

time_resolution (Required)​

min_elv_constraint (Required)​

max_elv_constraint (Required)​

norad_ids (Required)​

name (Optional)​

Response Schema​

Initial Response (Task Created)​

Task Status Response​

Status Codes​

Error Responses​

Maneuver Detection API​

Endpoint​

Request Schema​

Field Specifications​

norad_ids (Required)​

start_date (Required)​

end_date (Required)​

maxdv (Optional)​

mindv (Optional)​

maneuver_detection_method (Optional)​

force_data_source (Optional)​

name (Optional)​

Response Schema​

Query History API​

Get Query History​

Endpoint​

Response Schema​

Update Query History Alert​

Endpoint​

Request Schema​

Field Specifications​

history_id (Path Parameter)​

alert (Required)​

Response Schema​

Task Status API​

Endpoint​

Path Parameters​

task_id (Required)​

Response Schema​

Error Handling​

Common Error Codes​

Error Response Format​

Validation Errors​

Common Validation Errors​

Rate Limiting​

Best Practices​

Performance Optimization​

Data Management​

Integration Tips​

Examples​

Complete Pass Analysis Workflow​

Maneuver Detection Example​

Overview

Key Features

Authentication

Pass Analyzer API

Endpoint

Request Schema

Field Specifications

`ground_location` (Required)

`date` (Required)

`time_resolution` (Required)

`min_elv_constraint` (Required)

`max_elv_constraint` (Required)

`norad_ids` (Required)

`name` (Optional)

Response Schema

Initial Response (Task Created)

Task Status Response

Status Codes

Error Responses

Maneuver Detection API

Endpoint

Request Schema

Field Specifications

`norad_ids` (Required)

`start_date` (Required)

`end_date` (Required)

`maxdv` (Optional)

`mindv` (Optional)

`maneuver_detection_method` (Optional)

`force_data_source` (Optional)

`name` (Optional)

Response Schema

Query History API

Get Query History

Endpoint

Response Schema

Update Query History Alert

Endpoint

Request Schema

Field Specifications

`history_id` (Path Parameter)

`alert` (Required)

Response Schema

Task Status API

Endpoint

Path Parameters

`task_id` (Required)

Response Schema

Error Handling

Common Error Codes

Error Response Format

Validation Errors

Common Validation Errors

Rate Limiting

Best Practices

Performance Optimization

Data Management

Integration Tips

Examples

Complete Pass Analysis Workflow

Maneuver Detection Example