Quickstart

Prerequisites

You need an API key. If you don’t have one yet, see Authentication to request access.

Step 1 — List active buoys

Fetch a paginated list of active buoys. Each buoy includes its latest reading — no follow-up call needed.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys?per_page=5"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
r = requests.get(
    "https://api.thebuoy.app/v2/buoys",
    params={"per_page": 5},
    headers=headers,
)
r.raise_for_status()
print(r.json())

const response = await fetch(
  "https://api.thebuoy.app/v2/buoys?per_page=5",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();
console.log(data);

Response:

{
  "status": "success",
  "data": {
    "buoys": [
      {
        "id": 12,
        "name": "Anglet",
        "lat": 43.4832,
        "lng": -1.5586,
        "source": "Candhis",
        "source_identifier": "64002",
        "slug": "anglet",
        "last_reading_time": "2026-03-27T08:00:00Z",
        "readings_count": 142300,
        "last_reading": {
          "significient_height": 1.8,
          "maximum_height": 2.4,
          "period": 9.5,
          "direction": 285,
          "water_temperature": 14.2,
          "time": "2026-03-27T08:00:00Z"
        },
        "timezone": "Europe/Paris"
      }
    ],
    "count": 312
  },
  "meta": {
    "page": 1,
    "per_page": 5,
    "total_pages": 63,
    "timestamp": "2026-03-27T09:00:00Z"
  }
}

Step 2 — Filter by country

To get all active buoys in a specific country, pass the ISO 3166-1 alpha-2 country code.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys?country=FR"

Use this to bootstrap a cron job over all French buoys. See the Country Buoys guide for a complete pattern.

Step 3 — Get targeted last readings

If you already know the IDs of the buoys you care about, use last_readings to fetch only those — up to 100 at a time:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys/last_readings?ids=12,45,78&limit=3"

Response:

{
  "status": "success",
  "data": {
    "buoys": [
      {
        "id": 12,
        "name": "Anglet",
        "lat": 43.4832,
        "lng": -1.5586,
        "source": "Candhis",
        "last_reading": {
          "significient_height": 1.8,
          "maximum_height": 2.4,
          "period": 9.5,
          "direction": 285,
          "water_temperature": 14.2,
          "time": "2026-03-27T08:00:00Z"
        }
      }
    ],
    "missing_ids": []
  },
  "meta": {
    "timestamp": "2026-03-27T09:00:00Z"
  }
}

Step 4 — Find the nearest buoy

No IDs? Find the closest buoy to any coordinates:

curl "https://api.thebuoy.app/v2/buoys/nearest?lat=43.48&lng=-1.56&max_distance=50"

nearest and search are public endpoints — no API key required.

What’s next?

Country Buoys

Full cron job pattern for collecting all readings from a country.

Last Readings

Efficiently poll specific buoys with the bulk readings endpoint.

Rate Limits

Plan your request budget and handle 429 responses.

API Reference

Full endpoint documentation with interactive playground.

Getting Started

Use Cases

Prerequisites

Step 1 — List active buoys

Step 2 — Filter by country

Step 3 — Get targeted last readings

Step 4 — Find the nearest buoy

What’s next?

Country Buoys

Last Readings

Rate Limits

API Reference

​Prerequisites

​Step 1 — List active buoys

​Step 2 — Filter by country

​Step 3 — Get targeted last readings

​Step 4 — Find the nearest buoy

​What’s next?

Country Buoys

Last Readings

Rate Limits

API Reference

Prerequisites

Step 1 — List active buoys

Step 2 — Filter by country

Step 3 — Get targeted last readings

Step 4 — Find the nearest buoy

What’s next?