Skip to main content

​
Prerequisites

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

​
Step 1 — List active buoys

The simplest call: fetch a paginated list of all active buoys. Each buoy already includes its latest reading in the response, so there’s no need for a follow-up request. 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://thesurfkit.com/api/v2/buoys?per_page=5"
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. The response includes all matching buoys with their latest readings included. 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://thesurfkit.com/api/v2/buoys?country=FR"
This single call is the most efficient way to bootstrap a cron job that monitors all French buoys. See the Country Buoys guide for a complete cron job 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://thesurfkit.com/api/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://thesurfkit.com/api/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.