# Star Magnitude & Distance API
> Stellar magnitude and distance maths as an API, computed locally and deterministically. The magnitude endpoint works the distance modulus, m − M = 5·log₁₀(d/pc) − 5 — give any two of the apparent magnitude m, the absolute magnitude M and the distance and it returns the third, with the distance in parsecs, light-years and astronomical units (the absolute magnitude is the apparent magnitude a star would have at 10 parsecs). The flux endpoint applies Pogson's relation to turn a magnitude difference into a brightness ratio, F₁/F₂ = 10^(0.4·(m₂ − m₁)), where five magnitudes is exactly a hundredfold change in brightness — from two magnitudes, a magnitude difference or a ratio. The parallax endpoint converts a parallax angle into a distance, d(pc) = 1 ÷ p(arcseconds), and back, the geometric method behind the parsec itself. Everything is computed locally and deterministically, so it is instant and private. Ideal for astronomy-education, planetarium, stargazing and science app developers, observing and astrophysics tools, and STEM teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is stellar magnitude and distance; for orbital mechanics use an orbital API and for great-circle distances on Earth a geo-distance API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/starmagnitude-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($15/Mo) — 250,500 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 1,608,000 calls/Mo, 40 req/s

## Endpoints

### Astronomy

#### `GET /v1/flux` — Brightness ratio

**Parameters:**
- `magnitude1` (query, optional, string) — Magnitude of object 1 Example: `1`
- `magnitude2` (query, optional, string) — Magnitude of object 2 Example: `6`
- `delta_mag` (query, optional, string) — Or a magnitude difference
- `ratio` (query, optional, string) — Or a brightness ratio

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/starmagnitude-api/v1/flux?magnitude1=1&magnitude2=6"
```

**Response:**
```json
{
    "data": {
        "note": "Pogson: a difference of 5 magnitudes is exactly a 100× brightness ratio. F₁/F₂ = 10^(0.4·(m₂−m₁)).",
        "inputs": {
            "source": "two_magnitudes",
            "magnitude_difference": 5
        },
        "brightness_ratio": 100,
        "magnitude_difference": 5
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:02.891Z",
        "request_id": "c89b0dff-7b86-4b08-9387-a69018f8c3de"
    },
    "status": "ok",
    "message": "Brightness ratio",
    "success": true
}
```

#### `GET /v1/magnitude` — Distance modulus

**Parameters:**
- `apparent` (query, optional, string) — Apparent magnitude m Example: `10`
- `absolute` (query, optional, string) — Absolute magnitude M Example: `5`
- `distance` (query, optional, string) — Distance (parsecs)
- `distance_ly` (query, optional, string) — Or distance (light-years)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/starmagnitude-api/v1/magnitude?apparent=10&absolute=5"
```

**Response:**
```json
{
    "data": {
        "note": "Distance modulus: m − M = 5·log₁₀(d/pc) − 5. Absolute magnitude is the apparent magnitude at 10 pc.",
        "inputs": {
            "solved_for": "distance"
        },
        "distance_au": 20626480.6,
        "distance_ly": 326.15637769,
        "distance_pc": 100,
        "distance_modulus": 5,
        "absolute_magnitude": 5,
        "apparent_magnitude": 10
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:03.008Z",
        "request_id": "6f92dff5-775d-434a-93ee-d0e2dcd91ae0"
    },
    "status": "ok",
    "message": "Distance modulus",
    "success": true
}
```

#### `GET /v1/parallax` — Parallax distance

**Parameters:**
- `parallax` (query, optional, string) — Parallax (arcseconds) Example: `0.7687`
- `parallax_mas` (query, optional, string) — Or parallax (milliarcseconds)
- `distance` (query, optional, string) — Or distance (pc) for the parallax

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/starmagnitude-api/v1/parallax?parallax=0.7687"
```

**Response:**
```json
{
    "data": {
        "note": "Distance (pc) = 1 / parallax (arcseconds). 1 parsec is the distance at which 1 AU subtends 1 arcsecond.",
        "inputs": {
            "parallax_mas": 768.7,
            "parallax_arcsec": 0.7687
        },
        "distance_au": 268329.395,
        "distance_ly": 4.242960553,
        "distance_pc": 1.300897619
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:03.115Z",
        "request_id": "d515db9a-c1f4-4e4b-baac-648268361fbf"
    },
    "status": "ok",
    "message": "Parallax distance",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/starmagnitude-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Magnitudes are dimensionless (smaller = brighter); distance in parsecs (also reported in light-years and AU). 1 pc = 3.26156 ly = 206264.8 AU.",
        "service": "starmagnitude-api",
        "formulae": {
            "parallax": "d(pc) = 1 / p(arcsec)",
            "brightness_ratio": "F₁/F₂ = 10^(0.4·(m₂−m₁))",
            "distance_modulus": "m − M = 5·log₁₀(d/pc) − 5"
        },
        "endpoints": {
            "GET /v1/flux": "Brightness ratio from a magnitude difference (or the difference from a ratio).",
            "GET /v1/meta": "This document.",
            "GET /v1/parallax": "Distance from a parallax angle, or the parallax for a distance.",
            "GET /v1/magnitude": "Distance modulus — any two of apparent m, absolute M and distance give the third."
        },
        "description": "Stellar magnitude and distance calculator: the distance modulus relating apparent magnitude, absolute magnitude and distance; the brightness ratio between two magnitudes (Pogson); and the distance from a parallax angle."
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:03.215Z",
        "request_id": "ec62c3c0-0478-4816-9d6a-b5d9f4635be4"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/starmagnitude-api
OpenAPI spec: https://www.oanor.com/api/starmagnitude-api/openapi.json