Magicseaweed API
Node wrapper for Magicseaweed (MSW) developer API.
Quickstart
//Add the API to your modulevar msw = ; //Configure the instance to use your API key, optionally override the units (default is 'US')msw; //Get a promise for the swell forecast for spot at id 169 (Mundaka)msw;
API
msw.set(): static configuration
//signaturemsw : msw;
//apiKey: your MSW API key is required for any transactions. msw; //units: optionally set the units you want (option of US, EU & UK). Default of 'US'. Case insensitive.msw; //Obviously you can do both in one callmsw;
Go to MSW to get an API key.
msw.forecast(): get swell forecast
//signaturemsw : Promises/A+ for Forecast
//Option 1: using spotId integer (uses pre-set `units` via `set()` or default value of 'US')msw; //Option 2: using options object // spotId required// units optional: overrides whatever pre-defined units are for this call onlymsw;
Throws Error
when:
- no parameter is given
apiKey
notset()
Returns:
- promise with
Forecast
data. (Specifically returns a Q promise).
msw;
Note: Errors in retrieving data from Magicseaweed, invalid API KEY and invalid spot ID handled by a rejected promise. Handle these errors in second argument to
then()
as per the Promises/A+ spec.
msw.mockCallsUsing(): enable mock responses (for testing)
//signaturevar mocks = msw;
mocks
mocks.mockSpot(): Mocks a single spot call
//signaturemocks;
If the
spotId
does not exist in the samples, or the httpResponse is not200
, the mocked HTTP response will returnundefined
.
mocks.data: Sample data for a spot (if any)
var mockSpot169 = mocksdata'169';var forecast = mockSpot169;
Forecast
This is the instance yielded by a fulfilled msw.forecast()
promise.
forecast.filter(): Creates new Forecast by filtering entries
//signatureforecast : Forecast
Creates a new Forecast
via a boolean callback function. Note that the underlying ForecastEntry
instances are shared by reference and thus are mutable.
Callback of the standard form function (item, index, array)
.
msw;
forecast.toArray(): Swell data as Array
//signatureforecast : Array
Returns an Array
of ForecastEntry
.
msw;
Note: the Array is a clone of the underlying
Forecast
data, however each individualForecastEntry
is a mutable instance, so be wary of modifying this data.
forecast.toString(): Swell data as String
//signatureforecast : String
Takes an optional parameter hash and returns a string with one line for each forecast entry.
msw;
Supports UTC times via:
forecast;
Supports HTML table output via:
forecast;
Allows custom date formatting via:
forecast; //eg. Mon Dec 22 21:00
Supports modification of entry output via:
//signatureforecast
Requires both
shouldHighlightEntry()
andhighlightEntry()
to be supplied. The former returnstrue
orfalse
as to whether of not to call the output modifier. The modifierhighlightEntry()
is called to transform the output for that entry if required.
Returns swell data in the following format (when html
is not true
):
Dec 13 01:00 ★ 3-4ft (4.5ft 9s ENE) 12mph E 1F
Dec 13 04:00 ★ 3-4ft (4.5ft 9s ENE) 12mph E 1F
Dec 13 07:00 ★ 3-4ft (4.5ft 9s ENE) 12mph ENE 1F
Dec 13 10:00 ★ ★ 3-4ft (5ft 9s ENE) 15mph ENE 1F
Dec 13 13:00 ★ ☆ 3-4ft (5ft 9s ENE) 16mph E 10F
Dec 13 16:00 ★ ☆ 3-4ft (5ft 9s ENE) 16mph E 10F
Dec 13 19:00 ★ ★ 3-4ft (5ft 9s ENE) 14mph E 10F
Dec 13 22:00 ★ 3-4ft (5ft 9s ENE) 13mph E 10F
Dec 14 01:00 ☆ 2-4ft (5ft 8s ENE) 15mph E 1F
Dec 14 04:00 ★ 2-4ft (5ft 8s ENE) 15mph ENE 1F
Dec 14 07:00 ★ 2-4ft (5ft 8s ENE) 14mph E 1F
Dec 14 10:00 ★ 2-4ft (5ft 8s ENE) 13mph E 1F
Dec 14 13:00 ★ 2-4ft (5ft 8s ENE) 12mph E 10F
Dec 14 16:00 ★ 2-4ft (5ft 8s ENE) 12mph E 10F
Dec 14 19:00 ★ 2-4ft (5ft 8s ENE) 10mph E 11F
Dec 14 22:00 ★ 2-4ft (5ft 8s ENE) 12mph E 11F
forecast.where(): Query forecast data
//signatureforecast : Forecast
Supported Parameters
Can use any combination of the following for:
- Breaking height (the height of the swell in units):
minBreakingHeight
&/ormaxBreakingHeight
- Solid stars (MSW assigned solid stars):
minSolidStars
&/ormaxSolidStars
- Faded stars (MSW assigned faded stars):
minFadedStars
&/ormaxFadedStars
- Swell period: (the number of seconds of the primary swell period):
minPeriod
&/ormaxPeriod
- Wind speed: (the direction of wind in units):
minWindSpeed
&/ormaxWindSpeed
- Wind direction (the direction of the wind represented as degrees in the range 0° to 360°):
lowerWindDirection
ANDupperWindDirection
. Both parameters are required to query on wind direction. - Datetime: (the datetime of the forecast relative to the zone's timezone)
minDateTime
&/ormaxDateTime
- Sequence: (the number of consecutive entries that must occur in order for the entry to be returned)
minSequence
Refer to MSW Guide for Solid & Faded star definitions
All queries are inclusive. E.g.
minBreakingHeight
of 3 matches all entries>=
3
//get all forecast entries with minBreakingHeight at least 3 unitsforecast; //get all forecast entries with breaking height between 3 and 8, a wind speed of no more than 10 units and a period of at least 10sforecast; //get all forecast entries with at least 3 solid and 1 faded starsforecast; //get all forecast entries with 5 or more solid stars, at least 6 in min breaking height and a 16 or more second periodforecast; //get all forecast entries with at least 17s period and wind no greater than 10 (mph) which occur in a sequence of at least three entries in length forecast;