REST API

Weather API

Retrieve marine weather and ocean conditions for a position across forecast and historical timestamps. The service automatically selects the appropriate data source based on the requested time.

Endpoint

POST · https://api.weather.bluegreenintelligence.com/v1/query

Authentication

x-api-key: YOUR_API_TOKEN
Content-Type: application/json

Request

{
  "param_names": ["swh", "ws", "wdir", "sst", "current_speed"],
  "timestamps": [1760313600, 1760317200],
  "position": {"lat": 25.7617, "lon": -80.1918}
}

Request fields

Field	Type	Required	Description
`param_names`	array	Yes	Weather and ocean parameter identifiers to retrieve. Wave, wind and ocean parameters may be combined in one request.
`timestamps`	array	Yes	Unix epoch timestamps in seconds. Multiple timestamps may be batched in one request.
`position.lat`	float	Yes	Latitude in WGS84 decimal degrees, from -90 to 90.
`position.lon`	float	Yes	Longitude in WGS84 decimal degrees, from -180 to 180.

Available parameters

Parameter	Unit	Category	Description
`swh`	m	Waves	Significant height of combined wind waves and swell.
`wvdir`	° true	Waves	Wind-wave direction.
`swdir`	° true	Waves	Swell-wave direction.
`shts`	m	Waves	Significant swell-wave height.
`shww`	m	Waves	Significant wind-wave height.
`mpts`	s	Waves	Mean swell-wave period.
`mpww`	s	Waves	Mean wind-wave period.
`dirpw`	° true	Waves	Primary wave direction.
`perpw`	s	Waves	Primary wave mean period.
`u`	m/s	Wind	Eastward wind component.
`v`	m/s	Wind	Northward wind component.
`ws`	m/s	Wind	Wind speed.
`wdir`	°	Wind	Direction from which the wind is blowing.
`u_velocity`	m/s	Ocean	Eastward surface-current component.
`v_velocity`	m/s	Ocean	Northward surface-current component.
`current_speed`	kn	Ocean	Surface-current speed.
`current_direction`	°	Ocean	Direction toward which the current flows.
`sst`	°C	Ocean	Sea-surface temperature.
`sss`	PSU	Ocean	Sea-surface salinity.
`layer_density`	kg/m³	Ocean	Surface-layer density.

Quota calculation

Quota usage is based on the number of parameter retrievals. Every ten parameter retrievals consume one quota unit. Multiply the number of requested parameters by the number of timestamps, divide by ten and round up.

quota_used = ceil((parameter_count × timestamp_count) / 10)

Examples

5 parameters × 2 timestamps = 10 retrievals → 1 quota unit.
3 parameters × 12 timestamps = 36 retrievals → 4 quota units.
8 parameters × 1 timestamp = 8 retrievals → 1 quota unit.
15 parameters × 3 timestamps = 45 retrievals → 5 quota units.

Quota optimization: Batch multiple timestamps in one request rather than issuing a separate request for each timestamp.

Data availability

Forecast data is available for up to approximately ten days, depending on the parameter and source model.
Beyond the forecast horizon, climatic averages may be available for selected parameters.
Historical hindcast data is retained for up to approximately six months.
The dashboard currently identifies 1 November 2025 as the historical-data start date.
Use UTC when producing Unix timestamps to avoid timezone ambiguity.

Response

The response groups parameter values by timestamp. A requested parameter may be null when data is unavailable for the selected position or time.

{
  "data": {
    "13-10-2025T12:00": {
      "swh": 1.09,
      "ws": 7.4,
      "sst": 26.1,
      "current_speed": 0.42,
      "current_direction": 180.0
    }
  }
}

Timestamp representation: Request timestamps are Unix epoch seconds. Current response examples use formatted date-time keys.

Important notes

Coordinates use WGS84 decimal degrees.
Wave, wind and ocean parameters can be requested together.
Respect the daily quota associated with the active subscription plan.
Handle null values in client applications.

Request and response JSON

Example input JSON

{
  "param_names": ["swh", "ws", "wdir", "sst", "current_speed"],
  "timestamps": [1760313600, 1760317200],
  "position": {"lat": 25.7617, "lon": -80.1918}
}

Example output JSON

{
  "data": {
    "13-10-2025T12:00": {
      "swh": 1.09,
      "ws": 7.2,
      "wdir": 181.3,
      "sst": 26.1,
      "current_speed": 0.4
    }
  }
}

Quick start

curl -X POST "https://api.weather.bluegreenintelligence.com/v1/query" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -d '{
    "param_names": ["swh", "sst", "u_velocity", "v_velocity", "current_speed", "current_direction"],
    "timestamps": [1760313600, 1760317200],
    "position": {"lat": 25.7617, "lon": -80.1918}
  }'

Custom quota

For temporary quota increases, enterprise volumes or custom commercial requirements, contact operations@bluegreenintelligence.com. Include the expected request volume, parameters and operating pattern.

Live API demo

API key

Unix timestamps, comma separated

Latitude

Longitude

Select weather parameters

Generated request

The API key remains in this browser tab and is sent only to the selected API endpoint.