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.
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.
Quickstart
Make your first API call in under 5 minutes.
Authentication
Understand how API key authentication works.
France Buoys Guide
Fetch all active buoys for a country in one call.
Satellite Observations
Query wave data from satellite missions like CFOSAT and Jason-3.
API Reference
Browse the full endpoint documentation.
Key Features
Real-time buoy readings
Real-time buoy readings
Access the latest wave height, period, direction, and water temperature from hundreds of active buoys worldwide. Readings are typically updated every 30 minutes.
Country and geographic filtering
Country and geographic filtering
Filter buoys by ISO country code (
?country=FR), geographic bounding box, or a coordinates + radius query. Each response includes pagination metadata.Historical data
Historical data
Retrieve paginated historical readings per buoy with date range filters, or search for the reading closest to a specific timestamp.
Chart time series
Chart time series
Build dashboards with optimized chart payloads: wave height, period, forecasts, and tide levels as aligned time series.
Satellite wave observations
Satellite wave observations
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.Rate limiting and tracking
Rate limiting and tracking
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.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 |
API access is currently by invitation. To request access, email thomas@thebuoy.app