> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thebuoy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# The Buoy API

> Real-time ocean buoy data for developers. Wave heights, periods, water temperatures, and more from ocean buoy networks worldwide.

## What is the Buoy API?

The Buoy API serves real-time and historical wave data from ocean buoys worldwide. Data is sourced from **Candhis**, **Météo France**, **NOAA/NDBC**, **Sofar Ocean**, and others.

Every response uses a consistent `{status, data, meta}` envelope.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API call in under 5 minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Understand how API key authentication works.
  </Card>

  <Card title="France Buoys Guide" icon="location-dot" href="/guides/country-buoys">
    Fetch all active buoys for a country in one call.
  </Card>

  <Card title="Satellite Observations" icon="satellite" href="/guides/satellite-observations">
    Query wave data from satellite missions like CFOSAT and Jason-3.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Browse the full endpoint documentation.
  </Card>
</CardGroup>

## Key Features

<AccordionGroup>
  <Accordion title="Real-time buoy readings" icon="wave-square">
    Access the latest wave height, period, direction, and water temperature from hundreds of active buoys worldwide. Readings are typically updated every 30 minutes.
  </Accordion>

  <Accordion title="Country and geographic filtering" icon="earth-europe">
    Filter buoys by ISO country code (`?country=FR`), geographic bounding box, or a coordinates + radius query. Each response includes pagination metadata.
  </Accordion>

  <Accordion title="Historical data" icon="clock-rotate-left">
    Retrieve paginated historical readings per buoy with date range filters, or search for the reading closest to a specific timestamp.
  </Accordion>

  <Accordion title="Chart time series" icon="chart-line">
    Build dashboards with optimized chart payloads: wave height, period, forecasts, and tide levels as aligned time series.
  </Accordion>

  <Accordion title="Satellite wave observations" icon="satellite">
    Go beyond fixed buoys with open-ocean wave measurements from satellite missions — CFOSAT, Jason-3, Sentinel-3, SWOT, and more. Discover missions via `GET /buoys/satellites` and filter passes by mission. See the [Satellite Observations guide](/guides/satellite-observations).
  </Accordion>

  <Accordion title="Rate limiting and tracking" icon="gauge">
    Every response includes `X-RateLimit-*` headers. Requests exceeding your hourly quota return a `429` with a `retry_after` value so your client can back off gracefully.
  </Accordion>
</AccordionGroup>

## API at a Glance

| Property           | Value                             |
| ------------------ | --------------------------------- |
| Base URL           | `https://api.thebuoy.app/v2`      |
| Auth               | `Authorization: Bearer <api_key>` |
| Format             | JSON (`application/json`)         |
| Default rate limit | 1,000 requests / hour             |
| Version            | v2 (production)                   |

## Data Sources

| Network      | Region  | Type                 |
| ------------ | ------- | -------------------- |
| Candhis      | France  | Wave buoys           |
| Météo France | France  | Wave buoys           |
| NOAA / NDBC  | USA     | Wave & weather buoys |
| Sofar Ocean  | Global  | Spotter buoys        |
| Vegagerðin   | Iceland | Wave buoys           |

***

<Note>
  API access is currently by invitation. To request access, email [thomas@thebuoy.app](mailto:thomas@thebuoy.app)
</Note>