Complete endpoint documentation for the Nyx Astronomy API
This document provides detailed documentation for all REST API endpoints.
Table of Contents#
- Objects Endpoints
- Ephemeris Endpoints
- Events Endpoints
- Satellites Endpoints
- System Endpoints
- Common Parameters
Objects Endpoints#
Base path: /api/v1/objects
List Objects#
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:
curl "https://api.nyx.oshun.io/api/v1/objects?type=nebula&catalog=messier&limit=10"
Example Response:
{
"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#
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:
curl "https://api.nyx.oshun.io/api/v1/objects/search?q=andromeda&limit=5"
Example Response:
{
"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#
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:
curl "https://api.nyx.oshun.io/api/v1/objects/M42"
Example Response:
{
"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#
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:
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:
{
"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#
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:
curl "https://api.nyx.oshun.io/api/v1/ephemeris/position?objectId=jupiter&latitude=40.7128&longitude=-74.0060"
Get Rise/Set Times#
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:
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:
{
"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#
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:
curl "https://api.nyx.oshun.io/api/v1/events?types=meteor_shower,lunar_eclipse&startDate=2026-01-01&endDate=2026-12-31"
Example Response:
{
"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#
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:
curl "https://api.nyx.oshun.io/api/v1/events/upcoming?limit=5"
List Event Types#
GET /api/v1/events/types
Get all supported event types and their descriptions.
Get Event Details#
GET /api/v1/events/{id}
Get detailed information about a specific event.
Satellites Endpoints#
Base path: /api/v1/satellites
List Satellites#
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:
curl "https://api.nyx.oshun.io/api/v1/satellites?category=space_station"
Example Response:
{
"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#
GET /api/v1/satellites/categories
List all satellite categories.
Get Pass Predictions#
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:
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:
{
"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#
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#
GET /api/v1/satellites/{id}/passes
Get pass predictions for a specific satellite.
System Endpoints#
Health Check#
GET /health
Check API server status.
Response:
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2026-01-21T12:00:00.000Z"
}
API Documentation#
GET /api/docs
Interactive Swagger UI documentation.
OpenAPI Specification#
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 |