Skip to main content
GET
/
buoys
List all buoys
curl --request GET \
  --url https://thesurfkit.com/api/v2/buoys \
  --header 'Authorization: Bearer <token>'
{
  "status": "success",
  "data": {
    "buoys": [
      {
        "id": 10,
        "name": "Anglet",
        "lat": 43.4832,
        "lng": -1.5586,
        "source": "Candhis",
        "source_identifier": "64002",
        "last_reading_time": "2025-11-01T10:00:00Z",
        "readings_count": 125430,
        "last_reading": {
          "uuid": "abc-123-def",
          "significient_height": 1.5,
          "maximum_height": 2,
          "period": 8.5,
          "time": "2025-11-01T10:00:00Z",
          "water_temperature": 18.5,
          "direction": 270,
          "unit": "m"
        }
      }
    ],
    "count": 1
  },
  "meta": {
    "page": 1,
    "per_page": 50,
    "total_pages": 1,
    "timestamp": "2025-11-01T10:00:00Z"
  }
}

Authorizations

Authorization
string
header
required

API key authentication. Pass your API key as a Bearer token in the Authorization header.

Format: Authorization: Bearer YOUR_API_KEY

Alternative: Pass as query parameter ?api_key=YOUR_API_KEY

Security: API keys are stored as BCrypt hashes (never plain text). Only the hash is stored in the database.

Query Parameters

bounds
string

Geographic bounding box as JSON string {"north":44,"south":43,"east":-1,"west":-2}

near
string

Coordinates and radius in format lat,lng (e.g., "43.5,-1.5"). Use with radius parameter.

radius
integer
default:100

Search radius in kilometers (used with near parameter, default: 100)

source
string

Filter by source (e.g., "Candhis", "Meteo France", "Sofar Ocean")

country
string

Filter by ISO 3166-1 alpha-2 country code (e.g., "FR", "ES", "PT"). When set, up to 500 buoys are returned per page.

Pattern: ^[A-Z]{2}$
active_only
boolean
default:true

Only return buoys with recent readings (default: true)

page
integer
default:1
per_page
integer
default:50
Required range: x <= 500

Response

Successful response

status
string
Example:

"success"

data
object
meta
object

Pagination metadata included in list responses