Tide API Guide CORE

🚀 Early Access / Beta Testing

This API is currently in active development and will be ready for beta testing soon! Note: It will only available for commercial use. If you would like to be notified when the beta or free tier becomes available, please join the waitlist.

Integration Fact Sheet

Auth Type	API Access	Base URL	Protocol
API Key	Manual Request	https://api.marine.metservice.com/tide/v4	REST

Variables	Coverage	Horizon	Interval
sea_surface_elevation, tidal_stage	Global & NZ Coastal/Station Models	Decades (Astronomical Predictions)	Minimum 15min

Introduction

The Tide API provides high-quality tide predictions for locations across New Zealand and the globe. It unifies authoritative station data (e.g., LINZ) and advanced model-grid predictions into a single, easy-to-use API.

Core Concepts

Stations vs. Models

The Tide API offers two distinct sources of data. Depending on your choice of source (Station or Model) and output (Tide Times or Timeseries), you will use a different endpoint. See the API Reference for the specific paths. Understanding the difference between sources is key to valid usage:

• Stations (Gauged Locations):

  • What it is: Data derived from historical observations at a physical tidal gauge.
  • Precision: Extremely high for that exact location.
  • limitations: Valid only for the specific location (e.g., a wharf or port). Do not use a station prediction for a beach 20km away.
  • Use Case: Official tide times for a specific port or harbour (e.g., "High Tide at Port of Tauranga").

• Models (Best for Coastlines & Open Ocean):

  • What it is: Data calculated by a hydrodynamic model that simulates fluid physics across a grid.
  • Precision: Highly accurate for understanding water movement across a region.
  • Benefits: Predicts tides for any coordinate (lat/lon), even where no physical gauge exists.
  • Use Case: Surf breaks, fishing spots, shipping routes, or offshore locations.

Data Definitions

• Tidal Elevation (sea_surface_elevation): The predicted water level in metres.
  • For Stations, this is a harmonic prediction based on historical constituent analysis.
  • For Models, this is a hydrodynamic prediction based on physics simulations.
• Datum: By default, all heights are relative to LAT (Lowest Astronomical Tide).
  • Other Datums: You can request MSL (Mean Sea Level) or CD (Chart Datum, stations only) using the datum parameter.

Tide Times vs. Timeseries

The Tide API offers two different ways to retrieve predictions based on your use case:

• Tide Times (/tidetimes):
  • What it is: Returns the turning points (Highs and Lows).
  • How it works: Uses an algorithm to locate the absolute peaks (High Waters) and troughs (Low Waters).
  • Data Returned: A sparse list containing the time, the height, and the tidal_stage (high or low).
  • Use Cases: Calendars, tide tables, surfacing "Next high tide is at 2:15 PM" in an app.
• Timeseries (/timeseries):
  • What it is: Maps the continuous flow of the tide over time.
  • How it works: Samples the sea level at a regular, fixed interval (e.g., every 15 minutes), regardless of the tide stage.
  • Data Returned: A dense list of data points evenly spaced by the time_interval. No tidal_stage is provided.
  • Use Cases: Drawing continuous tidal curves plotted on a UI, navigation (calculating draft clearance at an arbitrary time), scientific modeling.

Schema Design Note: Timeseries vs. Tide Times

To simplify parser integrations, the Tide API uses a single, flattened TidePrediction object for both endpoints. For any given point returned by either endpoint, the sea_surface_elevation corresponds exactly to the height of the tide at that specific time. However, the tidal_stage property behaves differently:

• In /tidetimes: Every point represents an absolute peak or trough, so the response includes the tidal_stage (high or low).
• In /timeseries: Points represent steady intervals across the tidal curve (e.g., halfway between high and low tide). At these intervals, the tide is not at a specific stage (e.g., high or low). Therefore, the API completely drops the tidal_stage key from the JSON payload, rather than returning null or empty values.

Getting Started: Your First Forecast

Authorization

All requests require an API key provided in the Authorization header. If you do not have an API key, please see the Authentication page for instructions on how to request one.

Authorization: ApiKey <your-api-key>

Choose Your Endpoint

• For Specific Locations: GET /stations/{station_id}/tidetimes (See API Reference)
• For Coordinates: GET /models/{model_id}/tidetimes/points (See API Reference)

Make the API Call

Example: Get High/Low Tides for a Port

curl -H "Authorization: ApiKey <key>" \
     "https://api.marine.metservice.com/tide/v4/stations/port-taranaki/tidetimes"

Example: Get Time Series for a Coordinate

curl -H "Authorization: ApiKey <key>" \
     "https://api.marine.metservice.com/tide/v4/models/tpxo9_glob_v9.4/timeseries/points?latitudes=-39.05&longitudes=174.02"

Example Response

{
  "metadata": {
    "model_id": "tpxo9_glob_v9.4",
    "datum": "LAT",
    "data_year": "2025",
    "units": {
      "sea_surface_elevation": "m"
    }
  },
  "predictions": [
    {
      "time": "2025-05-25T00:00:00Z",
      "sea_surface_elevation": 1.25,
      "tidal_stage": "high"
    },
    {
      "time": "2025-05-25T06:15:00Z",
      "sea_surface_elevation": 0.15,
      "tidal_stage": "low"
    }
  ]
}

Need More Examples?

This guide only shows a single example response. To see the JSON structure for other endpoints, or generate code snippets in your preferred language, check out the Tide API Technical Reference!

Integration Workflow & Usage

To build a robust integration, we recommend the following flow:

1. Discovery

First, determine which resource best fits your user's location.

• Scenario A: User selects a Port. Call GET /stations to get the list of official gauges. You can filter by bounding box or radius.
  • GET /stations?radius=10000&latitude=-36.85&longitude=174.76 (Find stations within 10km of Auckland)
• Scenario B: User clicks a Map Coordinate. Use GET /models to see which models cover that area (e.g., tpxo9v4_nz for NZ waters).

2. Request Data

Once you have the station_id or latitude/longitude, choose your data type:

• Tide Times (/tidetimes): High/Low water summaries. Best for calendars and daily planners.
• Time Series (/timeseries): 10-minute interval predictions. Best for detailed charts and navigation.

3. Caching Strategy (Critical)

Tide data is deterministic and calculated months/years in advance.

• Do NOT poll the API every time a user views a screen.
• DO fetch data once per day (or week) and store it locally.
• If a user requests the tide for "Auckland" on Friday, cache that result. If they check again 10 minutes later, serve the cached data.

Checking API Status

For health and availability monitoring, use the /health endpoint. This checks the API's connectivity to the underlying database.

curl "https://api.marine.metservice.com/tide/v4/health"
# Returns: {"status": "ok"}

Time Handling

For detailed schemas of these parameters, see the API Reference.

• Time Range (time_range): Defines the Start and End (ISO 8601 Interval).
  • Default: If omitted, defaults to Now until 7 days from now.
  • Example: 2023-01-01T00:00:00Z--2023-01-02T00:00:00Z
• Time Interval (time_interval): Defines the step size (e.g., 15min, 1h). Default is 15min.

Advanced Features

Geospatial Discovery

You can search for stations or models using geospatial queries. For exact parameter schemas, see the API Reference.

• Bounding Box: ?bounding_box=min_lon,min_lat,max_lon,max_lat
• Radius: ?latitude=...&longitude=...&radius=10000 (radius in metres)

Limits and Errors

The Tide API relies strictly on the global platform limits and error specifications. There are no specific additional limits or bespoke errors beyond the Core API standards.

For detailed information, please review the global policies:

• Platform Rate Limits
• Error Handling Guide

Fair Use: Please avoid unnecessary polling. Tide data is astronomical and deterministic; it does not change in real-time like weather data. You should aggressively cache responses.