Tide API v4 Developer Guide

Integration Fact Sheet

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

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. Understanding the difference 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_height_above_mean_sea_level): 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.

Integration Workflow

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.

Available Resources

Tidal Models

The Tide API provides access to global, regional, and high-resolution local hydrodynamic models.

Dataset ID	Region	Description
Global & Regional
`tpxo9_glob_v9.4`	Global	TPXO9 Global Tidal Model v9.4 (1/6° resolution)
`tpxo9v4_nz`	New Zealand	NZ Regional Model (High resolution regional subset)
High-Resolution Harbours (NZ)
`mos_cs_v2.0`	Cook Strait	High-resolution Cook Strait model
`mos_gcs_v2.0`	Greater Cook Strait	Extended Greater Cook Strait model
`mos_hrki_v2.0`	Hauraki Gulf	Hauraki Gulf model
`mos_ihrki_v2.0`	Inner Hauraki Gulf	Inner Hauraki Gulf / Waitematā Harbour model
`mos_manukau_v2.0`	Manukau	Manukau Harbour model
`mos_raglan_v2.0`	Raglan	Raglan Harbour model
`mos_tau_v2.0`	Tauranga	Tauranga Harbour model
`mos_dnd_v2.0`	Dunedin	Otago Harbour / Dunedin model
`mos_hb_v2.0`	Hawke's Bay	Hawke's Bay model

Stations

Harmonic tidal predictions for standard ports and reference stations.

Sources:
- LINZ: Land Information New Zealand (official NZ tide tables).
- Coverage:
  - Primary Locations: Major commercial ports (e.g., Auckland, Wellington, Lyttelton, Tauranga, Napier, Nelson, Bluff).
  - Secondary Locations: Smaller coastal/recreational spots (e.g., Raglan, Akaroa, Kaikoura, Whitianga).
Discovery: Use the /stations endpoint to list all available station IDs.

Getting Started: Your First Forecast

1. Authorization

All requests require an API key provided in the Authorization header.

Authorization: ApiKey <your-api-key>

2. Choose Your Endpoint

For Specific Locations: GET /stations/{station_id}/tidetimes
For Coordinates: GET /models/{model_id}/tidetimes/points

3. 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"

Using the API

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

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:

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

Rate Limiting and Fair Use

The Tide API implements platform-wide rate limiting to ensure service stability.

Fair Use: Please avoid unnecessary polling. Tide data is astronomical and deterministic; it does not change in real-time like weather data.
Caching: Since tide predictions are calculated months or years in advance, you should aggressively cache responses. There is no need to request the same tide table for "today" more than once.

Error Handling

Errors follow the RFC 9457 standard.

{
  "type": "https://developer.metservice.com/docs/error-handling/#404-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Station 'invalid' not found."
}

Introduction​

Core Concepts​

Stations vs. Models​

Data Definitions​

Tide Times vs. Timeseries​

Integration Workflow​

1. Discovery​

2. Request Data​

3. Caching Strategy (Critical)​

Available Resources​

Tidal Models​

Stations​

Getting Started: Your First Forecast​

1. Authorization​

2. Choose Your Endpoint​

3. Make the API Call​

Using the API​

Checking API Status​

Time Handling​

Advanced Features​

Geospatial Discovery​

Rate Limiting and Fair Use​

Error Handling​