Bulletins API Documentation

Bulletins Endpoints Overview

Meteomatics provides official advisory bulletins, such as tropical cyclone warnings, through an endpoint family that returns the decoded content of each bulletin as GeoJSON together with the original text message.

A bulletin is split into its labeled sections (for example the current center fix, each forecast track point, or a wind envelope). Each section is returned as one GeoJSON Feature, merged with the fields of the bulletin it belongs to.

Bulletin types

Currently the following types are available:

Tropical cyclone

Endpoints

The Bulletins API uses two endpoint patterns:

/bulletins/<datetime>/<bulletin_type>/<location>/<format>
Use this endpoint when you want the latest known advisory state at a single point in time. For each WMO document identifier (for example WTPN33, which corresponds to one storm), the most recent advisory issued at or before datetime is selected, provided it is still valid at that time (its valid_to is not before datetime). Advisories without a valid_to are not returned. Each feature represents one section of a selected advisory (see Section kinds), merged with that advisory's own fields (issuer, validity period, raw text, ...).
/bulletins-history/<start_timestamp>--<end_timestamp>/<bulletin_type>/<location>/<format>
Use this endpoint when you want every advisory received over a time range. It is intended for use cases such as monitoring, auditing, replaying historical situations, or building downstream systems that need a complete record of advisory activity over time. Unlike /bulletins, which returns the latest state at one instant, /bulletins-history returns all advisories (new issuances as well as updates) received during the interval, including those with an empty valid_to.

Request parameters

Datetime

datetime is used in /bulletins. It is a single point in time as an ISO 8601 UTC datetime, or a supported time shortcut such as now.

Format: YYYY-MM-DDThh:mm:ssZ

It must resolve to a single timestamp, not a range. Use /bulletins-history for a time range.

Time range

start_timestamp and end_timestamp are used in /bulletins-history.

Format: YYYY-MM-DDThh:mm:ssZ--YYYY-MM-DDThh:mm:ssZ

Time shortcuts such as now are supported. start_timestamp must not be later than end_timestamp.

Time semantics

For /bulletins-history, the requested interval is matched against inserted_at, the time the bulletin was ingested into the Meteomatics system. It is not matched against issued_at or the validity period (valid_from / valid_to).

Bulletin type

bulletin_type identifies the bulletin type.

Options:

tropical_cyclone

Location

location is the spatial scope of the query. Supported forms:

Bounding box <lat_max>,<lon_min>_<lat_min>,<lon_max>
Named shortcuts such as global or switzerland

The location filter is applied to the advisory as a whole: an advisory is included if its overall bounding box intersects location. All sections of an included advisory are then returned, including those whose geometry lies outside location.

Format

Only geojson is supported at the moment.

Optionals

Query parameters are not yet available. Passing any will return HTTP 501.

GeoJSON response specification

The response has the MIME type application/geo+json. The top level is always a FeatureCollection:

{
  "version": "3.0",
  "user": "<user id>",
  "dateGenerated": "<timestamp>",
  "status": "OK",
  "type": "FeatureCollection",
  "product": "tropical_cyclone",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {}
    }
  ]
}

product echoes the requested bulletin_type.

Each feature represents one section of one advisory. The properties object combines the per-bulletin fields (repeated on every feature of that bulletin), the per-section fields (unique_id, kind, time) and fields specific to the section kind.

All timestamps are ISO 8601 UTC, for example 2026-08-24T09:00:00Z. Coordinates follow GeoJSON order [longitude, latitude]. The order of features is not guaranteed.

Tropical cyclone bulletins

Tropical cyclone bulletins are warnings issued by tropical cyclone warning centers, for example the Joint Typhoon Warning Center (PGTW). Each advisory describes the current position and intensity of a storm together with its forecast positions and wind and sea extents.

Mandatory fields

The following fields are present on every feature.

field name	type	description
`issuer`	string	WMO originating/transmitting center abbreviation, for example `PGTW`.
`issued_at`	string	Time when the bulletin was issued (UTC).
`wmo_document_identifier`	string	WMO abbreviated heading, for example `WTPN33`. One identifier corresponds to one storm.
`valid_from`	string	Start of the validity period of the bulletin (UTC). For `wind_swath` and `storm_track` features this is the more specific validity window of that section.
`valid_to`	string	End of the validity period of the bulletin (UTC), or `""` if not present. For `wind_swath` and `storm_track` features this is the more specific validity window of that section. An empty value can only occur in `/bulletins-history`, because `/bulletins` does not return advisories without a `valid_to`.
`raw_message`	string	Full text of the original bulletin as received.
`inserted_at`	string	Time when the bulletin was ingested into the Meteomatics system (UTC). This is the time used by `/bulletins-history`.
`basin`	string	Ocean basin code the storm was tracked in (ATCF basin code), for example `WP`.
`storm_id`	string	Identifier of the storm, stable across all of its advisories, for example `19W`.
`storm_name`	string	Name of the storm, normalized to upper case letters, with runs of dashes collapsed into a single dash (for example `ATSANI`, `MAN-YI`).
`storm_term`	string	Terminology used for the storm in its current location. Different terms are used around the globe: `cyclone`, `hurricane`, `typhoon`.
`advisory_number`	integer	Sequence number of the advisory within the lifetime of the storm.
`unique_id`	string	Identifier of this feature (one section of one advisory), composed as `<storm_name>_<issuer>_<wmo_document_identifier>_<issued_at>_<kind>_<time>`. Both timestamps use the compact form `YYYYMMDDTHHMMSSZ`. See the note below.
`kind`	string	Which section of the advisory this feature represents. See Section kinds.
`time`	string	Time this section applies to (UTC).

Uniqueness of unique_id is not guaranteed: sections of the same kind sharing the same time (for example wind envelopes for different thresholds) get the same id. It is not a UUID and does not identify the storm; use storm_id for that.

Value objects

Measurements are given as objects of the form {"value": <number or string>, "unit": <string>}, for example {"value": 30, "unit": "knots"}. Free-text values are tagged with "unit": "string".

Radii per quadrant are given as objects with the keys north_east, south_east, south_west and north_west, each holding a value object.

Optional fields

The following fields are conditional. They only appear on features of the listed kind, and only when the information is present in the bulletin.

field name	kind	type	description
`wind_speed`	`center`	value object	Current or forecast wind speed.
`wind_gust`	`center`	value object	Current or forecast wind gust.
`report_type`	`center`	string	Whether this fix is an `observation` or a `forecast`.
`forecast_ahead`	`center`	value object	Hours ahead of issuance this fix applies to. Absent for the current-observation fix (see `report_type`).
`classification`	`center`, `dissipated`	value object	For `center`: free-text system status (for example `BECOMING EXTRATROPICAL`). For `dissipated`: always present, the reason the storm no longer meets tropical cyclone criteria (for example `DISSIPATED`).
`position_accuracy`	`center`	value object	Accuracy of the reported position.
`motion_speed`	`center`	value object	Speed of the storm movement.
`motion_direction`	`center`	value object	Direction of the storm movement.
`minimum_central_pressure`	`center`	value object	Minimum central pressure.
`wave_height_threshold`	`sea_envelope`	value object	Wave height threshold the envelope refers to.
`sea_envelope_radii`	`sea_envelope`	quadrant radii	Extent of the wave height threshold per quadrant.
`wind_threshold`	`wind_envelope`, `wind_swath`	value object	Wind speed threshold the envelope or swath refers to.
`wind_envelope_radii`	`wind_envelope`	quadrant radii	Extent of the wind threshold per quadrant.

Section kinds

The kind field tells which labeled section of the advisory a feature represents.

kind	description
`center`	A center fix of the storm: the current position (`report_type` `observation`) or a forecast position (`report_type` `forecast`). Geometry is a `Point`.
`dissipated`	The storm no longer meets tropical cyclone criteria. The reason is given in `classification`. Geometry is `null`.
`sea_envelope`	Extent of a wave height threshold around the storm. Geometry is a `Polygon`.
`wind_envelope`	Extent of a wind speed threshold around the storm. Geometry is a `Polygon`, or a `MultiPolygon` when the envelope consists of several separate areas.
`wind_swath`	Area swept by a wind speed threshold over the validity window of the section. Geometry is a `Polygon`.
`storm_track`	Track of the storm over the validity window of the section. Geometry is a `LineString`.

Geometry

A geometry is attached to a feature when the underlying section has one. It is null for sections that carry no spatial extent.

Attribute	Value
Type	`Point` for a center fix, `LineString` for a storm track, `Polygon` or `MultiPolygon` for envelopes and swaths
CRS	WGS84 (EPSG:4326)
Coordinates	`[longitude, latitude]`

If the section carries no spatial extent, the feature is still returned, with:

{
  "type": "Feature",
  "geometry": null,
  "properties": {}
}

Lifecycle

/bulletins returns, per WMO document identifier, the newest advisory issued at or before the requested time that is still valid (valid_to not before the requested time). A newer advisory for the same identifier supersedes the older one.
/bulletins-history returns every advisory ingested in the interval, including superseded ones.
When a storm no longer meets tropical cyclone criteria, a dissipated section is returned.

Examples

Bulletins – State endpoint

Request:

/bulletins/2026-08-24T09:00:00Z/tropical_cyclone/global/geojson

Response (excerpt):

{
  "version": "3.0",
  "user": "demo_user",
  "dateGenerated": "2026-08-28T13:09:16Z",
  "status": "OK",
  "type": "FeatureCollection",
  "product": "tropical_cyclone",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "issuer": "PGTW",
        "issued_at": "2026-08-24T09:00:00Z",
        "wmo_document_identifier": "WTPN33",
        "valid_from": "2026-08-24T06:00:00Z",
        "valid_to": "2026-08-25T18:00:00Z",
        "raw_message": "WTPN33 PGTW 240900\nMSGID/GENADMIN/JOINT TYPHOON WRNCEN PEARL HARBOR HI//\nSUBJ/TROPICAL DEPRESSION 19W (ATSANI) WARNING NR 008//\n...",
        "inserted_at": "2026-08-24T07:45:05Z",
        "basin": "WP",
        "storm_id": "19W",
        "storm_name": "ATSANI",
        "storm_term": "typhoon",
        "advisory_number": 8,
        "unique_id": "ATSANI_PGTW_WTPN33_20260824T090000Z_center_20260824T090000Z",
        "kind": "center",
        "time": "2026-08-24T09:00:00Z",
        "wind_speed": {
          "value": 30,
          "unit": "knots"
        },
        "wind_gust": {
          "value": 40,
          "unit": "knots"
        },
        "report_type": "observation"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [137.4, 14.2]
      }
    }
  ]
}

Bulletins – History endpoint

Request:

/bulletins-history/2026-08-25T00:00:00Z--2026-08-26T00:00:00Z/tropical_cyclone/global/geojson

This returns all tropical cyclone advisories that were ingested during the requested period.

Response (excerpt):

{
  "version": "3.0",
  "user": "demo_user",
  "dateGenerated": "2026-08-28T13:09:16Z",
  "status": "OK",
  "type": "FeatureCollection",
  "product": "tropical_cyclone",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "issuer": "PGTW",
        "issued_at": "2026-08-24T09:00:00Z",
        "wmo_document_identifier": "WTPN33",
        "valid_from": "2026-08-24T06:00:00Z",
        "valid_to": "2026-08-25T18:00:00Z",
        "raw_message": "WTPN33 PGTW 240900\nMSGID/GENADMIN/JOINT TYPHOON WRNCEN PEARL HARBOR HI//\nSUBJ/TROPICAL DEPRESSION 19W (ATSANI) WARNING NR 008//\n...",
        "inserted_at": "2026-08-24T07:45:05Z",
        "basin": "WP",
        "storm_id": "19W",
        "storm_name": "ATSANI",
        "storm_term": "typhoon",
        "advisory_number": 8,
        "unique_id": "ATSANI_PGTW_WTPN33_20260824T090000Z_center_20260824T090000Z",
        "kind": "center",
        "time": "2026-08-24T09:00:00Z",
        "wind_speed": {
          "value": 30,
          "unit": "knots"
        },
        "wind_gust": {
          "value": 40,
          "unit": "knots"
        },
        "report_type": "observation"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [137.4, 14.2]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "issuer": "PGTW",
        "issued_at": "2026-08-24T09:00:00Z",
        "wmo_document_identifier": "WTPN32",
        "valid_from": "2026-08-24T06:00:00Z",
        "valid_to": "2026-08-26T18:00:00Z",
        "raw_message": "WTPN32 PGTW 240900\nMSGID/GENADMIN/JOINT TYPHOON WRNCEN PEARL HARBOR HI//\nSUBJ/TROPICAL STORM 18W (NARRA) WARNING NR 015//\n...",
        "inserted_at": "2026-08-24T07:50:05Z",
        "basin": "WP",
        "storm_id": "18W",
        "storm_name": "NARRA",
        "storm_term": "typhoon",
        "advisory_number": 15,
        "unique_id": "NARRA_PGTW_WTPN32_20260824T090000Z_dissipated_20260824T090000Z",
        "kind": "dissipated",
        "time": "2026-08-24T09:00:00Z",
        "classification": {
          "value": "DISSIPATED",
          "unit": "string"
        }
      },
      "geometry": null
    }
  ]
}

Errors

Errors are returned as plain text (text/plain; charset=UTF-8) with the following status codes:

status	description
`400`	Bad request, for example a malformed datetime, a time range given to `/bulletins`, an end timestamp before the start timestamp, an unsupported `bulletin_type`, or an invalid location or format.
`401`	Unauthorized.
`403`	Forbidden. The authenticated user does not have access to this data.
`500`	Internal server error.
`501`	Not implemented. Returned when query parameters (`optionals`) are supplied.