# Marine Buoys API
> Live marine weather and ocean conditions from NOAA's National Data Buoy Center (NDBC). The station catalogue (1,930 moored buoys and coastal stations worldwide) is searchable by name, type or coordinate; the live endpoint returns the latest observation for any station: significant wave height, wave period and direction, water and air temperature, wind speed/gust/direction, atmospheric pressure and more. Find the nearest buoys to any lat/lon. Ideal for surfing & sailing apps, marine operations, coastal monitoring and oceanography.

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

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

## Endpoints

### Marine Buoys

#### `GET /v1/buoy` — Latest live observation for a station

**Parameters:**
- `station` (query, required, string) — NDBC station id, e.g. 41001 Example: `41001`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buoys-api/v1/buoy?station=41001"
```

**Response:**
```json
{
    "data": {
        "name": "EAST HATTERAS - 150 NM East of Cape Hatteras",
        "wind": {
            "gust_m_s": 12,
            "speed_m_s": 10,
            "direction_deg": 10
        },
        "waves": {
            "direction_deg": null,
            "average_period_s": null,
            "dominant_period_s": null,
            "significant_height_m": null
        },
        "source": "NOAA NDBC",
        "station": "41001",
        "tide_ft": null,
        "latitude": 34.791,
        "longitude": -72.42,
        "air_temp_c": 18.3,
        "dewpoint_c": 11.6,
        "observed_at": "2026-05-31T05:10:00Z",
        "pressure_hpa": 1015.4,
        "water_temp_c": 23.1,
        "visibility_nmi": null,
        "pressure_tendency_hpa": null
    },
    "meta": {
        "timestamp": "2026-05-31T05:47:59.997Z",
        "request_id": "cee9a3a5-63a8-41fc-9621-0309f99c6b3e"
    },
    "status": "ok",
    "message": "Buoy observation retrieved",
    "success": true
}
```

#### `GET /v1/nearby` — Stations within a radius of a coordinate

**Parameters:**
- `lat` (query, optional, string) — Latitude (-90..90) Example: `25.8`
- `lon` (query, optional, string) — Longitude (-180..180) Example: `-80.1`
- `radius_km` (query, optional, string) — Search radius in km (1-20000, default 200)
- `limit` (query, optional, string) — Max results (1-100, default 10)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buoys-api/v1/nearby?lat=25.8&lon=-80.1"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "total": 63,
        "center": {
            "lat": 25.8,
            "lon": -80.1
        },
        "results": [
            {
                "id": "VAKF1",
                "name": "8723214 - Virginia Key, FL",
                "type": "Water Level Observation Network",
                "owner": "O",
                "latitude": 25.731,
                "longitude": -80.162,
                "distance_km": 9.9
            },
            {
                "id": "41122",
                "name": "Hollywood Beach, FL (265)",
                "type": "Waverider Buoy",
                "owner": "R",
                "latitude": 26.001,
                "longitude": -80.096,
                "distance_km": 22.4
            },
            {
                "id": "FWYF1",
                "name": "Fowey Rock, FL",
                "type": "C-MAN Station",
                "owner": "N",
                "latitude": 25.591,
                "longitude": -80.097,
                "distance_km": 23.2
            },
            {
                "id": "BBNF1",
                "name": "BBCW8",
                "type": "C-MAN Station",
                "owner": "NP",
                "latitude": 25.601,
                "longitude": -80.306,
                "distance_km": 30.3
            },
            {
                "id": "PEGF1",
                "name": "8722956 - Port Everglades, FL",
                "type": "Water Level Observation Network",
              
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search the station catalogue

**Parameters:**
- `q` (query, optional, string) — Name / id search, e.g. hatteras Example: `hatteras`
- `type` (query, optional, string) — Station type substring, e.g. buoy
- `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/buoys-api/v1/search?q=hatteras&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "type": null,
        "count": 6,
        "limit": 20,
        "query": "hatteras",
        "total": 6,
        "offset": 0,
        "results": [
            {
                "id": "41001",
                "name": "EAST HATTERAS - 150 NM East of Cape Hatteras",
                "type": "3-meter foam buoy",
                "owner": "N",
                "latitude": 34.791,
                "longitude": -72.42
            },
            {
                "id": "41002",
                "name": "SOUTH HATTERAS - 225 NM South of Cape Hatteras",
                "type": "3-meter foam buoy",
                "owner": "N",
                "latitude": 31.743,
                "longitude": -74.955
            },
            {
                "id": "41062",
                "name": "Hatteras Bay (B1)",
                "type": "Buoy",
                "owner": "UB",
                "latitude": 35.778,
                "longitude": -75.095
            },
            {
                "id": "41120",
                "name": "Cape Hatteras East, NC (250)",
                "type": "Waverider Buoy",
                "owner": "R",
                "latitude": 35.258,
                "longitude": -75.285
            },
            {
                "id": "41X01",
                "name": "Adrift from 41001, 150nm E of Cape Hatteras",
                "type": "3-meter foam buoy",
                "owner": "N",
                "latitude": 34.502,
                "longitude": -72.522
   
…(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/buoys-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Station catalogue is bundled; /v1/buoy fetches the latest live observation from NDBC. Units: m/s wind, metres wave height, °C, hPa.",
        "fields": [
            "station",
            "name",
            "observed_at",
            "wind",
            "waves",
            "pressure_hpa",
            "air_temp_c",
            "water_temp_c",
            "visibility_nmi"
        ],
        "source": "NOAA National Data Buoy Center (NDBC)",
        "stations": 1930,
        "endpoints": [
            "/v1/buoy",
            "/v1/search",
            "/v1/nearby",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:00.222Z",
        "request_id": "25b4998b-5f23-4241-bb3a-2975b4e541ea"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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