API Documentation

Get Satellite Geoposition

Get the current geographic position of a satellite by its NORAD ID.

Endpoint

GET /api/v1/satellites/:noradId/geoposition

Parameters

• noradId (path parameter, required) - The NORAD catalog ID of the satellite

Example Request

GET /api/v1/satellites/25544/geoposition

Response Example

{
  "noradId": 25544,
  "name": "ISS (ZARYA)",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "epoch": "2024-01-15T10:30:00.000Z"
}

Get Nearby Satellites

Get a list of satellites that are currently in range of a specific observer location (above 10° elevation).

Endpoint

GET /api/v1/satellites/nearby

Query Parameters

• latitude (required) - Observer’s latitude in decimal degrees (-90 to 90)
• longitude (required) - Observer’s longitude in decimal degrees (-180 to 180)
• mode (optional) - Response mode, defaults to “basic”

Example Request

GET /api/v1/satellites/nearby?latitude=51.5074&longitude=-0.1278&mode=basic

Response Example

{
  "metadata": {
    "total": 2,
    "mode": "basic"
  },
  "observer": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "datetime": "2024-01-15T10:30:00.000Z"
  },
  "satellites": [
    {
      "noradId": 25544,
      "name": "ISS (ZARYA)",
      "labels": ["iss"],
      "elevation": 45.2,
      "azimuth": 180.5,
      "range": 450.8,
      "visible": true,
      "observerDaytime": false,
      "satelliteSunlit": true,
      "epoch": "2024-01-15T10:30:00.000Z"
    },
    {
      "noradId": 20580,
      "name": "HST",
      "labels": ["hubble"],
      "elevation": 30.1,
      "azimuth": 270.3,
      "range": 550.2,
      "visible": false,
      "observerDaytime": false,
      "satelliteSunlit": false,
      "epoch": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Health Check

Health check endpoint to verify API availability and status.

Endpoint

GET /api/v1/service/healthcheck

Parameters

No parameters required.

Example Request

GET /api/v1/service/healthcheck

Response Example

{
  "message": "OK"
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 404 - Not Found (satellite not found)
• 500 - Internal Server Error

Error Response Format

{
  "message": "Error message description",
  "statusCode": 400
}

Notes

• All dates are in UTC format (ISO 8601)
• Coordinates are in decimal degrees
• Elevation angles are in degrees (0-90)
• Azimuth angles are in degrees (0-360)
• Range is measured in kilometers
• Satellites with elevation below 10° are filtered out
• Visibility depends on satellite illumination and observer’s day/night conditions