> ## Documentation Index > Fetch the complete documentation index at: https://docs.thebuoy.app/llms.txt > Use this file to discover all available pages before exploring further. # 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) ## OpenAPI ````yaml /api-reference/openapi.json get /conditions openapi: 3.0.3 info: title: The Buoy API version: 2.0.0 description: >- **The Buoy API** — programmatic access to ocean wave buoys on The Surf Kit platform. All operations are **read-only** (`GET`). Data includes live and historical readings, geographic filters, chart time series, and **`GET /conditions`** (combined forecast, buoy reading, and tide for a point). ## Authentication Pass your API key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` `GET /buoys/search` and `GET /buoys/nearest` are public (no key required). ## Rate limiting Responses include `X-RateLimit-*` headers. Exceeding your hourly quota returns `429 Too Many Requests`. contact: name: API Support email: thomas@thebuoy.app license: name: Proprietary servers: - url: https://api.thebuoy.app/v2 description: Production server (V2) - url: http://localhost:3000/api/v2 description: Development server (V2) security: - ApiKeyAuth: [] tags: - name: Buoys description: Real-time ocean buoy data - name: Satellite Passes description: >- Satellite altimeter passes over virtual buoys, and the missions behind them - name: Conditions description: All-in-one conditions endpoint paths: /conditions: get: tags: - Conditions summary: Get all-in-one conditions (V2) description: > 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) operationId: getConditionsV2 parameters: - name: lat in: query required: true description: Latitude in decimal degrees example: 43.47967255638358 schema: type: number format: float example: 43.47967255638358 - name: lng in: query required: true description: Longitude in decimal degrees example: -1.5692197193092723 schema: type: number format: float example: -1.5692197193092723 - name: time in: query required: true description: ISO 8601 timestamp for which to get conditions example: '2026-03-28T12:00:00Z' schema: type: string format: date-time example: '2026-03-28T12:00:00Z' - name: spot_id in: query description: Optional spot ID for enhanced context and nearby data example: 1 schema: type: integer example: 1 responses: '200': description: Successful response with conditions data headers: X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: location: type: object properties: lat: type: number format: float description: Latitude example: 43.47967255638358 lng: type: number format: float description: Longitude example: -1.5692197193092723 timezone: type: string description: Timezone for the location example: Europe/Paris forecast: type: object description: Wave, wind, and swell forecast data properties: waves_height: type: number format: float description: Forecast wave height in meters example: 1.5 waves_period: type: number format: float description: Forecast wave period in seconds example: 8.5 waves_direction: type: string description: Forecast wave direction (compass direction) example: SW wind_speed: type: number format: float description: Forecast wind speed in km/h example: 15 wind_direction: type: string description: Forecast wind direction (compass direction) example: NW swell_height: type: number format: float description: Forecast swell height in meters example: 1.2 swell_period: type: number format: float description: Forecast swell period in seconds example: 10 swell_direction: type: string description: Forecast swell direction (compass direction) example: SW wave_energy: type: number format: float description: Wave energy in kJ per meter per wave example: 25.5 reading: type: object description: Nearest buoy reading (if available within 50km) nullable: true properties: exists: type: boolean description: Whether a reading was found example: true significient_height: type: number format: float description: Significant wave height in meters example: 1.8 maximum_height: type: number format: float description: Maximum wave height in meters example: 2.5 direction_degrees: type: integer description: Wave direction in degrees (0-360) example: 225 period: type: integer description: Wave period in seconds example: 9 time: type: string format: date-time description: Reading timestamp example: '2026-03-28T11:45:00Z' wave_energy: type: number format: float description: Wave energy in kJ per meter per wave example: 28.3 buoy: type: object description: Information about the buoy providing the reading properties: id: type: integer example: 10 name: type: string example: Anglet distance_km: type: number format: float description: Distance from location in kilometers example: 2.5 tide: type: object description: Tide information for the location properties: height: type: number format: float description: Current tide height in meters example: 1.2 time: type: string format: date-time description: Time of the tide reading example: '2026-03-28T12:00:00Z' direction: type: string enum: - rising - falling description: Current tide direction example: rising seconds_to_next_tide_change: type: integer description: Seconds until the next tide change (high or low) example: 3600 next_tide: type: string enum: - high - low description: Type of the next tide change example: high next_tide_height: type: number format: float description: Height of the next tide in meters example: 2.5 harbor: type: string description: Harbor name used for tide calculations example: Biarritz metadata: type: object description: Additional metadata about the data sources properties: forecast_updated_at: type: string format: date-time description: When the forecast was last updated example: '2026-03-28T09:00:00Z' reading_age_minutes: type: integer description: Age of the reading in minutes (if reading exists) nullable: true example: 15 tide_source: type: string description: Source of tide data example: shom units: type: object description: Units used for measurements properties: height: type: string example: m speed: type: string example: km/h human_readable: type: string description: >- Optional human-readable conditions description (for compatibility) example: 📍 Anglet buoy (2.5km away)... meta: type: object properties: timestamp: type: string format: date-time description: Response timestamp example: '2026-03-28T12:00:00Z' examples: with_reading: summary: Conditions with buoy reading value: 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' forecast_only: summary: Conditions with forecast only (no nearby buoy) value: 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: false 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: null tide_source: shom units: height: m speed: km/h meta: timestamp: '2026-03-28T12:00:00Z' '400': $ref: '#/components/responses/BadRequest' description: Missing required parameters (lat, lng, or time) or invalid format '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' security: - ApiKeyAuth: [] components: headers: XRateLimitLimit: schema: type: integer description: Maximum requests allowed per hour example: 1000 description: Maximum requests allowed per hour XRateLimitRemaining: schema: type: integer description: Requests remaining in current hour example: 987 description: Requests remaining in current hour XRateLimitReset: schema: type: integer description: Unix timestamp when rate limit resets example: 1735326000 description: Unix timestamp when rate limit resets responses: BadRequest: description: Bad request (400 Bad Request) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: bad_request message: Search term must be at least 2 characters timestamp: '2025-12-27T14:30:00Z' request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Invalid or missing API key (401 Unauthorized) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unauthorized message: Invalid API key timestamp: '2025-12-27T14:30:00Z' request_id: 550e8400-e29b-41d4-a716-446655440000 RateLimitExceeded: description: Rate limit exceeded (429 Too Many Requests) headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed per hour example: 1000 X-RateLimit-Remaining: schema: type: integer description: Requests remaining in current hour example: 0 X-RateLimit-Reset: schema: type: integer description: Unix timestamp when rate limit resets (top of next hour) example: 1735326000 Retry-After: schema: type: integer description: Seconds to wait before retrying example: 3600 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate_limit_exceeded message: You have exceeded 1000 requests per hour timestamp: '2025-12-27T14:30:00Z' request_id: 550e8400-e29b-41d4-a716-446655440000 schemas: ErrorResponse: type: object description: Standardized error response format for V2 API properties: error: type: string description: >- Error code (e.g., "unauthorized", "bad_request", "resource_not_found") example: unauthorized message: type: string description: Human-readable error message example: Invalid API key details: type: object description: Additional error details (optional, varies by error type) securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: > 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. ````