Tide API Guide CORE

Beta In Progress

The Tide API v4 Beta is Live

We are currently running a closed beta to gather developer feedback on the new high-performance endpoints. The API is available for commercial evaluation.

Request Early Access

Integration Fact Sheet

Auth Type	API Access	Base URL	Protocol
API key, sent as a Bearer token	Manual Request	https://api.marine.metservice.com/tide/v4	REST

Variables	Coverage	Horizon	Interval
sea_surface_elevation, tidal_stage	Global & NZ Coastal/Station Models (Coverage Map)	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: Calculated 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: 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.
  • Coverage: Each regional model covers a defined area of New Zealand harbour or coastal water. The global model covers everywhere else.
  • Benefits: Predicts tides for any coordinate inside the model's area, even where no physical gauge exists.
  • Check the area first: GET /models returns each model's boundary (a polygon of [lon, lat] points) and resolution. A point outside a model's boundary returns a 400 error, so check the point falls inside the boundary before calling a regional model, or use the global model (tpxo9_glob_v9.4) instead. The coverage map shows every model area.
  • Points near the shore: Each model calculates tides on a grid, and resolution in GET /models is its grid spacing in degrees. A coordinate close to the shore can fall in a grid cell the model treats as land, even when the point itself is over water, such as in a marina or a narrow harbour. The API then returns a 400 error with the message Chosen point coordinates are over land. Coarser grids reach further from the shore: the global model's grid is about 0.033 degrees (roughly 3.7 km), so it can reject harbour points that a regional model with a finer grid accepts. If a point returns this error, try the regional model for that area, or a point a little further offshore.
  • Use Case: Surf breaks, fishing spots, shipping routes, or offshore locations.

Data Sources and Attribution

Station predictions are calculated from tidal data published by Toitū Te Whenua Land Information New Zealand (LINZ). The regional models are built and run by MetService, and locations elsewhere use a global tide model.

This work is based on Toitū Te Whenua Land Information New Zealand data which are licensed by Toitū Te Whenua Land Information New Zealand for re-use under the Creative Commons Attribution 4.0 International licence.

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).
  • If you omit the datum parameter from your request entirely, the API will safely default to LAT and explicitly inject "datum": "LAT" into the response metadata block so your application has a safe confirmation.
  • Other Datums: You can explicitly request MSL (Mean Sea Level) or CD (Chart Datum, stations only) using the datum query 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: Bearer <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: Bearer <key>" \
     "https://api.marine.metservice.com/tide/v4/stations/port-taranaki/tidetimes"

Example: Get Time Series for a Coordinate

curl -H "Authorization: Bearer <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",
    "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. To check before you write any code, the Coverage Map shows every tide station and regional model grid; the global model covers everywhere else.

• Scenario A: User selects a Port. Call GET /stations to get the list of official gauges. You can filter by name, bounding box or radius.
  • GET /stations?name=napier (Find stations with "napier" in the name, then use the station_id in the response, for example linz6432)
  • 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.

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. It needs your API key, like every other endpoint. The status is ok when the API is ready to handle requests, or degraded if its cache is unavailable (the API still serves requests).

curl -H "Authorization: Bearer <your-api-key>" "https://api.marine.metservice.com/tide/v4/health"
# Returns: {"status": "ok"}

Time Handling

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

• Start and end (from_date_time, to_date_time): Define the window as two ISO 8601 UTC timestamps.
  • Default: If both are omitted, defaults to Now until 7 days from now.
  • One bound only: from_date_time on its own returns 7 days from that time. to_date_time on its own returns the 7 days up to that time.
  • Example: from_date_time=2025-06-01T00:00:00Z&to_date_time=2025-06-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)

Multi-Point Requests (Batching)

The Tide API supports requesting predictions for multiple coordinates in a single GET request using the latitudes and longitudes array parameters. This returns a "Grouped Array" response where predictions are nested under their respective coordinates.

Performance Trade-off & Limits: Because the internal model engine must individually compute the astronomical harmonics for every single point requested, latency degrades linearly (O(N)) as you add more coordinates.

• Points per request: There is no fixed limit, but response time grows with the number of points. For quick responses, keep requests to about 10 points and split larger sets across several requests.
• Recommendation: For high-volume polling, aggressively cache the responses natively within your application architecture.

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.