SOFAR API Client

Welcome to the SOFAR API Client. It is a simple and easy to use way to access the following API endpoints:

• Marine Weather
• Wave Spectra
• Spotter Sensor

Check out our weather dashboard at https://weather.sofarocean.com/.

Installing

npm install --save @sofarocean/sofar-api-client

Authentication

The Sofar API uses token-based authentication. To get started using the Sofar API, you'll need to retrieve or generate an authentication token.

Get your API token in the Weather Dashboard by signing up for a user, then navigating to Account > API Access.

Usage

Typescript:

import { SDK } from 'sofar-sdk';
async function main(): Promise<number> {
    const apiKey = 'YOUR API KEY';
    const sdk = new SDK(apiKey);
    console.log(await sdk.spotters.getSpotters());
    return 0;
}
main();

JavaScript:

var SDK = require('@sofarocean/sofar-sdk').SDK;
var apiKey = 'YOUR API KEY';

var sdk = new SDK(apiKey);
sdk.spotters.getSpotters().then((spotters) => {
    console.log(spotters);
});

Documentation

For the full API documentation, see here.

Examples

Marine Weather

Get Point Forecast

sdk.marineWeather
    .getPointForecast('SofarOperationalWaveModel', -152.0001, 37.0001, [
        'SofarOperationalWaveModel-significantWaveHeight',
        'SofarOperationalWaveModel-meanDirection',
    ])
    .then((data) => {
        console.log(data);
    });

Get Point Hindcast

sdk.marineWeather
    .getPointHindcast(
        'SofarOperationalWaveModel',
        -152,
        37,
        new Date('2020-07-12T22:00:00Z'),
        new Date('2020-07-12T24:00:00Z'),
        ['SofarOperationalWaveModel-significantWaveHeight', 'SofarOperationalWaveModel-meanDirection'],
    )
    .then((data) => {
        console.log(data);
    });

Get Weather models

sdk.marineWeather
    .getModels()
    .then((models) => {
        console.log('Weather models:');
        console.dir(models, { depth: null });
    })
    .catch((err) => {
        console.error(JSON.stringify(err));
    });

Get model metadata

sdk.marineWeather
    .getModelMetadata('NOAACoralReefWatch')
    .then((metadata) => {
        console.log('Model category metadata:');
        console.dir(metadata, { depth: null });
    })
    .catch((err) => {
        console.error(JSON.stringify(err));
    });

Get data categories

sdk.marineWeather
    .getDataCategories()
    .then((categories) => {
        console.log('Data categories:');
        console.dir(categories, { depth: null });
    })
    .catch((err) => {
        console.error(JSON.stringify(err));
    });

Get data category metadata

sdk.marineWeather
    .getDataCategoryMetadata('coralEcosystem')
    .then((metadata) => {
        console.log('Data category metadata:');
        console.dir(metadata, { depth: null });
    })
    .catch((err) => {
        console.error(JSON.stringify(err));
    });

Spotter

Get a list of spotters

sdk.spotters.getSpotters().then((spotters) => {
    console.log(spotters);
});

Get Wave Data from a specific Spotter

sdk.spotters
    .getSpotter('SPOT-0222')
    .getWaveData({ includeWindData: true, includeFrequencyData: true })
    .then((data) => {
        console.log(data);
    });

Wave Spectra

Get Wave Specra List and download files

sdk.waveSpectra
    .getWaveSpectraForecast({ latitude: 34.5, longitude: 200 })
    .then((spectra) => {
        spectra
            .download(`${spectra.latitude}_${spectra.longitude}.netcdf`)
            .then(() => {
                // successfully written data to stream.
            })
            .catch((err) => {
                console.error(err);
            });
    })
    .catch((err) => {
        console.error(err);
    });

Download Wave Spectra File

sdk.waveSpectra.getWaveSpectraForecast({ latitude: 34.5, longitude: 200 }).then((spectra) => {
    spectra.download('test.netcdf').then(() => {
        console.log('done');
    });
});

Development

Build

The build step runs the typescript compilers and also recreates the documentation.

yarn build

Test

yarn test

Committing & Docs

When commiting to master, the docs directory is updated automatically through a GitHub Workflow and commited. The /docs directory is used for github pages.

Releases

Releases to NPM are handled through a github action workflow. To release a new version, update the version in the package.json file, then create a new tag in /releases/VERSION_NUMBER (eg: /releases/1.0.2).