tidecheck

Official TypeScript/JavaScript client for the TideCheck API — tide predictions, sun/moon data, and solunar forecasts for 6,470+ stations in 176 countries.

Install

npm install tidecheck

Quick Start

import { TideCheck } from "tidecheck";

const tc = new TideCheck("tc_live_your_api_key");

// Get tide predictions
const tides = await tc.tides("san-francisco", { days: 7, datum: "LAT" });

for (const extreme of tides.extremes) {
  console.log(`${extreme.type}: ${extreme.height}m at ${extreme.time} (${extreme.localDate})`);
}

Get an API Key

1. Sign up at tidecheck.com/dashboard/login
2. Create a key at tidecheck.com/dashboard/keys
3. Free tier: 50 requests/day, no credit card required

API

new TideCheck(apiKey)

// Simple — just pass your API key
const tc = new TideCheck("tc_live_...");

// With options
const tc = new TideCheck({
  apiKey: "tc_live_...",
  baseUrl: "https://tidecheck.com", // optional, defaults to this
});

tc.tides(stationId, options?)

Get tide predictions for a station.

const tides = await tc.tides("san-francisco", {
  days: 7,       // 1-37, default 9
  datum: "LAT",  // "LAT" | "MLLW" | "MSL", default "LAT"
  start: "2026-04-01", // optional start date
});

Returns:

{
  station: { id, name, region, country, lat, lng, type, timezone },
  datum: "LAT",
  extremes: [
    { type: "high", time: "2026-03-09T05:42:00Z", localDate: "2026-03-09", height: 1.83 },
    { type: "low",  time: "2026-03-09T11:18:00Z", localDate: "2026-03-09", height: 0.42 },
  ],
  timeSeries: [
    { time: "2026-03-09T00:00:00Z", height: 1.23 },
    // ... every 15 minutes
  ],
  conditions: { sunrise, sunset, moonPhase, moonIllumination, tidalStrength, springNeap, moonCalendar },
  dailyConditions: [
    { date: "2026-03-09", sunrise, sunset, moonPhase, moonIllumination, solunarRating, solunarLabel, springNeap },
  ]
}

tc.search(query)

Search for stations by name, region, or country.

const stations = await tc.search("moalboal");
// [{ id: "fes2022-moalboal", slug: "moalboal", name: "Moalboal", region: "Cebu", country: "Philippines", label: "..." }]

tc.nearest(lat, lng)

Find the 5 nearest stations to a coordinate.

const nearby = await tc.nearest(37.8063, -122.466);
// [{ id: "9414290", name: "San Francisco", distanceKm: 0, ... }]

tc.geocode(query)

Geocode a place name to coordinates. Useful for finding stations near a location.

const places = await tc.geocode("Bali");
const nearby = await tc.nearest(places[0].lat, places[0].lng);
const tides = await tc.tides(nearby[0].id);

Error Handling

import { TideCheck, TideCheckError } from "tidecheck";

try {
  const tides = await tc.tides("invalid-station");
} catch (err) {
  if (err instanceof TideCheckError) {
    console.error(err.status);  // 404
    console.error(err.body);    // { error: "Station not found" }
  }
}

Common Patterns

Next high tide

const tides = await tc.tides("san-francisco");
const nextHigh = tides.extremes.find(
  (e) => e.type === "high" && new Date(e.time) > new Date()
);

Group tides by local date

const tides = await tc.tides("fes2022-moalboal", { days: 7 });
const byDay: Record<string, typeof tides.extremes> = {};
for (const e of tides.extremes) {
  (byDay[e.localDate] ??= []).push(e);
}
// { "2026-03-09": [...], "2026-03-10": [...] }

Find tides for a place name

const places = await tc.geocode("Santorini, Greece");
const nearby = await tc.nearest(places[0].lat, places[0].lng);
const tides = await tc.tides(nearby[0].id, { days: 3 });

Timestamps

All time fields are ISO 8601 UTC. Each extreme includes a localDate field (YYYY-MM-DD) in the station's local timezone for easy day grouping. Use station.timezone (IANA, e.g. "Asia/Manila") to convert to local display times.

Rate Limits

Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

| Plan | Requests/day | Keys | |------|-------------|------| | Free | 50 | 1 | | Starter ($9/mo) | 1,000 | 3 | | Pro ($29/mo) | 10,000 | 10 | | Business ($79/mo) | 50,000 | 25 |

Requirements

• Node.js 18+ (or any runtime with global fetch: Deno, Bun, Cloudflare Workers, browsers)
• No dependencies

Links

• API Documentation
• Dashboard
• TideCheck

License

MIT