@tides/api v0.7.0

@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.

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;
  });

Params

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

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<COOPSProducts>; // see below
  datum?: ValueOf<COOPSDatum>; // see below, required for water level products
  interval?: "h" | "hilo" | "MAX_SLACK" | number;
  velType?: "speed_dir" | "default";
  bin?: number;
  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

coopsApi(params: COOPSApiParams)

Async function wrapper around the CO-OPS Data Retrieval API. Added params 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.

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"
// }

new COOPSApi(params: COOPSApiParams)

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

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
// }