# Stellar Parallax API
> Stellar-parallax and astrometry maths as an API, computed locally and deterministically. The distance endpoint turns a measured trigonometric parallax angle into a distance using d(pc) = 1/p(arcsec), accepting the parallax in arcseconds or milliarcseconds and returning the distance in parsecs, light-years and astronomical units — a parallax of one arcsecond is one parsec (≈3.2616 light-years) by definition, and Proxima Centauri’s 0.7687-arcsecond parallax gives about 1.30 pc, or 4.24 light-years. The parallax endpoint inverts it, p(arcsec) = 1/d(pc), giving the tiny annual back-and-forth angle a star traces against the background as Earth orbits the Sun. The proper-motion endpoint computes a star’s tangential (transverse) velocity across the sky from its proper motion and distance, v_t = 4.74047·μ(arcsec/yr)·d(pc) km/s — Barnard’s Star, with a proper motion of about 10.39 arcsec/yr at 1.83 pc, races across the sky at roughly 90 km/s. Everything is computed locally and deterministically, so it is instant and private. Ideal for astronomy, astrophysics, planetarium, education and science-communication app developers, star-distance and stellar-kinematics tools, and Gaia-catalogue post-processing. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is geometric distance and kinematics; for a star’s apparent and absolute brightness use a star-magnitude 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/parallax-api/..."
```

## Pricing
- **Free** (Free) — 4,900 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 49,000 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 225,000 calls/Mo, 15 req/s
- **Mega** ($36/Mo) — 1,320,000 calls/Mo, 40 req/s

## Endpoints

### Parallax

#### `GET /v1/distance` — Distance from parallax

**Parameters:**
- `parallax` (query, optional, string) — Parallax (arcsec) Example: `0.7687`
- `parallax_mas` (query, optional, string) — Parallax (milliarcsec)

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

**Response:**
```json
{
    "data": {
        "note": "d(pc) = 1/p(arcsec). A parallax of 1 arcsec is 1 parsec ≈ 3.2616 light-years. Proxima Centauri's 0.7687 arcsec gives ≈1.30 pc (4.24 ly).",
        "inputs": {
            "parallax_arcsec": 0.7687
        },
        "distance_au": 268329.3951,
        "distance_parsec": 1.30089762,
        "distance_light_years": 4.24296055
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:26.354Z",
        "request_id": "3455a0aa-1050-4e49-af56-1271597308e8"
    },
    "status": "ok",
    "message": "Distance from parallax",
    "success": true
}
```

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

**Parameters:**
- `distance_parsec` (query, optional, string) — Distance (pc) Example: `1.3`
- `distance_light_years` (query, optional, string) — Distance (ly)

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

**Response:**
```json
{
    "data": {
        "note": "p(arcsec) = 1/d(pc). Nearer stars have larger parallax; Gaia measures down to microarcseconds.",
        "inputs": {
            "distance_parsec": 1.3
        },
        "parallax_mas": 769.230769,
        "parallax_arcsec": 0.7692307692
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:26.466Z",
        "request_id": "1f449533-0162-42c2-91e3-bb550de73832"
    },
    "status": "ok",
    "message": "Parallax from distance",
    "success": true
}
```

#### `GET /v1/proper-motion` — Tangential velocity

**Parameters:**
- `proper_motion` (query, required, string) — Proper motion (arcsec/yr) Example: `10.39`
- `distance_parsec` (query, optional, string) — Distance (pc) Example: `1.83`
- `parallax` (query, optional, string) — Or parallax (arcsec)
- `parallax_mas` (query, optional, string) — Or parallax (mas)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/parallax-api/v1/proper-motion?proper_motion=10.39&distance_parsec=1.83"
```

**Response:**
```json
{
    "data": {
        "note": "v_t = 4.74047·μ(arcsec/yr)·d(pc) km/s. Barnard's Star (μ≈10.39 arcsec/yr, d≈1.83 pc) has v_t ≈ 90 km/s.",
        "inputs": {
            "distance_parsec": 1.83,
            "proper_motion_arcsec_yr": 10.39
        },
        "tangential_velocity_kms": 90.133883
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:26.577Z",
        "request_id": "4f2f5786-4d5f-4fcb-b5aa-d9e584ac39d4"
    },
    "status": "ok",
    "message": "Tangential velocity",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Parallax in arcsec (or mas), distance in parsec/light-year/AU, proper motion in arcsec/yr. This is geometric distance; for apparent/absolute brightness use a star-magnitude API.",
        "service": "parallax-api",
        "constants": {
            "kms_constant": 4.740470446,
            "au_per_parsec": 206264.806,
            "light_years_per_parsec": 3.2615637769
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/distance": "Distance (pc, ly, AU) from a parallax angle.",
            "GET /v1/parallax": "Parallax angle from a distance.",
            "GET /v1/proper-motion": "Tangential velocity from proper motion and distance."
        },
        "description": "Stellar parallax and astrometry: distance from parallax, parallax from distance, and tangential velocity from proper motion."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:26.690Z",
        "request_id": "286b9f1f-0b29-4c0b-9659-27b4b5c745e3"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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