# Satellites API
> The CelesTrak satellite catalogue (SATCAT) as an API — 33,000+ catalogued payloads and rocket bodies in (and decayed from) Earth orbit. Look up any object by its NORAD catalogue number (e.g. 25544 → ISS (ZARYA)) or international designator (e.g. 1998-067A); search by name with filters for owner/country, object type and in-orbit status; or list every operator with object counts. Each record carries the operational status, launch date and site, decay status, and orbit (period, inclination, apogee/perigee). Ideal for space dashboards, satellite trackers, OSINT and educational tools. (Catalogued averages, not live ephemeris/TLE.)

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

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 50,000 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 250,000 calls/Mo, 20 req/s
- **Mega** ($50/Mo) — 1,200,000 calls/Mo, 50 req/s

## Endpoints

### Satellites

#### `GET /v1/owners` — Operators / countries with object counts

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

**Response:**
```json
{
    "data": {
        "count": 129,
        "owners": [
            {
                "count": 18386,
                "owner": "US",
                "owner_name": "United States"
            },
            {
                "count": 7912,
                "owner": "CIS",
                "owner_name": "Russia / CIS"
            },
            {
                "count": 2501,
                "owner": "PRC",
                "owner_name": "China"
            },
            {
                "count": 755,
                "owner": "UK",
                "owner_name": "United Kingdom"
            },
            {
                "count": 512,
                "owner": "JPN",
                "owner_name": "Japan"
            },
            {
                "count": 415,
                "owner": "FR",
                "owner_name": "France"
            },
            {
                "count": 240,
                "owner": "IND",
                "owner_name": "India"
            },
            {
                "count": 209,
                "owner": "TBD",
                "owner_name": "Unallocated"
            },
            {
                "count": 143,
                "owner": "GER",
                "owner_name": "Germany"
            },
            {
                "count": 141,
                "owner": "IT",
                "owner_name": "Italy"
            },
            {
                "count": 139,
                "owner": "ESA",
                "owner_name": "European Spa
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/satellite` — A single catalogued object by NORAD number or designator

**Parameters:**
- `norad` (query, optional, string) — NORAD catalogue number, e.g. 25544 (ISS) Example: `25544`
- `designator` (query, optional, string) — International designator, e.g. 1998-067A

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/satellites-api/v1/satellite?norad=25544"
```

**Response:**
```json
{
    "data": {
        "name": "ISS (ZARYA)",
        "type": "payload",
        "orbit": {
            "apogee_km": 423,
            "perigee_km": 413,
            "period_min": 92.93,
            "inclination_deg": 51.63
        },
        "owner": "ISS",
        "status": "operational",
        "in_orbit": true,
        "norad_id": 25544,
        "decay_date": null,
        "owner_name": "ISS (international)",
        "launch_date": "1998-11-20",
        "launch_site": "TYMSC",
        "intl_designator": "1998-067A"
    },
    "meta": {
        "timestamp": "2026-05-31T03:28:31.546Z",
        "request_id": "f109d1e8-fcd9-4d0e-98d6-b4f15e52e5d8"
    },
    "status": "ok",
    "message": "Satellite retrieved",
    "success": true
}
```

#### `GET /v1/search` — Search by name with owner / type / orbit filters

**Parameters:**
- `q` (query, optional, string) — Name search, e.g. starlink Example: `hubble`
- `owner` (query, optional, string) — Owner / country code, e.g. US, CIS, PRC, ESA
- `type` (query, optional, string) — payload | rocket-body
- `in_orbit` (query, optional, string) — true = still in orbit, false = decayed
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/satellites-api/v1/search?q=hubble&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 4,
        "limit": 20,
        "query": "hubble",
        "total": 4,
        "offset": 0,
        "filters": {
            "type": null,
            "owner": null,
            "in_orbit": null
        },
        "results": [
            {
                "name": "HUBBLE 6",
                "type": "payload",
                "orbit": {
                    "apogee_km": 587,
                    "perigee_km": 585,
                    "period_min": 96.4,
                    "inclination_deg": 97.77
                },
                "owner": "US",
                "status": "operational",
                "in_orbit": true,
                "norad_id": 64562,
                "decay_date": null,
                "owner_name": "United States",
                "launch_date": "2025-06-23",
                "launch_site": "AFWTR",
                "intl_designator": "2025-135AL"
            },
            {
                "name": "LEMUR-2-HUBBLE-4",
                "type": "payload",
                "orbit": {
                    "apogee_km": 590,
                    "perigee_km": 586,
                    "period_min": 96.44,
                    "inclination_deg": 97.77
                },
                "owner": "US",
                "status": "operational",
                "in_orbit": true,
                "norad_id": 64565,
                "decay_date": null,
                "owner_name": "United States",
                "launch_date": "2025-06-23",
    
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & source

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

**Response:**
```json
{
    "data": {
        "note": "Catalogued payloads and rocket bodies; debris excluded. Orbit values are catalogued averages, not live ephemeris.",
        "total": 33211,
        "fields": [
            "norad_id",
            "name",
            "intl_designator",
            "type",
            "status",
            "owner",
            "launch_date",
            "launch_site",
            "decay_date",
            "in_orbit",
            "orbit"
        ],
        "owners": 129,
        "source": "CelesTrak SATCAT (payloads + rocket bodies)",
        "decayed": 11823,
        "in_orbit": 21388,
        "payloads": 26363,
        "rocket_bodies": 6848
    },
    "meta": {
        "timestamp": "2026-05-31T03:28:31.706Z",
        "request_id": "47f0af58-4aac-4e5c-8dd0-a89836db2920"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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