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 ISS Data

Get the current data and geographic position of the International Space Station (ISS).

Endpoint

GET /api/v1/satellites/iss

Parameters

No parameters required.

Example Request

GET /api/v1/satellites/iss

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
    },
    "geoposition": {
      "latitude": 51.5074,
      "longitude": -0.1278
    }
  },
  "metadata": {
    "total": 1
  }
}

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 currently in range of a specific observer location (above the elevation threshold).

Endpoint

GET /api/v1/satellites/nearby

Query Parameters

Response Modes

The mode parameter controls how much data is returned per satellite.

mode=basic (default)

Returns real-time observation data only — position in the sky, velocity, visibility, and basic identification.

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,
    "altitude": 0,
    "datetime": "2024-01-15T10:30:00.000Z"
  },
  "satellites": [
    {
      "noradId": 25544,
      "name": "ISS (ZARYA)",
      "labels": ["iss"],
      "altitude": 420.5,
      "velocityKmHs": 27576,
      "elevation": 45.2,
      "azimuth": 180.5,
      "range": 450.8,
      "visible": true,
      "observerDaytime": false,
      "satelliteSunlit": true,
      "epoch": "2024-01-15T10:30:00.000Z"
    }
  ]
}

mode=extended

Returns everything from basic mode plus the satellite’s real-time geographic coordinates and orbital parameters. Useful for map rendering or detailed analysis.

Example Request

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

Response Example

{
  "metadata": {
    "total": 2,
    "mode": "extended"
  },
  "observer": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "altitude": 0,
    "datetime": "2024-01-15T10:30:00.000Z"
  },
  "satellites": [
    {
      "noradId": 25544,
      "name": "ISS (ZARYA)",
      "labels": ["iss"],
      "altitude": 420.5,
      "velocityKmHs": 27576,
      "elevation": 45.2,
      "azimuth": 180.5,
      "range": 450.8,
      "visible": true,
      "observerDaytime": false,
      "satelliteSunlit": true,
      "epoch": "2024-01-15T10:30:00.000Z",
      "geoposition": {
        "latitude": 48.3,
        "longitude": 14.7
      },
      "orbitalParams": {
        "inclination": 51.6441,
        "eccentricity": 0.0001234,
        "meanMotion": 15.49123456,
        "orbitalPeriod": 92.68,
        "perigeeHeight": 408.5,
        "apogeeHeight": 418.2,
        "semiMajorAxis": 6785.5
      }
    }
  ]
}

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
• Altitude is measured in kilometers
• Speed is measured in kilometers per hour (velocityKmHs, integer)
• Satellites with elevation below 10° are filtered out
• Visibility depends on satellite illumination and observer’s day/night conditions