<!-- block-id: about -->

## Storm Tracker API Integration Guide

### What Storm Tracker gives you

Storm Tracker is an OpenWeather API that returns everything you need to draw active tropical cyclones (hurricanes, typhoons, tropical storms) on a map in a single GeoJSON response.

For every active storm, one request gives you:

- the current center position and the size of the strong-wind zone (winds of 34 kt / ~63 km/h and above);
- the most likely track for up to 10 days ahead — the OpenWeather consensus of 10+ forecast models (ECMWF, GFS, UK Met Office, NOAA hurricane models and others);
- an uncertainty cone showing how much the models disagree;
- the official NHC (US National Hurricane Center) forecast cone for Atlantic and Pacific storms.

You do not need to download or decode raw model data, resolve storm identifiers or average models yourself. The service merges the sources, drops outlier forecasts, normalizes model names and returns a ready-to-draw result.

| **Basin code** | **Region** | **Local name** |
| --- | --- | --- |
| AL | Atlantic | hurricane |
| EP | Eastern Pacific | hurricane |
| CP | Central Pacific | hurricane |
| WP | Western Pacific | typhoon |
| IO | Indian Ocean | cyclone |
| SH | Southern Hemisphere | cyclone |

A storm stays in the response while its last observed position is no older than 3 days. Storm IDs follow the standard pattern, e.g. `al052024` — the 5th Atlantic storm of the 2024 season.

The service is based on forecast models and official advisories only; it does not use radar or satellite imagery.

<!-- block-id: how_get -->

## How to get the data

All data comes from a single endpoint. Pass your OpenWeather API key in the `appid` parameter. The default call returns the consensus product for every active storm:

```text
GET https://api.openweathermap.org/data/2.5/storms/geojson?appid={API key}
```

### Choose what to receive

Use the `feature_types` parameter to request only the layers you draw. This keeps the payload small.

```text
GET https://api.openweathermap.org/data/2.5/storms/geojson?appid={API key}&feature_types=current_position,consensus_track,uncertainty_cone,forecast_cone
```

| **Request** | **What you get** | **Typical use** |
| --- | --- | --- |
| `/storms/geojson?appid={API key}` | Consensus track, cones, current position and wind zone for all storms | Default product map |
| `…&feature_types=a,b,c` | Only the listed feature types | Lightweight map layers, mobile |
| `…&feature_types=all` | Everything, including each model's own track | Expert / comparison views |
| `…&model=ECMWF` | One model only (also AVNX, UKM, HWRF, …) | Model comparison, debugging |

In single-model mode, storms that this model does not forecast are omitted. Single-model mode is not the consensus — it shows that model's raw track only.

<!-- block-id: response -->

### Response shape

The response is a standard GeoJSON `FeatureCollection`. The `metadata` block tells you when the snapshot was built and how many storms are active; each `feature` carries a `feature_type` property that tells you how to draw it.

```json
{
  "type": "FeatureCollection",
  "metadata": {
    "generated_at": "2024-09-10T18:05:00Z",
    "sources": ["atcf", "ecmwf", "nhc"],
    "active_storms": 3,
    "mode": "consensus"
  },
  "features": [ ... ]
}
```

Coordinates are `[longitude, latitude]` with longitude in the −180…180 range, as in any GeoJSON.

<!-- block-id: how_often_poll -->

### How often to poll

The underlying forecasts update every 6–12 hours and the service rebuilds its snapshot about once an hour. Polling once every 30–60 minutes is enough; there is no benefit in polling more often. Check `metadata.generated_at` to see whether the snapshot has changed.

If the service is rebuilding, you may briefly receive the previous snapshot instead of waiting — this is expected and safe to display.

<!-- block-id: how_integrate -->

## How to integrate the data into your map

Every feature in the response has a feature_type property. Switch on it to decide how to draw the feature. A typical product map uses the first six rows; the rest are optional.

| **feature_type** | **Geometry** | **What it shows** | **Suggested rendering** |
| --- | --- | --- | --- |
| `current_position` | Point | Where the storm center is now | Marker / eye icon |
| `wind_radii` | Polygon | Zone with winds ≥ 34 kt right now | Filled area around the marker |
| `consensus_track` | LineString | Most likely path (OpenWeather consensus) | Main forecast line |
| `consensus_point` | Point | Forecast position at +24 h, +48 h, +72 h ... | Dots on the line with hour labels |
| `uncertainty_cone` | Polygon | How much the models disagree | Translucent cone around the line |
| `forecast_cone` | Polygon | Official NHC cone (Atlantic / Pacitic only) | Separate toggleable layer |
| `per_model_tracks` | LineString | Each model's own track (feature_types=all) | Thin colored lines, off by default |
| `forecast_track` / `forecast_point` / `forecast_wind_radii` | Line / Point / Polygon | Single-model track, points and wind zone (?model=...) | Expert views only |

<!-- block-id: properties -->

### Properties you will use

- **Storm identity**: storm ID (e.g. `al052024`), name and basin — group all features of one storm by its ID.
- **Forecast hour** (`tau_h`): hours after the model run start. Forecast points are available at 0, 6, 12, 24, 36, 48, 72, 96, 120, 168 and 240 hours.
- **Wind speed** (`wind_kts`) and **category**: see the tables below.
- **Wind radii** (`radii_ne_nm`, `radii_se_nm`, `radii_sw_nm`, `radii_nw_nm`): how far the 34 kt wind zone extends in each quadrant, in nautical miles. The polygon is already built for you; these numbers are for labels or tooltips.
- **Source** on cones: `forecast_cone` has `source: "nhc"`, so you can label it as the official product.

<!-- block-id: units -->

### Units

Tropical meteorology uses nautical units. Convert them for display if your users expect metric.

| **Unit** | **Equals** | **Example** |
| --- | --- | --- |
| Knot (kt) | = 1.85 km/h = 0.51 m/s | 64 kt = 119 km/h, the Category 1 threshold |
| Nautical mile (nm) | = 1.85 km | Wind radius 120 nm = 222 km |

<!-- block-id: saffir_simpson -->

### Saffir–Simpson category

The category is derived from the maximum sustained wind in knots. Use it to color markers and tracks.

| **Category** | **Wind (kt)** | **Meaning** |
| --- | --- | --- |
| -1 | unknown | No wind data |
| 0 | < 64 | Tropical storm or depression |
| 1 | 64-82 | Hurricane, Category 1 |
| 2 | 83-95 | Category 2 |
| З | 96-112 | Major hurricane, Category 3 |
| 4 | 113-136 | Category 4 |
| 5 | ≥ 137 | Category 5 |

<!-- block-id: cones -->

### Two cones, two meanings

`uncertainty_cone` and `forecast_cone` can look alike but are independent products. Show them as separate layers with different styling and labels.

- **uncertainty_cone** — computed by OpenWeather from the spread of the forecast models around the consensus track. Wider cone means the models disagree more.
- **forecast_cone** — the official NHC cone, the same one shown on NHC advisories. Present only for Atlantic, Eastern and Central Pacific storms; Western Pacific typhoons and other basins have no NHC cone.

<!-- block-id: recommended_steps -->

### Recommended integration steps

1. Call *https://api.openweathermap.org/data/2.5/storms/geojson?appid={API key}* with the `feature_types` your map needs.
2. Group features by storm ID.
3. Draw layers bottom-up: `forecast_cone`, `uncertainty_cone`, `wind_radii`, `consensus_track`, `consensus_point`, `current_position`.
4. Color by category and label points with `tau_h` and wind speed.
5. Refresh every 30–60 minutes and redraw when `metadata.generated_at` changes.

<!-- block-id: faq -->

## Frequently asked questions

#### **Where does the forecast come from?**

From the official ATCF storm database (NCAR/UCAR), ECMWF Open Data and NHC advisories. The consensus track is a weighted average of the models, with ECMWF carrying the highest weight; models that drift far from the group at a given forecast hour are excluded from that hour.

#### **Why does a storm appear with a new ID?**

An unnamed candidate system (ID numbers 90–99, e.g. `al952024`) may be renumbered and named once it strengthens (e.g. `al052024`). The service merges both records into one storm, so you will see one object, not two.

#### **Why is there no **`forecast_cone`** for some storms?**

NHC covers only the Atlantic, Eastern and Central Pacific. Storms elsewhere have the OpenWeather `uncertainty_cone` only.

#### **Why has the response not changed in the last hour?**

Forecast models update every 6–12 hours and the snapshot is rebuilt about once an hour. Compare `metadata.generated_at` between calls.

#### **Why are some forecast points missing at longer lead times?**

he service stops extending a track when fewer than two models agree or when the forecast becomes physically implausible. A shorter track means low confidence beyond that hour.

#### **Are 50 kt and 64 kt wind zones available?**

Not yet — the API currently exposes the 34 kt zone only.

#### **Can I get the data for one model only?**

Yes, with `?model=ECMWF` (or `AVNX`, `UKM`, `HWRF`, `HMON`, `HFSA`, `HFSB`, `CMC`, `NVGM`). This is intended for comparison views; use the default consensus mode for end-user maps.