Skip to main content
GET
/
buoys
/
{buoy_id}
/
readings
/
series
Get seasonal buoy reading series
curl --request GET \
  --url https://api.thebuoy.app/v2/buoys/{buoy_id}/readings/series \
  --header 'Authorization: Bearer <token>'
{
  "status": "success",
  "data": {
    "buoy": {
      "id": 295,
      "name": "Azur",
      "lat": 43.38,
      "lng": 7.83,
      "source": "Météo France",
      "dtz": "Europe/Paris"
    },
    "metric": "significient_height",
    "bucket": "day",
    "aggregation": "median",
    "timezone": "Europe/Paris",
    "season": {
      "start": {
        "month": 4,
        "day": 1
      },
      "end": {
        "month": 6,
        "day": 30
      }
    },
    "years": [
      {
        "year": 2025,
        "complete": true,
        "point_count": 91,
        "points": [
          {
            "bucket_index": 1,
            "label": "Apr 01",
            "bucket_start": "2025-04-01T00:00:00+02:00",
            "bucket_end": "2025-04-01T23:59:59+02:00",
            "value": 1.12,
            "sample_count": 24
          }
        ]
      }
    ],
    "count": 91
  },
  "meta": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.labouee.app/llms.txt

Use this file to discover all available pages before exploring further.

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.

Path Parameters

​
buoy_id
integer
required

Query Parameters

​
metric
enum<string>
required

Metric to return for the seasonal series. Candhis supports significient_height, maximum_height, period, peak_period, and direction.

Available options:
significient_height,
maximum_height,
period,
peak_period,
direction,
water_temperature,
wind_speed,
wind_direction,
gust_speed
​
bucket
enum<string>
default:hour

Bucket size for grouping the seasonal series

Available options:
hour,
day,
week
​
aggregation
enum<string>
default:median

Aggregation used when bucket is day or week

Available options:
median,
avg,
min,
max
​
start_year
integer

Inclusive first season year. Explicit ranges can span up to 13 seasons.

​
end_year
integer

Inclusive last season year. Explicit ranges can span up to 13 seasons.

​
season_start_month
integer
default:4

Season start month

Required range: 1 <= x <= 12
​
season_start_day
integer
default:1

Season start day of month

Required range: 1 <= x <= 31
​
season_end_month
integer
default:6

Season end month

Required range: 1 <= x <= 12
​
season_end_day
integer
default:30

Season end day of month

Required range: 1 <= x <= 31
​
timezone
string

IANA timezone used for bucket boundaries and labels. Defaults to the buoy timezone or UTC.

Example:

"Europe/Paris"

Response

Seasonal chart series grouped by year

​
status
string
Example:

"success"

​
data
object
​
meta
object

Non-paginated response metadata