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 Satellites List

Get a list of all available satellites in the database with their basic information, TLE data, and orbital parameters.

Endpoint

GET /api/v1/satellites

Parameters

No parameters required.

Example Request

GET /api/v1/satellites

Response Example

{
  "data": [
    {
      "noradId": 25544,
      "name": "ISS (ZARYA)",
      "labels": ["iss"],
      "groups": ["stations"],
      "tle": {
        "line1": "1 25544U 98067A   24015.12345678  .00001234  00000+0  12345-4 0  9999",
        "line2": "2 25544  51.6441 344.0965 0001234 123.4567 234.5678 15.49123456789012"
      },
      "epoch": "2024-01-15T10:30:00.000Z",
      "orbitalParams": {
        "inclination": 51.6441,
        "eccentricity": 0.0001234,
        "meanMotion": 15.49123456,
        "orbitalPeriod": 92.68,
        "perigeeHeight": 408.5,
        "apogeeHeight": 418.2,
        "semiMajorAxis": 6785.5
      }
    },
    {
      "noradId": 20580,
      "name": "HST",
      "labels": ["hubble"],
      "groups": ["space-telescopes"],
      "tle": null,
      "epoch": null,
      "orbitalParams": null
    }
  ],
  "metadata": {
    "total": 2
  }
}

Note: Fields tle, epoch, and orbitalParams can be null if the data is not available for a particular satellite.

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)
• altitude (optional) - Observer’s altitude in meters, defaults to 0
• mode (optional) - Response mode, defaults to “basic”
• azimuth-range-from (optional) - Minimum azimuth angle in degrees (0-360), defaults to 0
• azimuth-range-to (optional) - Maximum azimuth angle in degrees (0-360), defaults to 360
• elevation-threshold (optional) - Minimum elevation angle in degrees (10-90), defaults to 10
• visible-only (optional) - Filter only visible satellites (boolean: true/false), defaults to false

Example Request

GET /api/v1/satellites/nearby?latitude=51.5074&longitude=-0.1278&altitude=100&mode=basic&azimuth-range-from=0&azimuth-range-to=180&elevation-threshold=15&visible-only=false

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