Get all-in-one conditions (V2)

curl --request GET \
  --url https://api.thebuoy.app/v2/conditions \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.thebuoy.app/v2/conditions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thebuoy.app/v2/conditions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.thebuoy.app/v2/conditions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.thebuoy.app/v2/conditions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.thebuoy.app/v2/conditions")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.thebuoy.app/v2/conditions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "location": {
      "lat": 43.47967255638358,
      "lng": -1.5692197193092723,
      "timezone": "Europe/Paris"
    },
    "forecast": {
      "waves_height": 1.5,
      "waves_period": 8.5,
      "waves_direction": "SW",
      "wind_speed": 15,
      "wind_direction": "NW",
      "swell_height": 1.2,
      "swell_period": 10,
      "swell_direction": "SW",
      "wave_energy": 25.5
    },
    "reading": {
      "exists": true,
      "significient_height": 1.8,
      "maximum_height": 2.5,
      "direction_degrees": 225,
      "period": 9,
      "time": "2026-03-28T11:45:00Z",
      "wave_energy": 28.3,
      "buoy": {
        "id": 10,
        "name": "Anglet",
        "distance_km": 2.5
      }
    },
    "tide": {
      "height": 1.2,
      "time": "2026-03-28T12:00:00Z",
      "direction": "rising",
      "seconds_to_next_tide_change": 3600,
      "next_tide": "high",
      "next_tide_height": 2.5,
      "harbor": "Biarritz"
    },
    "metadata": {
      "forecast_updated_at": "2026-03-28T09:00:00Z",
      "reading_age_minutes": 15,
      "tide_source": "shom"
    },
    "units": {
      "height": "m",
      "speed": "km/h"
    }
  },
  "meta": {
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

Conditions

Get all-in-one conditions (V2)

Returns combined forecast, reading, and tide data for a location in a standardized V2 format.

This endpoint combines:

Wave forecast (height, period, direction, energy)
Wind forecast (speed, direction)
Swell forecast (height, period, direction)
Nearest buoy reading (if available within 50km)
Tide information (height, direction, next change)

Improvements over V1:

✅ Standardized {status, data, meta} response format
✅ Structured JSON data (not human-readable string)
✅ Includes nearby buoy/weather station information
✅ Better error handling
✅ Optional spot_id parameter for enhanced context
✅ Forecast metadata (update times, sources)

GET

conditions

Get all-in-one conditions (V2)

curl --request GET \
  --url https://api.thebuoy.app/v2/conditions \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.thebuoy.app/v2/conditions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thebuoy.app/v2/conditions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.thebuoy.app/v2/conditions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.thebuoy.app/v2/conditions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.thebuoy.app/v2/conditions")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.thebuoy.app/v2/conditions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "location": {
      "lat": 43.47967255638358,
      "lng": -1.5692197193092723,
      "timezone": "Europe/Paris"
    },
    "forecast": {
      "waves_height": 1.5,
      "waves_period": 8.5,
      "waves_direction": "SW",
      "wind_speed": 15,
      "wind_direction": "NW",
      "swell_height": 1.2,
      "swell_period": 10,
      "swell_direction": "SW",
      "wave_energy": 25.5
    },
    "reading": {
      "exists": true,
      "significient_height": 1.8,
      "maximum_height": 2.5,
      "direction_degrees": 225,
      "period": 9,
      "time": "2026-03-28T11:45:00Z",
      "wave_energy": 28.3,
      "buoy": {
        "id": 10,
        "name": "Anglet",
        "distance_km": 2.5
      }
    },
    "tide": {
      "height": 1.2,
      "time": "2026-03-28T12:00:00Z",
      "direction": "rising",
      "seconds_to_next_tide_change": 3600,
      "next_tide": "high",
      "next_tide_height": 2.5,
      "harbor": "Biarritz"
    },
    "metadata": {
      "forecast_updated_at": "2026-03-28T09:00:00Z",
      "reading_age_minutes": 15,
      "tide_source": "shom"
    },
    "units": {
      "height": "m",
      "speed": "km/h"
    }
  },
  "meta": {
    "timestamp": "2026-03-28T12: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

lat

number<float>

required

Latitude in decimal degrees

Example:

43.47967255638358

lng

number<float>

required

Longitude in decimal degrees

Example:

-1.5692197193092723

time

string<date-time>

required

ISO 8601 timestamp for which to get conditions

Example:

"2026-03-28T12:00:00Z"

spot_id

integer

Optional spot ID for enhanced context and nearby data

Example:

1

Response

Successful response with conditions data

status

string

Example:

"success"

data

object

Show child attributes

Overview

Endpoints

Get all-in-one conditions (V2)

Authorizations

Query Parameters

Response