OceanLife API
The OceanLife API provides access to swell, tide and weather information across all major data suppliers, spanning the globe.
All data is expressed using metric units except where explicity defined otherwise.
Luna Events ¶
Luna event related resources.
Luna Event Locations ¶
Presents the locations permitting the retrieval of luna-related data.
Luna Event LocationsGET/luna/locations
List the supported luna event locations.
Error state summary
-
403The User-Key is missing or invalid. -
415The provided Content-Type header failed content negotiation. Check the header is valid.
Example URI
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.luna.location-v1+json200Body
{
"data": [
{
"id": 13,
"lunaId": "1",
"provider": "MOBILE_GEOGRAPHICS",
"description": "130th Street, Hudson River, New York",
"latitude": "40.81670",
"longitude": "-73.96670",
"tzOffset": -18000,
"tzId": "America/New_York"
},
{
"id": 123,
"lunaId": "2",
"provider": "MOBILE_GEOGRAPHICS",
"description": "2.5 miles above mouth, Little Satilla River, Georgia",
"latitude": "31.05830",
"longitude": "-81.49330",
"tzOffset": -18000,
"tzId": "America/New_York"
}
]
}403Body
{
"error": [
{
"type": "FORBIDDEN",
"message": "Whoops! Looks like you aren't allowed to view this page!",
"advice": [
"To use the OceanLifeAPI contact oceanlife.development@gmail.com for options"
]
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<user_requested_media_type>]",
"advice": [
"application/vnd+brantapps.luna.location-v1+json"
]
}
]
}Luna Events ¶
The luna events taking place at the specified location. The default responses period is one week in advance.
The currently supported luna events are;
-
Low water (
LOW_WATER) -
High water (
HIGH_WATER) -
Moonrise (
MOONRISE) -
Moonset (
MOONSET)
Luna Events DetailGET/luna/locations/xtide/{id}
Retrieve luna event data for a specific location specified by the given lunaId.
Error state summary
-
403The User-Key is missing or invalid. -
404The requestedlunaIddoes not map to a recognised ‘luna location’. -
415The provided Content-Type header failed content negotiation. Check the header is valid.
Example URI
- id
number(required) Example: 1Numeric
lunaIdof the supported luna location delivered under the/luna/locationsresponse.
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.luna.event-v1+json200Body
{
"data": [
{
"date": "2015-01-28T23:16:00-05:00",
"eventType": "LOW_WATER",
"height": -0.064
},
{
"date": "2015-01-29T05:11:00-05:00",
"eventType": "HIGH_WATER",
"height": 0.564
},
{
"date": "2015-01-29T11:53:00-05:00",
"eventType": "LOW_WATER",
"height": 0.064
}
]
}403Body
{
"error": [
{
"type": "FORBIDDEN",
"message": "Whoops! Looks like you aren't allowed to view this page!",
"advice": [
"To use the OceanLifeAPI contact oceanlife.development@gmail.com for options"
]
}
]
}404Body
{
"error": [
{
"type": "UNKNOWN",
"message": "Unknown luna location with id [X] and provider [Y]",
"advice" [
"The position requested is not known"
]
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<user_requested_media_type>]",
"advice": [
"application/vnd+brantapps.luna.event-v1+json"
]
}
]
}Solar Events ¶
Solar event related resources.
Solar Event Locations ¶
Presents the locations permitting the retrieval of solar data.
Solar Event LocationsGET/solar/locations
List the supported solar event locations.
Error state summary
-
403The User-Key is missing or invalid. -
415The provided Content-Type header failed content negotiation. Check the header is valid.
Example URI
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.solar.location-v1+json200Body
{
"data": [
{
"id": 21,
"solarId": "1",
"provider": "MOBILE_GEOGRAPHICS",
"description": "130th Street, Hudson River, New York",
"latitude": "40.81670",
"longitude": "-73.96670",
"tzOffset": -18000,
"tzId": "America/New_York"
},
{
"id": 112,
"solarId": "2",
"provider": "MOBILE_GEOGRAPHICS",
"description": "2.5 miles above mouth, Little Satilla River, Georgia",
"latitude": "31.05830",
"longitude": "-81.49330",
"tzOffset": -18000,
"tzId": "America/New_York"
}
]
}403Body
{
"error": [
{
"type": "FORBIDDEN",
"message": "Whoops! Looks like you aren't allowed to view this page!",
"advice": [
"To use the OceanLifeAPI contact oceanlife.development@gmail.com for options"
]
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<user_requested_media_type>]",
"advice": [
"application/vnd+brantapps.solar.location-v1+json"
]
}
]
}Solar Events ¶
The solar events taking place at the specified location. The default responses period is one week in advance.
The supported solar events are;
-
Sunrise (
SUNRISE) -
Sunset (
SUNSET)
Solar Events DetailGET/solar/locations/xtide/{id}
Retrieve solar event data for a specific location specified by the given solarId.
Error state summary
-
403The User-Key is missing or invalid. -
404The requestedsolarIddoes not map to a recognised ‘solar location’. -
415The provided Content-Type header failed content negotiation. Check the header is valid.
Example URI
- id
number(required) Example: 1Numeric
solarIdof the supported luna location delivered under the/solar/locationsresponse.
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.solar.event-v1+json200Body
{
"data": [
{
"date": "2015-01-28T23:16:00-05:00",
"eventType": "SUNSET"
},
{
"date": "2015-01-29T05:11:00-05:00",
"eventType": "SUNRISE"
},
{
"date": "2015-01-29T23:16:00-05:00",
"eventType": "SUNSET"
}
]
}403Body
{
"error": [
{
"type": "FORBIDDEN",
"message": "Whoops! Looks like you aren't allowed to view this page!",
"advice": [
"To use the OceanLifeAPI contact oceanlife.development@gmail.com for options"
]
}
]
}404Body
{
"error": [
{
"type": "UNKNOWN_SOLAR_LOCATION",
"message": "Unknown solar location with id [X] and provider [Y]",
"advice": [
"The position requested is not known"
]
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<user_requested_media_type>]",
"advice": [
"application/vnd+brantapps.solar.event-v1+json"
]
}
]
}Water Events ¶
Water event related resources.
Water Event Locations ¶
Presents the locations permitting the retrieval of water-related data.
Water Event LocationsGET/water/locations{?measures}
List the supported water event locations.
Error state summary
-
403The User-Key is missing or invalid. -
404There was an issue resolving the requested resource. -
415The provided Content-Type header failed content negotiation. Check the header is valid.
Example URI
- measures
string(optional) Example: 'sig_swell'Return locations that support one of the provided measures (comma separated). If more than one measure is provided then an OR operation is applied within the filter query.
Choices:
sig_swellsig_periodsig_swell_dirwater_temp
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.water.location-v1+json200Body
{
"data": [
{
"id": 104,
"buoyId": "32012",
"provider": "NOAA",
"description": "Woods Hole Stratus Wave Station ",
"latitude": -19.376,
"longitude": -84.37,
"capabilities": {
"measures": [
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_PERIOD",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
},
{
"id": 119,
"buoyId": "41001",
"provider": "NOAA",
"description": "EAST HATTERAS - 150 NM East of Cape Hatteras",
"latitude": 34.561,
"longitude": -72.631,
"capabilities": {
"measures": [
"WATER_TEMPERATURE",
"SIGNIFICANT_SWELL_PERIOD",
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
},
{
"id": 120,
"buoyId": "41002",
"provider": "NOAA",
"description": "SOUTH HATTERAS - 225 NM South of Cape Hatteras",
"latitude": 31.862,
"longitude": -74.835,
"capabilities": {
"measures": [
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_PERIOD",
"WATER_TEMPERATURE",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
}
]
}403Body
{
"error": [
{
"type": "FORBIDDEN",
"message": "Whoops! Looks like you aren't allowed to view this page!",
"advice": [
"To use the OceanLifeAPI contact oceanlife.development@gmail.com for options"
]
}
]
}404Body
{
"error": [
{
"type": "NO_MATCH",
"message": "No results when filtering locations on [<measures_requested>]",
"advice": [
"Check the filters requested are valid"
]
}
]
}404Body
{
"error": [
{
"type": "UNKNOWN",
"message": "Unknown buoy with id [<id_requested>] and provider [<provider_requested>]",
"advice": [
"Check the filters requested are valid"
]
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<content_type_requested>]",
"advice": [
"application/vnd+brantapps.water.location-v1+json"
]
}
]
}Water Event Locations by Provider ¶
Presents the locations permitting the retrieval of water-related data for a specific provider.
Note: The World Weather Online resource is a proxy delivering swell data from any GPS coordinate so there is no definitive list of water event locations available for this provider.
Water Event Locations by ProviderGET/water/locations/{provider}{?measures}
List the supported water event locations for a given provider.
Error state summary
-
403The User-Key is missing or invalid. -
404There was an issue resolving the requested resource. -
415The provided Content-Type header failed content negotiation. Check the header is valid.
Example URI
- provider
string(required) Example: noaaThe water event location provider.
Choices:
noaabomqldwwo- measures
string(optional) Example: 'sig_swell'Return locations that support one of the provided measures (comma separated). If more than one measure is provided then an OR operation is applied within the filter query.
Choices:
sig_swellsig_periodsig_swell_dirwater_temp
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.water.location-v1+json200Body
{
"data": [
{
"id": 104,
"buoyId": "32012",
"provider": "NOAA",
"description": "Woods Hole Stratus Wave Station ",
"latitude": -19.376,
"longitude": -84.37,
"capabilities": {
"measures": [
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_PERIOD",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
},
{
"id": 119,
"buoyId": "41001",
"provider": "NOAA",
"description": "EAST HATTERAS - 150 NM East of Cape Hatteras",
"latitude": 34.561,
"longitude": -72.631,
"capabilities": {
"measures": [
"WATER_TEMPERATURE",
"SIGNIFICANT_SWELL_PERIOD",
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
},
{
"id": 120,
"buoyId": "41002",
"provider": "NOAA",
"description": "SOUTH HATTERAS - 225 NM South of Cape Hatteras",
"latitude": 31.862,
"longitude": -74.835,
"capabilities": {
"measures": [
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_PERIOD",
"WATER_TEMPERATURE",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
}
]
}403Body
{
"error": [
{
"type": "FORBIDDEN",
"message": "Whoops! Looks like you aren't allowed to view this page!",
"advice": [
"To use the OceanLifeAPI contact oceanlife.development@gmail.com for options"
]
}
]
}404Body
{
"error": [
{
"type": "NO_MATCH",
"message": "No results when filtering locations on [<measures_requested>]",
"advice": [
"Check the filters requested are valid"
]
}
]
}404Body
{
"error": [
{
"type": "UNKNOWN",
"message": "No supported buoys for provider [X]",
"advice": [
"The requested provider is not known"
]
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<user_requested_media_type>]",
"advice": [
"application/vnd+brantapps.water.location-v1+json"
]
}
]
}Water Event Locations Search ¶
Water Event Locations SearchGET/water/locations/{provider}/search{?latlong}
Retrieve water event locations for a given geo-point and provider.
Example URI
- provider
string(required) Example: wwoThe water event location provider (only WWO supported for search at present)
Choices:
wwo- latlong
string(required) Example: 56.0,-45.0Comma separated longitude and latitude in decimal degrees.
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.water.location-v2+json200Body
{
"data": [
{
"id": 104,
"buoyId": "32012",
"provider": "NOAA",
"description": "Woods Hole Stratus Wave Station ",
"latitude": -19.376,
"longitude": -84.37,
"capabilities": {
"measures": [
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_PERIOD",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
},
{
"id": 119,
"buoyId": "41001",
"provider": "NOAA",
"description": "EAST HATTERAS - 150 NM East of Cape Hatteras",
"latitude": 34.561,
"longitude": -72.631,
"capabilities": {
"measures": [
"WATER_TEMPERATURE",
"SIGNIFICANT_SWELL_PERIOD",
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
},
{
"id": 120,
"buoyId": "41002",
"provider": "NOAA",
"description": "SOUTH HATTERAS - 225 NM South of Cape Hatteras",
"latitude": 31.862,
"longitude": -74.835,
"capabilities": {
"measures": [
"SIGNIFICANT_SWELL_HEIGHT",
"SIGNIFICANT_SWELL_PERIOD",
"WATER_TEMPERATURE",
"SIGNIFICANT_SWELL_DIRECTION"
]
}
}
]
}404Body
{
"error": [
{
"type": "UNKNOWN",
"message": "Unknown search query [x,y]",
"advice": [
"Unknown search query"
]
}
]
}404Body
{
"error": [
{
"type": "NO_MATCH",
"message": "No water event locations found near [x,y]",
"advice": [
"Check the requested coordinates are near a body of water"
]
}
]
}400Body
{
"error": [
{
"type": "BAD_REQUEST",
"message": "Required parameters are malformed or missing from the request",
"advice": [
"Refer to the documentation to ensure the request is valid"
]
}
]
}Water Events Details ¶
Presents the water event detail for a given provider and buoy identifier as returned by the provider end point - see /water/locations/{provider}.
Water Event DetailGET/water/locations/{provider}/{id}{?daysData}
Retrieve detail on the water state at the given location as specified by the provider and buoyId combination.
Error state summary
-
403The User-Key is missing or invalid. -
404The requestedbuoyIddoes not map to a recognised ‘water event location’ or something bad happened. -
415The provided Content-Type header failed content negotiation. Check the header is valid.
Example URI
- provider
string(required) Example: noaaSee
/water/locations/{provider}end point documentation for possible values- id
string(required) Example: 62303String
buoyIdof the supported buoy location delivered under the/water/locationsresponse- daysData
number(optional) Example: 5Requests a specific period of historic data. Omitting this parameter returns all data points.
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.water.event-v1+json200Body
{
"data": [
{
"date": "2016-02-05T12:00:00+00:00",
"significantSwellHeight": 3.1,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 180,
"waterTemperature": 10
},
{
"date": "2016-02-04T17:00:00+00:00",
"significantSwellHeight": 2,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 180,
"waterTemperature": 10
},
{
"date": "2016-02-04T16:00:00+00:00",
"significantSwellHeight": 2.2,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 180,
"waterTemperature": 10
},
{
"date": "2016-02-04T15:00:00+00:00",
"significantSwellHeight": 2.1,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 190,
"waterTemperature": 10
},
{
"date": "2016-02-04T14:00:00+00:00",
"significantSwellHeight": 2.3,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 200,
"waterTemperature": 10.1
}
]
}403Body
{
"error": [
{
"type": "FORBIDDEN",
"message": "Whoops! Looks like you aren't allowed to view this page!",
"access": "To use the OceanLifeAPI contact oceanlife.development@gmail.com for options"
}
]
}404Body
{
"error": [
{
"type": "UNKNOWN",
"message": "Unknown buoy with id [X] and provider [Y]",
"advice": [
"The buoy requested is not known"
]
}
]
}404Body
{
"error": [
{
"type": "WTH",
"message": "Unknown error whilst requesting data for [X] and provider [Y]",
"advice": null
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<user_requested_media_type>]",
"advice": [
"application/vnd+brantapps.water.event-v1+json"
]
}
]
}WWO Marine Data Proxy Details ¶
Proxies the WWO Marine Data v2 API.
WWO Marine Data ProxyGET/water/locations/wwo/virtual{?latlong}
Retrieve the marine conditions and forecast for a given geo-point.
Unlike other end-points documented here, the date-time elements to the WWO responses are all in local time making them LocalDateTimes, rather than DateTimes.
Example URI
- latlong
string(required) Example: 56.0,-45.0Comma separated longitude and latitude in decimal degrees.
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+brantapps.water.event-v2+json200Body
{
"data": [
{
"date": "2016-02-05T12:00:00+00:00",
"significantSwellHeight": 3.1,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 180,
"waterTemperature": 10
},
{
"date": "2016-02-04T17:00:00+00:00",
"significantSwellHeight": 2,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 180,
"waterTemperature": 10
},
{
"date": "2016-02-04T16:00:00+00:00",
"significantSwellHeight": 2.2,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 180,
"waterTemperature": 10
},
{
"date": "2016-02-04T15:00:00+00:00",
"significantSwellHeight": 2.1,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 190,
"waterTemperature": 10
},
{
"date": "2016-02-04T14:00:00+00:00",
"significantSwellHeight": 2.3,
"significantSwellPeriod": 6,
"swellDirectionDegrees": 200,
"waterTemperature": 10.1
}
]
}404Body
{
"error": [
{
"type": "UNSUPPORTED",
"message": "No virtual buoys are available at [Lat X and Lon Y]",
"advice": [
"Check the requested position is valid and on water"
]
}
]
}415Body
{
"error": [
{
"type": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type requested [<user_requested_media_type>]",
"advice": [
"application/vnd+brantapps.water.event-v1+json",
"application/vnd+brantapps.water.event-v2+json"
]
}
]
}400Body
{
"error": [
{
"type": "BAD_REQUEST",
"message": "Required parameters are malformed or missing from the request",
"advice": [
"Refer to the documentation to ensure the request is valid"
]
}
]
}Meteorological Events ¶
Atmospheric event related resources.
WWO Weather Data Proxy Details ¶
Proxies the WWO Weather Data v2 API.
WWO Weather Data ProxyGET/meteo/wwo/weather{?query,daysData}
Retrieve the weather conditions and forecast for a given location.
Example URI
- query
string(required) Example: Swansea, UKThe location query to use whilst quering WWO for weather data.
- daysData
number(optional) Example: 5Requests a specific forecast period. Omitting this parameter returns all data points.
Headers
User-Key: <your_user_key>
Content-Type: application/vnd+wwo.free.weather-v2+json200Body
{
"data": {
"current_condition": [
{
"cloudcover": "0",
"FeelsLikeC": "4",
"FeelsLikeF": "40",
"humidity": "87",
"observation_time": "10:25 PM",
"localObsTime": "2016-03-01 10:25 PM",
"precipMM": "0.2",
"pressure": "1006",
"temp_C": "9",
"temp_F": "48",
"visibility": "9",
"weatherCode": "296",
"weatherDesc": [
{
"value": "Light Rain"
}
],
"weatherIconUrl": [
{
"value": "http://cdn.worldweatheronline.net/images/wsymbols01_png_64/wsymbol_0033_cloudy_with_light_rain_night.png"
}
],
"winddir16Point": "W",
"winddirDegree": "260",
"windspeedKmph": "43",
"windspeedMiles": "27"
}
],
"request": [
{
"query": "Swansea, United Kingdom",
"type": "City"
}
],
"weather": [
{
"astronomy": [
{
"moonrise": "12:59 AM",
"moonset": "10:27 AM",
"sunrise": "07:00 AM",
"sunset": "05:57 PM"
}
],
"date": "2016-03-01",
"hourly": [
{
"chanceoffog": "0",
"chanceoffrost": "0",
"chanceofhightemp": "0",
"chanceofovercast": "94",
"chanceofrain": "94",
"chanceofremdry": "0",
"chanceofsnow": "0",
"chanceofsunshine": "0",
"chanceofthunder": "0",
"chanceofwindy": "0",
"cloudcover": "100",
"DewPointC": "9",
"DewPointF": "49",
"FeelsLikeC": "6",
"FeelsLikeF": "43",
"HeatIndexC": "10",
"HeatIndexF": "50",
"humidity": "96",
"precipMM": "1.2",
"pressure": "1021",
"tempC": "7",
"tempF": "45",
"time": "0",
"visibility": "9",
"weatherCode": "296",
"weatherDesc": [
{
"value": "Light rain"
}
],
"weatherIconUrl": [
{
"value": "http://cdn.worldweatheronline.net/images/wsymbols01_png_64/wsymbol_0033_cloudy_with_light_rain_night.png"
}
],
"WindChillC": "6",
"WindChillF": "43",
"winddir16Point": "SSW",
"winddirDegree": "209",
"WindGustKmph": "39",
"WindGustMiles": "24",
"windspeedKmph": "31",
"windspeedMiles": "19"
},
{
"chanceoffog": "0",
"chanceoffrost": "0",
"chanceofhightemp": "0",
"chanceofovercast": "93",
"chanceofrain": "93",
"chanceofremdry": "0",
"chanceofsnow": "0",
"chanceofsunshine": "0",
"chanceofthunder": "0",
"chanceofwindy": "0",
"cloudcover": "100",
"DewPointC": "11",
"DewPointF": "52",
"FeelsLikeC": "9",
"FeelsLikeF": "47",
"HeatIndexC": "12",
"HeatIndexF": "53",
"humidity": "96",
"precipMM": "0.4",
"pressure": "1018",
"tempC": "8",
"tempF": "47",
"time": "300",
"visibility": "2",
"weatherCode": "266",
"weatherDesc": [
{
"value": "Light drizzle"
}
],
"weatherIconUrl": [
{
"value": "http://cdn.worldweatheronline.net/images/wsymbols01_png_64/wsymbol_0033_cloudy_with_light_rain_night.png"
}
],
"WindChillC": "9",
"WindChillF": "47",
"winddir16Point": "SW",
"winddirDegree": "223",
"WindGustKmph": "42",
"WindGustMiles": "26",
"windspeedKmph": "33",
"windspeedMiles": "20"
}
],
"maxtempC": "11",
"maxtempF": "51",
"mintempC": "3",
"mintempF": "38",
"uvIndex": "1"
}
]
}
}404Body
{
"data": {
"error": [
{
"msg": "Unable to find any matching weather location to the query submitted!"
}
]
}
}