# Observatory Codes API
> The IAU Minor Planet Center list of observatory codes as an API — every site the MPC uses to identify a telescope when it publishes astrometric observations of asteroids and comets. For each of 2,700+ codes: the 3-character code, the observatory name, its east longitude and the parallax constants (rho·cos φ', rho·sin φ'). From those constants the API derives each site's geocentric latitude and a -180..180 longitude, so you can find the observatories nearest any point on Earth with a great-circle (haversine) search. Look one up by code, search by name, list them all, or find the closest sites to a latitude/longitude. Distinct from telescope-api (optics maths) — this is the registry of real observing sites and where they are. Served from memory — always fast.

## 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/observatories-api/..."
```

## Pricing
- **Free** (Free) — 12,000 calls/Mo, 3 req/s
- **Starter** ($5/Mo) — 120,000 calls/Mo, 8 req/s
- **Pro** ($15/Mo) — 600,000 calls/Mo, 20 req/s
- **Mega** ($36/Mo) — 3,000,000 calls/Mo, 50 req/s

## Endpoints

### Lookup

#### `GET /v1/observatory` — Observatory by MPC code

**Parameters:**
- `code` (query, required, string) — MPC observatory code Example: `309`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/observatories-api/v1/observatory?code=309"
```

**Response:**
```json
{
    "data": {
        "observatory": {
            "code": "309",
            "name": "Cerro Paranal",
            "latitude": -24.4818,
            "lon_east": 289.5957,
            "longitude": -70.4043,
            "rho_cos_phi": 0.909943,
            "rho_sin_phi": -0.414336,
            "has_location": true
        }
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:11.218Z",
        "request_id": "5b47bf8a-734f-4729-acc1-d2a45815aaa3"
    },
    "status": "ok",
    "message": "Observatory retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Search observatories by name or code

**Parameters:**
- `q` (query, required, string) — Search query (min 2 chars) Example: `paranal`
- `limit` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/observatories-api/v1/search?q=paranal&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 4,
        "query": "paranal",
        "total": 4,
        "observatories": [
            {
                "code": "309",
                "name": "Cerro Paranal",
                "latitude": -24.4818,
                "lon_east": 289.5957,
                "longitude": -70.4043,
                "rho_cos_phi": 0.909943,
                "rho_sin_phi": -0.414336,
                "has_location": true
            },
            {
                "code": "W75",
                "name": "SPECULOOS-South Observatory, Paranal",
                "latitude": -24.4707,
                "lon_east": 289.6094,
                "longitude": -70.3906,
                "rho_cos_phi": 0.910001,
                "rho_sin_phi": -0.41415,
                "has_location": true
            },
            {
                "code": "W91",
                "name": "VHS-VISTA, Cerro Paranal",
                "latitude": -24.4705,
                "lon_east": 289.6026,
                "longitude": -70.3974,
                "rho_cos_phi": 0.910007,
                "rho_sin_phi": -0.414148,
                "has_location": true
            },
            {
                "code": "X11",
                "name": "VLT Survey Telescope, Paranal",
                "latitude": -24.4809,
                "lon_east": 289.596,
                "longitude": -70.404,
                "rho_cos_phi": 0.909953,
                "rho_sin_phi": -0.414324,
                "has_location": true
            }
…(truncated, see openapi.json for full schema)
```

### Geo

#### `GET /v1/nearby` — Nearest observatories to a point

**Parameters:**
- `lat` (query, required, string) — Latitude (-90..90) Example: `-24.6`
- `lon` (query, required, string) — Longitude (-180..180) Example: `-70.4`
- `limit` (query, optional, string) — Max results (1-100) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/observatories-api/v1/nearby?lat=-24.6&lon=-70.4&limit=10"
```

**Response:**
```json
{
    "data": {
        "lat": -24.6,
        "lon": -70.4,
        "count": 10,
        "observatories": [
            {
                "code": "309",
                "name": "Cerro Paranal",
                "latitude": -24.4818,
                "lon_east": 289.5957,
                "longitude": -70.4043,
                "distance_km": 13.2,
                "rho_cos_phi": 0.909943,
                "rho_sin_phi": -0.414336,
                "has_location": true
            },
            {
                "code": "X11",
                "name": "VLT Survey Telescope, Paranal",
                "latitude": -24.4809,
                "lon_east": 289.596,
                "longitude": -70.404,
                "distance_km": 13.2,
                "rho_cos_phi": 0.909953,
                "rho_sin_phi": -0.414324,
                "has_location": true
            },
            {
                "code": "W75",
                "name": "SPECULOOS-South Observatory, Paranal",
                "latitude": -24.4707,
                "lon_east": 289.6094,
                "longitude": -70.3906,
                "distance_km": 14.4,
                "rho_cos_phi": 0.910001,
                "rho_sin_phi": -0.41415,
                "has_location": true
            },
            {
                "code": "W91",
                "name": "VHS-VISTA, Cerro Paranal",
                "latitude": -24.4705,
                "lon_east": 289.6026,
                "longitude": -70.3974,
                "distance
…(truncated, see openapi.json for full schema)
```

### List

#### `GET /v1/list` — List observatories

**Parameters:**
- `limit` (query, optional, string) — Page size (1-500) Example: `50`
- `offset` (query, optional, string) — Offset Example: `0`
- `located` (query, optional, string) — Only sites with coordinates Example: `true`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/observatories-api/v1/list?limit=50&offset=0&located=true"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "total": 2675,
        "observatories": [
            {
                "code": "100",
                "name": "Ahtari",
                "latitude": 62.4597,
                "lon_east": 24.1414,
                "longitude": 24.1414,
                "rho_cos_phi": 0.461165,
                "rho_sin_phi": 0.88437,
                "has_location": true
            },
            {
                "code": "101",
                "name": "Kharkiv",
                "latitude": 49.8131,
                "lon_east": 36.2322,
                "longitude": 36.2322,
                "rho_cos_phi": 0.64403,
                "rho_sin_phi": 0.76246,
                "has_location": true
            },
            {
                "code": "102",
                "name": "Zvenigorod",
                "latitude": 55.5201,
                "lon_east": 36.7595,
                "longitude": 36.7595,
                "rho_cos_phi": 0.564841,
                "rho_sin_phi": 0.822468,
                "has_location": true
            },
            {
                "code": "103",
                "name": "Ljubljana",
                "latitude": 45.8515,
                "lon_east": 14.5277,
                "longitude": 14.5277,
                "rho_cos_phi": 0.695365,
                "rho_sin_phi": 0.716346,
                "has_location": true
            },
            {
                "code": "104",
                "name": "San Marcello Pistoiese",
             
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

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

**Response:**
```json
{
    "data": {
        "source": "IAU MPC ObsCodes",
        "service": "observatories-api",
        "endpoints": {
            "GET /v1/list": "List observatories (limit, offset, located=true to skip space/geocentric codes).",
            "GET /v1/meta": "This document.",
            "GET /v1/nearby": "Nearest observatories to a point (lat=, lon=, limit=) — great-circle distance.",
            "GET /v1/search": "Search observatories by name or code (q=, min 2 chars).",
            "GET /v1/observatory": "Observatory detail by MPC code (code=, e.g. 500 or 309)."
        },
        "description": "IAU Minor Planet Center observatory codes: 3-character code, name, east longitude, parallax constants (rho·cos φ′, rho·sin φ′) and the derived geocentric latitude / -180..180 longitude. Find observatories by code or name, list them, or find the nearest sites to a point (haversine). No key.",
        "with_location": 2675,
        "total_observatories": 2704
    },
    "meta": {
        "timestamp": "2026-06-08T18:25:11.711Z",
        "request_id": "7689d53c-7145-4d8f-8611-ba795466fc57"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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