Eve library

REST API Reference

Guide

Revision 1

On this page

Complete endpoint documentation for the Nyx Astronomy API

This document provides detailed documentation for all REST API endpoints.

Table of Contents#

  1. Objects Endpoints
  2. Ephemeris Endpoints
  3. Events Endpoints
  4. Satellites Endpoints
  5. System Endpoints
  6. Common Parameters

Objects Endpoints#

Base path: /api/v1/objects

List Objects#

http
GET /api/v1/objects

Retrieve a paginated list of celestial objects.

Query Parameters:

Parameter Type Default Description
page integer 1 Page number (1-indexed)
limit integer 20 Items per page (max: 100)
type string - Filter by object type
catalog string - Filter by catalog
constellation string - Filter by constellation
minMagnitude float - Minimum brightness (mag)
maxMagnitude float - Maximum brightness (mag)

Object Types: star, planet, moon, asteroid, comet, galaxy, nebula, open_cluster, globular_cluster, planetary_nebula, supernova_remnant

Catalogs: messier, ngc, ic, caldwell, hipparcos, gaia, tycho

Example Request:

bash
curl "https://api.nyx.oshun.io/api/v1/objects?type=nebula&catalog=messier&limit=10"

Example Response:

json
{
  "success": true,
  "data": [
    {
      "id": "M42",
      "name": "Orion Nebula",
      "type": "nebula",
      "catalog": "messier",
      "catalogNumber": 42,
      "aliases": ["NGC 1976", "Great Orion Nebula"],
      "coordinates": {
        "ra": 83.82,
        "dec": -5.39,
        "epoch": "J2000.0"
      },
      "constellation": "Orion",
      "magnitude": 4.0,
      "size": {
        "major": 65.0,
        "minor": 60.0,
        "unit": "arcminutes"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 11,
    "totalPages": 2,
    "hasNext": true,
    "hasPrev": false
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-21T12:00:00.000Z"
  }
}

Search Objects#

http
GET /api/v1/objects/search

Search objects by name, designation, or alias.

Query Parameters:

Parameter Type Required Description
q string Yes Search query
type string No Filter by object type
limit integer No Maximum results (default: 20)

Example Request:

bash
curl "https://api.nyx.oshun.io/api/v1/objects/search?q=andromeda&limit=5"

Example Response:

json
{
  "success": true,
  "data": [
    {
      "id": "M31",
      "name": "Andromeda Galaxy",
      "type": "galaxy",
      "catalog": "messier",
      "magnitude": 3.4,
      "matchScore": 0.98
    },
    {
      "id": "NGC 7662",
      "name": "Blue Snowball Nebula",
      "type": "planetary_nebula",
      "constellation": "Andromeda",
      "magnitude": 8.3,
      "matchScore": 0.45
    }
  ],
  "meta": {
    "requestId": "req_def456",
    "timestamp": "2026-01-21T12:00:00.000Z",
    "query": "andromeda"
  }
}

Get Object#

http
GET /api/v1/objects/{id}

Retrieve detailed information about a specific object.

Path Parameters:

Parameter Type Description
id string Object ID (e.g., "M42", "NGC 7000")

Example Request:

bash
curl "https://api.nyx.oshun.io/api/v1/objects/M42"

Example Response:

json
{
  "success": true,
  "data": {
    "id": "M42",
    "name": "Orion Nebula",
    "type": "nebula",
    "subtype": "emission_nebula",
    "catalog": "messier",
    "catalogNumber": 42,
    "aliases": ["NGC 1976", "LBN 974", "Great Orion Nebula"],
    "coordinates": {
      "ra": 83.8221,
      "dec": -5.3911,
      "raHMS": "05h 35m 17.3s",
      "decDMS": "-05° 23' 28\"",
      "epoch": "J2000.0",
      "galacticL": 209.01,
      "galacticB": -19.38
    },
    "constellation": "Orion",
    "magnitude": {
      "visual": 4.0,
      "surface": 13.0
    },
    "size": {
      "major": 65.0,
      "minor": 60.0,
      "unit": "arcminutes",
      "positionAngle": 0
    },
    "distance": {
      "value": 1344,
      "unit": "light-years",
      "uncertainty": 20
    },
    "physicalSize": {
      "value": 24,
      "unit": "light-years"
    },
    "discovery": {
      "discoverer": "Nicolas-Claude Fabri de Peiresc",
      "year": 1610,
      "method": "telescope"
    },
    "description": "The Orion Nebula is a diffuse nebula situated in the Milky Way, being south of Orion's Belt in the constellation of Orion. It is one of the brightest nebulae, and is visible to the naked eye in the night sky.",
    "observing": {
      "bestSeason": "winter",
      "bestMonths": ["December", "January", "February"],
      "difficulty": "easy",
      "equipment": "visible to naked eye, binoculars recommended"
    },
    "relatedObjects": ["M43", "NGC 1977", "Trapezium Cluster"],
    "links": {
      "wikipedia": "https://en.wikipedia.org/wiki/Orion_Nebula",
      "simbad": "http://simbad.u-strasbg.fr/simbad/sim-id?Ident=M42"
    }
  },
  "meta": {
    "requestId": "req_ghi789",
    "timestamp": "2026-01-21T12:00:00.000Z"
  }
}

Ephemeris Endpoints#

Base path: /api/v1/ephemeris

Calculate Ephemeris#

http
GET /api/v1/ephemeris

Calculate position data for a celestial object over a time range.

Query Parameters:

Parameter Type Required Description
objectId string Yes Object identifier (e.g., "mars")
startTime string No Start time (ISO 8601)
endTime string No End time (ISO 8601)
step string No Time step (e.g., "1h", "10m")
latitude float No Observer latitude (-90 to 90)
longitude float No Observer longitude (-180 to 180)
elevation float No Observer elevation in meters

Supported Objects: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto

Example Request:

bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.nyx.oshun.io/api/v1/ephemeris?objectId=mars&latitude=40.7128&longitude=-74.0060&step=1h"

Example Response:

json
{
  "success": true,
  "data": {
    "objectId": "mars",
    "objectName": "Mars",
    "observer": {
      "latitude": 40.7128,
      "longitude": -74.006,
      "elevation": 0
    },
    "entries": [
      {
        "timestamp": "2026-01-21T12:00:00.000Z",
        "equatorial": {
          "ra": 117.4523,
          "dec": 23.8912,
          "raHMS": "07h 49m 48.6s",
          "decDMS": "+23° 53' 28\"",
          "epoch": "J2000.0"
        },
        "horizontal": {
          "altitude": 45.23,
          "azimuth": 165.78
        },
        "distance": {
          "au": 1.42,
          "km": 212400000,
          "lightMinutes": 11.8
        },
        "magnitude": 0.8,
        "phase": 0.92,
        "elongation": 78.5,
        "isVisible": true
      }
    ]
  },
  "meta": {
    "requestId": "req_eph123",
    "timestamp": "2026-01-21T12:00:00.000Z"
  }
}

Get Current Position#

http
GET /api/v1/ephemeris/position

Get the current position of an object.

Query Parameters:

Parameter Type Required Description
objectId string Yes Object identifier
latitude float No Observer latitude
longitude float No Observer longitude

Example Request:

bash
curl "https://api.nyx.oshun.io/api/v1/ephemeris/position?objectId=jupiter&latitude=40.7128&longitude=-74.0060"

Get Rise/Set Times#

http
GET /api/v1/ephemeris/rise-set

Calculate rise, transit, and set times for an object.

Query Parameters:

Parameter Type Required Description
objectId string Yes Object identifier
latitude float Yes Observer latitude
longitude float Yes Observer longitude
date string No Date (YYYY-MM-DD), default today

Example Request:

bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.nyx.oshun.io/api/v1/ephemeris/rise-set?objectId=mars&latitude=40.7128&longitude=-74.0060&date=2026-01-21"

Example Response:

json
{
  "success": true,
  "data": {
    "objectId": "mars",
    "objectName": "Mars",
    "date": "2026-01-21",
    "observer": {
      "latitude": 40.7128,
      "longitude": -74.006
    },
    "rise": {
      "time": "2026-01-21T22:15:00.000Z",
      "azimuth": 68.5
    },
    "transit": {
      "time": "2026-01-22T03:45:00.000Z",
      "altitude": 58.2,
      "azimuth": 180.0
    },
    "set": {
      "time": "2026-01-22T09:12:00.000Z",
      "azimuth": 291.5
    },
    "isCircumpolar": false,
    "neverRises": false,
    "visibleHours": 10.95
  },
  "meta": {
    "requestId": "req_rs456",
    "timestamp": "2026-01-21T12:00:00.000Z"
  }
}

Events Endpoints#

Base path: /api/v1/events

List Events#

http
GET /api/v1/events

Retrieve astronomical events within a date range.

Query Parameters:

Parameter Type Required Description
startDate string No Start date (ISO 8601)
endDate string No End date (ISO 8601)
types string No Comma-separated event types
importance string No Filter by importance (low/medium/high)
latitude float No Filter by visibility from location
longitude float No Filter by visibility from location
page int No Page number
limit int No Items per page

Event Types:

Category Types
Lunar new_moon, first_quarter, full_moon, last_quarter, supermoon
Eclipse lunar_eclipse, solar_eclipse
Planetary planetary_conjunction, planetary_opposition, greatest_elongation, transit, occultation
Meteor meteor_shower
Seasonal solstice, equinox, perihelion, aphelion
Other comet

Example Request:

bash
curl "https://api.nyx.oshun.io/api/v1/events?types=meteor_shower,lunar_eclipse&startDate=2026-01-01&endDate=2026-12-31"

Example Response:

json
{
  "success": true,
  "data": [
    {
      "id": "evt_2026_perseids",
      "type": "meteor_shower",
      "name": "Perseid Meteor Shower",
      "startTime": "2026-08-11T00:00:00.000Z",
      "endTime": "2026-08-13T23:59:59.000Z",
      "peakTime": "2026-08-12T14:00:00.000Z",
      "description": "One of the best meteor showers, with up to 100 meteors per hour at peak.",
      "importance": "high",
      "visibility": {
        "regions": ["northern_hemisphere"],
        "bestViewing": "After midnight, looking northeast"
      },
      "details": {
        "zenithalHourlyRate": 100,
        "radiant": {
          "constellation": "Perseus",
          "ra": 48,
          "dec": 58
        },
        "parentBody": "109P/Swift-Tuttle"
      }
    },
    {
      "id": "evt_2026_lunar_eclipse_mar",
      "type": "lunar_eclipse",
      "name": "Total Lunar Eclipse",
      "startTime": "2026-03-03T03:00:00.000Z",
      "endTime": "2026-03-03T08:30:00.000Z",
      "peakTime": "2026-03-03T05:45:00.000Z",
      "description": "A total lunar eclipse visible from the Americas, Europe, and Africa.",
      "importance": "high",
      "visibility": {
        "regions": ["americas", "europe", "africa"],
        "bestViewing": "Totality begins at 05:45 UTC"
      },
      "details": {
        "magnitude": 1.15,
        "duration": {
          "total": 330,
          "totality": 58,
          "unit": "minutes"
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  },
  "meta": {
    "requestId": "req_evt789",
    "timestamp": "2026-01-21T12:00:00.000Z",
    "dateRange": {
      "start": "2026-01-01T00:00:00.000Z",
      "end": "2026-12-31T23:59:59.000Z"
    }
  }
}

Get Upcoming Events#

http
GET /api/v1/events/upcoming

Get events for the next 7 days.

Query Parameters:

Parameter Type Default Description
limit int 10 Maximum events to return

Example Request:

bash
curl "https://api.nyx.oshun.io/api/v1/events/upcoming?limit=5"

List Event Types#

http
GET /api/v1/events/types

Get all supported event types and their descriptions.


Get Event Details#

http
GET /api/v1/events/{id}

Get detailed information about a specific event.


Satellites Endpoints#

Base path: /api/v1/satellites

List Satellites#

http
GET /api/v1/satellites

Retrieve a list of tracked satellites.

Query Parameters:

Parameter Type Description
category string Filter by category
status string Filter by status (active/inactive)
search string Search by name
minAltitude float Minimum orbital altitude (km)
maxAltitude float Maximum orbital altitude (km)
page int Page number
limit int Items per page

Satellite Categories: space_station, weather, communication, navigation, scientific, earth_observation, military, amateur, starlink, oneweb, debris

Example Request:

bash
curl "https://api.nyx.oshun.io/api/v1/satellites?category=space_station"

Example Response:

json
{
  "success": true,
  "data": [
    {
      "id": "25544",
      "name": "ISS (ZARYA)",
      "noradId": 25544,
      "intlDesignator": "1998-067A",
      "category": "space_station",
      "status": "active",
      "launchDate": "1998-11-20",
      "orbital": {
        "inclination": 51.6,
        "apogee": 420,
        "perigee": 418,
        "period": 92.9,
        "unit": "km"
      },
      "size": {
        "length": 109,
        "width": 73,
        "mass": 419700,
        "unit": "meters/kg"
      }
    }
  ],
  "meta": {
    "requestId": "req_sat123",
    "timestamp": "2026-01-21T12:00:00.000Z"
  }
}

Get Satellite Categories#

http
GET /api/v1/satellites/categories

List all satellite categories.


Get Pass Predictions#

http
GET /api/v1/satellites/passes

Get satellite pass predictions for an observer location.

Query Parameters:

Parameter Type Required Description
satelliteId string Yes Satellite NORAD ID
latitude float Yes Observer latitude
longitude float Yes Observer longitude
elevation float No Observer elevation (m)
days int No Prediction period (1-14, default 7)
minElevation float No Minimum pass altitude (default 10°)
visibleOnly boolean No Only sunlit passes

Example Request:

bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.nyx.oshun.io/api/v1/satellites/passes?satelliteId=25544&latitude=40.7128&longitude=-74.0060&days=3&minElevation=20"

Example Response:

json
{
  "success": true,
  "data": [
    {
      "satelliteId": "25544",
      "satelliteName": "ISS",
      "passNumber": 1,
      "rise": {
        "time": "2026-01-21T19:30:00.000Z",
        "azimuth": 270.0,
        "azimuthCardinal": "W"
      },
      "transit": {
        "time": "2026-01-21T19:35:00.000Z",
        "altitude": 78.5,
        "azimuth": 180.0,
        "azimuthCardinal": "S"
      },
      "set": {
        "time": "2026-01-21T19:40:00.000Z",
        "azimuth": 90.0,
        "azimuthCardinal": "E"
      },
      "duration": 600,
      "magnitude": -2.5,
      "isVisible": true,
      "visibility": "excellent"
    }
  ],
  "meta": {
    "requestId": "req_pass456",
    "timestamp": "2026-01-21T12:00:00.000Z",
    "observer": {
      "latitude": 40.7128,
      "longitude": -74.006,
      "elevation": 0
    },
    "predictionPeriod": {
      "days": 3,
      "start": "2026-01-21T00:00:00.000Z",
      "end": "2026-01-24T00:00:00.000Z"
    },
    "passCount": 8
  }
}

Get Satellite Details#

http
GET /api/v1/satellites/{id}

Get detailed information about a specific satellite.

Path Parameters:

Parameter Type Description
id string NORAD catalog number

Get Satellite Passes#

http
GET /api/v1/satellites/{id}/passes

Get pass predictions for a specific satellite.


System Endpoints#

Health Check#

http
GET /health

Check API server status.

Response:

json
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-01-21T12:00:00.000Z"
}

API Documentation#

http
GET /api/docs

Interactive Swagger UI documentation.

OpenAPI Specification#

http
GET /api/v1/openapi.json

Machine-readable OpenAPI 3.1.0 specification.


Common Parameters#

Coordinate Parameters#

Used across multiple endpoints:

Parameter Type Range Description
latitude float -90 to 90 Observer latitude (degrees)
longitude float -180 to 180 Observer longitude (degrees)
elevation float -500 to 10000 Elevation above sea level (m)

Date/Time Parameters#

Parameter Format Example
date YYYY-MM-DD 2026-01-21
startTime ISO 8601 2026-01-21T00:00:00.000Z
endTime ISO 8601 2026-01-21T23:59:59.000Z
step Duration string "1h", "10m", "1d"

Pagination Parameters#

Parameter Type Default Max Description
page int 1 - Page number (1-indexed)
limit int 20 100 Items per page

Next: WebSocket Integration#