Skip to main content
GET
/
buoys
/
{buoy_id}
/
readings
Get historical readings for a buoy
curl --request GET \
  --url https://thesurfkit.com/api/v2/buoys/{buoy_id}/readings \
  --header 'Authorization: Bearer <token>'
{
  "status": "success",
  "data": {
    "buoy": {
      "name": "<string>",
      "lat": 123,
      "lng": 123,
      "source": "<string>",
      "dtz": "<string>"
    },
    "readings": [
      {
        "id": 123,
        "uuid": "<string>",
        "significient_height": 123,
        "maximum_height": 123,
        "period": 123,
        "time": "2023-11-07T05:31:56Z",
        "water_temperature": 123,
        "direction": 123,
        "direction_compass": "<string>",
        "unit": "<string>",
        "energy_per_wave": 123
      }
    ],
    "count": 123
  },
  "meta": {
    "page": 1,
    "per_page": 50,
    "total_pages": 5,
    "timestamp": "2023-11-07T05:31:56Z",
    "date_range": {
      "start": "2023-11-07T05:31:56Z",
      "end": "2023-11-07T05:31:56Z"
    },
    "performance": {
      "parse_date_range_ms": 123,
      "query_build_ms": 123,
      "count_query_ms": 123,
      "pagination_setup_ms": 123,
      "load_records_ms": 123,
      "records_loaded": 123,
      "total_db_time_ms": 123,
      "serialization_ms": 123,
      "total_ms": 123,
      "timestamp": "2023-11-07T05:31:56Z",
      "date_range_hours": 123,
      "pagination_method": "kaminari",
      "sql_query": "<string>",
      "query_plan": "<string>"
    }
  }
}

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

start_date
string<date-time>

Start date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

end_date
string<date-time>

End date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

date
string<date>

Filter by single date (YYYY-MM-DD). Alternative to start_date/end_date.

timestamp
integer

Filter by unix timestamp (seconds). Returns readings within a 3-hour window.

order
enum<string>
default:desc

Sort order

Available options:
asc,
desc
page
integer
default:1
per_page
integer
default:20
Required range: 1 <= x <= 100
debug
boolean
default:false

Enable debug mode to include query plan and SQL in response (adds overhead)

no_kaminari
boolean
default:false

Bypass Kaminari pagination and use manual pagination (for performance testing)

Response

Successful response

status
string
Example:

"success"

data
object
meta
object

Pagination metadata included in list responses