# REST API Reference

> Complete endpoint documentation for the Nyx Astronomy API

This document provides detailed documentation for all REST API endpoints.

## Table of Contents

1. [Objects Endpoints](#objects-endpoints)
2. [Ephemeris Endpoints](#ephemeris-endpoints)
3. [Events Endpoints](#events-endpoints)
4. [Satellites Endpoints](#satellites-endpoints)
5. [System Endpoints](#system-endpoints)
6. [Common Parameters](#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](./websocket.md)
