NAVTEX Messages API

Access maritime safety information through the NAVTEX API. Query weather warnings, navigation hazards, search and rescue alerts, and other safety broadcasts. Messages are collected every 6 hours.

What is NAVTEX?

NAVTEX (Navigational Telex) is an international automated medium frequency direct-printing service for delivery of maritime safety information. It's a key component of the Global Maritime Distress and Safety System (GMDSS) and provides safety information to ships at sea.

NAVTEX stations around the world broadcast messages on standardized frequencies, covering coastal waters within approximately 200-400 nautical miles of the transmitter. The API collects and indexes these broadcasts, making them searchable and accessible through a simple REST interface.

Safety Note: While the API provides access to NAVTEX messages for informational and research purposes, it should not be used as a primary source for real-time safety decisions at sea. Always rely on direct NAVTEX reception and official maritime safety communications for navigation.

Message Categories

NAVTEX messages are categorized by subject identifier (B1 character). Each category serves a specific safety purpose:

A

Navigational Warnings

Hazards to navigation including uncharted dangers, changes to aids to navigation, and marine construction activities.

B

Meteorological Warnings

Gale warnings, storm warnings, and other hazardous weather information for mariners.

C

Ice Reports

Ice conditions and icebreaker operations in polar and subpolar regions.

D

Search and Rescue

SAR operations, distress alerts, and missing vessel information.

E

Weather Forecasts

Detailed marine weather forecasts for specific sea areas.

L

Navigation Warnings (Additional)

Supplementary navigational warnings and updates.

T

Piracy Warnings

Piracy alerts and security advisories for high-risk areas.

V-Z

Special Services

LORAN corrections, OMEGA corrections, and other special transmissions.

Use Cases

Voyage Planning

Query short-term historical and current NAVTEX messages along planned routes to identify potential hazards and weather conditions before departure.

Maritime Research

Analyze patterns in maritime safety messages for research into weather trends, hazard distributions, and SAR activity.

Situational Awareness

Build dashboards that display relevant safety information for specific geographic areas or vessel routes.

Risk Assessment

Incorporate safety message data into maritime risk models and insurance assessments.

Available Endpoints

GET /navtex

Get NAVTEX Messages

Retrieve NAVTEX messages within a specified time range.

Parameters:

  • time.from - Start of time range in RFC3339 format (optional, defaults to 24 hours ago)
  • time.to - End of time range in RFC3339 format (optional, defaults to current time)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results

v2 Endpoints (Premium)

The v2 endpoints split NAVTEX data into a meteorological feed (METAREA) and a navigational-hazard feed (NAVAREA) with richer filtering. They live under the /v2 base path and are available on the Starter, Growth, and Pro plans; other plans receive HTTP 403 with the error code feature_not_available. Filters that accept multiple values on these endpoints take them comma-separated in a single parameter (e.g. filter.navarea_id=IV,XII).

GET /v2/navtex/metarea PREMIUM

Get METAREA Meteorological Warnings

Retrieve METAREA (meteorological) NAVTEX warnings, filterable by area, coordinator, message type, and free text. Same underlying data as /v1/navtex with clearer naming. Unlike v1, the time range is fully optional: omit time.from / time.to to query without time bounds.

Parameters:

  • filter.metarea_id - METAREA id(s), comma-separated (e.g. 11 or 11,8N) (optional)
  • filter.coordinator - Coordinating country or countries, comma-separated (e.g. Japan) (optional)
  • filter.label - Message type, substring match (e.g. HIGH SEAS FORECAST) (optional)
  • filter.q - Free-text search over message content (optional)
  • time.from / time.to - Time range in RFC3339 format (optional; omit for no lower/upper bound)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results
GET /v2/navtex/navarea PREMIUM

Get NAVAREA Navigational Warnings

Retrieve NAVAREA navigational-hazard warnings with lifecycle, area, time, free-text, and geographic filters. By default only warnings currently in force are returned.

Parameters:

  • filter.status - Lifecycle filter: omit for in_force only (the default), all for every state, or one of in_force, expired, cancelled, cancellation, withdrawn (optional)
  • filter.include - Extra states to include alongside in_force, comma-separated (e.g. expired,cancelled) (optional)
  • filter.navarea_id - NAVAREA(s), comma-separated (e.g. IV,XII) (optional)
  • filter.coordinator - Coordinating country or countries, comma-separated (optional)
  • filter.year - Issue year (optional)
  • filter.issued_from / filter.issued_to - Issued on/after and on/before, RFC3339 format (optional)
  • filter.q - Free-text search over area and body (optional)
  • filter.near - Warnings within a radius of a point: lat,lon,radius_nm; the radius is in nautical miles (e.g. 24.5,-83.1,50) (optional)
  • filter.bbox - Warnings intersecting a bounding box: minLat,minLon,maxLat,maxLon (optional)
  • filter.sort - Sort as field:dir; fields first_seen_at, last_seen_at, issue_date, navarea_id; directions asc / desc (optional, default first_seen_at:desc)
  • pagination.limit - Results per page (max 50, default 20)
  • pagination.nextToken - Cursor for next page of results

Response includes:

  • warnings - Array of NAVAREA warning objects
  • nextToken - Pagination token for next page
  • disclaimer - Always present: a safety notice stating the data is for situational awareness only and not a substitute for official NAVAREA coordinator broadcasts

Code Examples

Get Recent Messages (cURL)

# The API defaults to the past 24 hours if time range is omitted
curl -X GET "https://api.vesselapi.com/v1/navtex" \
     -H "Authorization: Bearer YOUR_API_KEY"

Get Messages in Time Range (Python)

import requests
from datetime import datetime, timedelta

end_time = datetime.utcnow()
start_time = end_time - timedelta(days=7)

response = requests.get(
    "https://api.vesselapi.com/v1/navtex",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "time.from": start_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
        "time.to": end_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
        "pagination.limit": 50
    }
)

messages = response.json()
for msg in messages["navtexMessages"]:
    print(f"[{msg['label']}] {msg['issuing_office']}: {msg['raw_content'][:100]}")

Filter Messages Client-Side (JavaScript)

async function getPiracyAlerts() {
  const now = new Date();
  const weekAgo = new Date(now - 7 * 24 * 60 * 60 * 1000);

  const response = await fetch(
    `https://api.vesselapi.com/v1/navtex?` +
    new URLSearchParams({
      "time.from": weekAgo.toISOString(),
      "time.to": now.toISOString()
    }),
    { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
  );

  const data = await response.json();
  // Filter by label client-side
  return data.navtexMessages.filter(msg =>
    msg.raw_content.toLowerCase().includes("piracy")
  );
}

Response Fields

Field Description
label Message type (e.g., "NAVIGATIONAL WARNING")
issuing_office Office that issued the bulletin
timestamp UTC timestamp of the broadcast
raw_content Full message text
lines Message content as array of lines
metarea_name METAREA name (e.g., "South China Sea")
metarea_coordinator Coordinating country for the METAREA
metarea_id METAREA numeric identifier
metarea_region Geographic region of the METAREA
metarea_stations List of broadcast stations in the METAREA
wmo_header WMO header code

Access Maritime Safety Data

Try the NAVTEX endpoint interactively in the API Explorer.

Open API Explorer Get Your API Key

Related Documentation

Vessel Tracking

Track vessel positions alongside safety messages.

Navigation Infrastructure

Lighthouses, beacons, and other aids to navigation.