# Asteroid Close Approaches API
> Live near-Earth object close approaches as an API, straight from NASA/JPL's Close-Approach Data (CAD) system. List the asteroids and comets passing nearest Earth over the next N days (or look back), with the approach date, miss distance (in astronomical units, lunar distances and kilometres), relative velocity and an estimated diameter from the object's absolute magnitude; or pull the full close-approach history for a specific object (e.g. 99942 Apophis, 101955 Bennu). Ideal for planetary-defense dashboards, astronomy & space apps, education and "asteroid of the week" content.

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

## Pricing
- **Free** (Free) — 3,500 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 45,000 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 240,000 calls/Mo, 20 req/s
- **Mega** ($49/Mo) — 1,300,000 calls/Mo, 50 req/s

## Endpoints

### Close Approaches

#### `GET /v1/approaches` — Upcoming (or past) close approaches

**Parameters:**
- `days` (query, optional, string) — Window in days from now (default 60) Example: `60`
- `dist_max` (query, optional, string) — Max miss distance in AU (default 0.05 ≈ 19.5 LD) Example: `0.05`
- `past` (query, optional, string) — true = look back instead of forward
- `limit` (query, optional, string) — Max results (1-100, default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/closeapproach-api/v1/approaches?days=60&dist_max=0.05&limit=50"
```

**Response:**
```json
{
    "data": {
        "count": 23,
        "total": 23,
        "approaches": [
            {
                "date": "2026-May-31 00:54",
                "object": "2026 KJ2",
                "distance": {
                    "au": 0.044786,
                    "km": 6699907,
                    "lunar": 17.43
                },
                "fullname": "(2026 KJ2)",
                "estimated_diameter": {
                    "max_km": 0.041,
                    "min_km": 0.018
                },
                "absolute_magnitude_h": 25.807,
                "relative_velocity_km_s": 7.212
            },
            {
                "date": "2026-May-31 01:31",
                "object": "2026 KA3",
                "distance": {
                    "au": 0.024714,
                    "km": 3697202,
                    "lunar": 9.62
                },
                "fullname": "(2026 KA3)",
                "estimated_diameter": {
                    "max_km": 0.044,
                    "min_km": 0.02
                },
                "absolute_magnitude_h": 25.654,
                "relative_velocity_km_s": 9.333
            },
            {
                "date": "2026-Jun-01 03:26",
                "object": "2026 KV",
                "distance": {
                    "au": 0.02598,
                    "km": 3886503,
                    "lunar": 10.11
                },
                "fullname": "(2026 KV)",
                "estimated_diameter": {
               
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/object` — Full close-approach history for one object

**Parameters:**
- `des` (query, required, string) — Object designation/number, e.g. 99942 (Apophis) Example: `99942`
- `limit` (query, optional, string) — Max results (1-200, default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/closeapproach-api/v1/object?des=99942&limit=50"
```

**Response:**
```json
{
    "data": {
        "count": 6,
        "total": 6,
        "object": "99942",
        "approaches": [
            {
                "date": "1907-Apr-13 01:12",
                "object": "99942",
                "distance": {
                    "au": 0.028613,
                    "km": 4280482,
                    "lunar": 11.14
                },
                "fullname": "99942 Apophis (2004 MN4)",
                "estimated_diameter": {
                    "max_km": 0.904,
                    "min_km": 0.404
                },
                "absolute_magnitude_h": 19.09,
                "relative_velocity_km_s": 5.097
            },
            {
                "date": "1949-Apr-14 11:30",
                "object": "99942",
                "distance": {
                    "au": 0.027961,
                    "km": 4182895,
                    "lunar": 10.88
                },
                "fullname": "99942 Apophis (2004 MN4)",
                "estimated_diameter": {
                    "max_km": 0.904,
                    "min_km": 0.404
                },
                "absolute_magnitude_h": 19.09,
                "relative_velocity_km_s": 6.69
            },
            {
                "date": "1990-Apr-14 20:44",
                "object": "99942",
                "distance": {
                    "au": 0.032929,
                    "km": 4926157,
                    "lunar": 12.82
                },
                "fullname": "99942 Apophis (2004 MN
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Source & units

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

**Response:**
```json
{
    "data": {
        "note": "Live close approaches of near-Earth asteroids and comets. dist_max in AU (default 0.05 ≈ 19.5 lunar distances). Diameter estimated from absolute magnitude.",
        "units": {
            "au": "astronomical units",
            "km": "kilometres",
            "lunar": "lunar distances (1 LD = 384,400 km)",
            "velocity": "km/s relative to Earth"
        },
        "source": "NASA/JPL CAD — Close-Approach Data API",
        "endpoints": [
            "/v1/approaches",
            "/v1/object",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T06:28:02.554Z",
        "request_id": "6c7a585a-d2e7-4d64-8c3d-c9e9c31a03e1"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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