@tides/noaa

Wrapper around NOAA's Tides and Currents API.

Usage

``
yarn install @tides/noaa
// or
npm install --save @tides/noaa
`

The API can be called in 2 ways.

`js
import { coopsApi, COOPSApi } from "@tides/noaa";

// plain function
const getTides = async () => {
const response = await coopsApi({
station: "840140",
units: "english",
product: "predictions",
datum: "MLLW",
begin_date: "20201214",
end_date: "20201214",
interval: "hilo"
}).then(({ data }) => {
if (!data) return;

return data;
});
};

// using the class
const api = new COOPSApi({
station: "840140",
units: "english",
begin_date: "20201214",
end_date: "20201214"
});

const tides = api
.get({
product: "predictions",
datum: "MLLW",
interval: "hilo"
})
.then(({ data }) => {
if (!data) return;

return data;
});
`

$3

The params directly coincide with the CO-OPS Data Retrieval API params.

`ts
type COOPSApiParams = {
station: string;
units: "english" | "metric";
format?: "json" | "xml" | "csv"; // defaults to json
timeZone?: "lst_ldt" | "lst" | "gmt"; // defaults to lst_ldt
date?: "latest" | "recent" | "today";
beginDate?: string; // yyyMMdd, yyMMdd HH:mm, MM/dd/yyyy, MM/dd/yyyy HH:mm
endDate?: string; // yyyMMdd, yyMMdd HH:mm, MM/dd/yyyy, MM/dd/yyyy HH:mm
range?: number;
product: ValueOf; // see below
datum?: ValueOf; // see below, required for water level products
interval?: "h" | "hilo" | "MAX_SLACK" | number;
velType?: "speed_dir" | "default";
bin?: number;
timeFormat?: string; // defaults to hh:mm a if units === 'english', HH:mm otherwise
windUnits?: string; // defaults to knots if units === 'english', meters/second otherwise
noFormat?: boolean; // whether or not to return friendlier formatted data
};

enum COOPSProducts {
water_level,
air_temperature,
water_temperature,
wind,
air_pressure,
air_gap,
conductivity,
visibility,
salinity,
humidity,
hourly_height,
high_low,
daily_mean,
monthly_mean,
one_minute_water_level,
predictions,
datums,
currents,
currents_predictions
}

// required for water level products
enum COOPSData {
CRD,
IGLD,
LWD,
MHHW,
MHW,
MTL,
MSL,
MLW,
MLLW,
NAVD,
STND
}
`

More information can be found here.

API

$3

Async function wrapper around the CO-OPS Data Retrieval API. Added params timeFormat and windUnits are used for returning friendlier data. You can disable this and get the raw data from CO-OPS by setting the param noFormat to true.

`js
import { coopsApi } from '@tides/noaa'

const getTodaysTides = async () => {
const response = await coopsApi({
station: '840140',
units: 'english',
date: 'today',
product: 'predictions',
interval: 'hilo',
windUnits: 'mph', // noaa api will return wind in knots when units === 'english'
timeFormat: 'h:mm a' // the api will use this as the default since units === 'english',
noFormat: false // to get the raw return data from CO-OPS, set this to 'true'
})

return response ?? null
}

const todaysTides = getTodaysTides()
console.log(todaysTides)
// returns an array of tides
// {
// time: {
// local: "2020-12-15T04:47:00.000Z",
// utc: "2020-12-15T09:47:00:000.Z",
// display: "\"4:47 AM\""
// },
// value: -1.076,
// symbol: "ft",
// type: "L",
// },
//
// setting noFormat to true will return raw data from CO-OPS
// ie:
// {
// t: "2020-12-15 04:47",
// v: "-1.076",
// type: "L"
// }
`

$3

The COOPSApi class is initialized with the same params and has some extra methods for gathering more specific data.

`js
import { COOPSApi } from '@tides/noaa'

// only some params are required for initialization
const api = new COOPSApi({
station: "8410140",
units: "english",
timeFormat: "h:mm a" // default if units === 'english', HH:mm for metric
windUnits: "mph",
noFormat: false // set to 'true' for raw CO-OPS data
})

// other params are used on a method level (i.e. product, datum)
const tides = api.get({
product: "predictions",
datum: "MLLW",
date: "today",
interval: "hilo"
})

// the class also contains methods to check for alerts / flood levels for this.station
const alerts = api.alerts()
// returns
// {
// id: "8410140",
// alert: "HIGH_WATER_NOW" | "HIGH_WATER_TODAY" | "HIGH_WATER_TOMORROW" | null
// }

const floodLevels = api.floodLevels()
// returns null or an array of flood levels
// {
// type: "minor",
// value: 20.4
// }
``