Maritime Insights - Spire Weather API Documentation

Insights is an API-based service that provides actionable weather outcomes for specific use cases. The Maritime Insights endpoints combine weather forecast data with vessel characteristics and domain knowledge to deliver direct operational guidance.

Endpoints¶

Method	Endpoint	Description
POST	`/insights/maritime/route?type=risk`	Get vessel risk assessment along a route
POST	`/insights/maritime/route?type=efficiency`	Get vessel efficiency forecast along a route

Vessel Risk Insight¶

POST /insights/maritime/route?type=risk

Assess weather-related risk to the vessel, cargo, and crew along a planned route. The result uses a traffic-light system (Red, Amber, Green) for each leg of the voyage, with explanations of the risk factors.

How It Works¶

The waypoints describe the planned movement of the vessel and when it will be at each position. The service splits every leg between two waypoints into smaller steps and checks the forecast weather at each step, at the time the vessel is expected to be there, taking the vessel’s heading relative to wind, waves and swell into account. All legs start as green. If any step of a leg meets a risky condition for the vessel, its cargo or its crew, the whole leg becomes amber or red and the reasons are listed. The assessment uses Spire’s 15-day global forecast, so routes can be checked up to 15 days ahead.

Query Parameters¶

Parameter	Type	Required	Description
`type`	string	Yes	Must be `risk`

Request Body¶

{
  "route": {
    "waypoints": [
      {
        "lat": 23.25,
        "lon": -62.10,
        "time": "2024-01-15T03:00:00"
      },
      {
        "lat": 23.32,
        "lon": -62.11,
        "time": "2024-01-15T04:00:00"
      },
      {
        "lat": 23.36,
        "lon": -62.13,
        "time": "2024-01-15T05:00:00"
      },
      {
        "lat": 23.42,
        "lon": -62.16,
        "time": "2024-01-15T06:00:00"
      }
    ]
  },
  "vessel": {
    "vessel_type": "container_ship",
    "vessel_state": "low_gm"
  },
  "configuration": "default"
}

Request Body Fields¶

Field	Type	Required	Description
`route`	object	Yes	Route definition
`route.waypoints`	array	Yes	Array of waypoints (max 120)
`vessel`	object	Yes	Vessel configuration
`vessel.vessel_type`	string	Yes	Type of vessel (see table below)
`vessel.vessel_state`	string	Yes	Loading state of vessel (see table below)
`vessel.cargo_type`	string	No	`wx_sensitive` or `general`; influences the cargo risk factors
`configuration`	string	No	Custom threshold configuration name

Vessel Configurations¶

Vessel Type	Available States
`container_ship`	`low_gm`, `medium_gm`, `high_gm`
`bulk_carrier`	`in_ballast`, `loaded_small`, `loaded_half`, `loaded_full`
`tanker`	`in_ballast`, `loaded`
`general_cargo`	`low_gm`, `medium_gm`, `high_gm`

Response¶

Each leg of the route receives risk assessments for vessel, cargo, and crew. Every factor is listed for every leg: factors without a detected hazard carry "risk": "green" and an empty reasons list, and any factor with a risky condition is escalated to amber or red with an explanation. combined_risk is the worst factor on the leg.

{
  "meta": {},
  "data": [
    {
      "start": {
        "time": "2024-01-15T03:00:00",
        "lat": 23.25,
        "lon": -62.10
      },
      "end": {
        "time": "2024-01-15T04:00:00",
        "lat": 23.32,
        "lon": -62.11
      },
      "combined_risk": "red",
      "risk_factors": {
        "vessel": {
          "visibility": { "risk": "green", "reasons": [] },
          "ice_accretion": { "risk": "green", "reasons": [] },
          "wind": {
            "risk": "red",
            "reasons": [
              "wind direction is between 45 and 135 ° from movement direction",
              "wind speed is between 5 and 16 m/s"
            ]
          },
          "gust": {
            "risk": "red",
            "reasons": [
              "wind direction is between 45 and 135 ° from movement direction",
              "wind gust is between 5 and 16 m/s"
            ]
          },
          "waves": { "risk": "green", "reasons": [] },
          "wind_waves": { "risk": "green", "reasons": [] },
          "swell": { "risk": "green", "reasons": [] }
        },
        "cargo": {
          "wind": { "risk": "red", "reasons": ["wind speed is between 5 and 16 m/s"] },
          "humidity": { "risk": "green", "reasons": [] }
        },
        "crew": {
          "wind": { "risk": "amber", "reasons": ["wind speed is between 5 and 16 m/s"] }
        }
      }
    }
  ]
}

Risk Categories¶

Risk factors are classified into three categories:

Category	Weather Factors Considered
Vessel	Visibility, wind (general), ice accretion, wind gusts, wind waves, waves, swell
Cargo	Dew point, temperature, humidity, wind, wind gusts, wind waves, waves, swell
Crew	Wind (general), wind gusts, wind waves, waves, swell, functional temperature

Risk Levels¶

Level	Meaning
`green`	No significant weather risk
`amber`	Moderate weather risk — caution advised
`red`	High weather risk — conditions may be hazardous

Customized Thresholds¶

Spire provides default thresholds for risk classification, but custom threshold configurations can be created. A customer can maintain multiple configurations (e.g., “conservative” vs. “risk-tolerant”) and specify which to use per request via the configuration field.

Contact Spire for configuration of custom threshold settings.

Vessel Efficiency Insight¶

POST /insights/maritime/route?type=efficiency

Forecast the expected efficiency of a planned route based on weather conditions. Uses a five-color ranking from worst to best conditions for vessel efficiency.

Query Parameters¶

Parameter	Type	Required	Description
`type`	string	Yes	Must be `efficiency`

Request Body¶

Uses the same request body structure as the Risk insight (route + vessel configuration).

Response¶

Each leg receives an overall efficiency rating and per-parameter breakdowns:

{
  "meta": {},
  "data": [
    {
      "start": {
        "time": "2024-01-15T03:00:00",
        "lat": 23.25,
        "lon": -62.10
      },
      "end": {
        "time": "2024-01-15T09:00:00",
        "lat": 23.50,
        "lon": -62.30
      },
      "combined_efficiency": "orange",
      "efficiency_factors": {
        "ocean_currents": {
          "efficiency": "red"
        },
        "mean_waves": {
          "efficiency": "light green"
        },
        "wind_waves": {
          "efficiency": "orange"
        },
        "swell_waves": {
          "efficiency": "light green"
        },
        "winds_10m": {
          "efficiency": "orange"
        },
        "winds_50m": {
          "efficiency": "orange"
        }
      }
    }
  ]
}

Efficiency Levels¶

Ranked from worst to best:

Level	Meaning
`red`	Worst efficiency — strong adverse conditions
`orange`	Poor efficiency
`grey`	Neutral conditions
`light green`	Good efficiency
`green`	Best efficiency — favorable conditions

Weather Factors¶

The efficiency calculation considers the following factors, weighted by vessel type, load, and heading relative to the weather:

Factor	Description
`winds_10m`	10-meter wind speed and direction
`winds_50m`	50-meter wind speed and direction
`ocean_currents`	Ocean current speed and direction
`mean_waves`	Total (combined wind + swell) wave height and direction
`swell_waves`	Swell wave height and direction
`wind_waves`	Wind wave height and direction

Time Alignment¶

For both insight types, when requested waypoint times do not align with available forecast times, the response uses the nearest available time. The response includes both times:

{
  "times": {
    "issuance_time": "2024-01-13T12:00:00+00:00",
    "valid_time": "2024-01-15T12:00:00+00:00",
    "requested_valid_time": "2024-01-15T13:10:00+00:00"
  }
}

Example Request¶

Shell

Python

Node.js

curl -X POST \
  'https://api.wx.spire.com/insights/maritime/route?type=risk' \
  -H 'spire-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "route": {
      "waypoints": [
        {"lat": 0.0, "lon": 0.0, "time": "2024-01-15T22:00:00"},
        {"lat": 0.5, "lon": 0.5, "time": "2024-01-16T04:00:00"},
        {"lat": 1.0, "lon": 1.0, "time": "2024-01-16T10:00:00"},
        {"lat": 1.5, "lon": 1.5, "time": "2024-01-16T16:00:00"},
        {"lat": 2.0, "lon": 2.0, "time": "2024-01-16T22:00:00"}
      ]
    },
    "vessel": {
      "vessel_type": "container_ship",
      "vessel_state": "low_gm"
    }
  }'

import requests

response = requests.post(
    "https://api.wx.spire.com/insights/maritime/route",
    params={"type": "risk"},
    headers={"spire-api-key": "YOUR_API_KEY"},
    json={
        "route": {
            "waypoints": [
                {"lat": 0.0, "lon": 0.0, "time": "2024-01-15T22:00:00"},
                {"lat": 0.5, "lon": 0.5, "time": "2024-01-16T04:00:00"},
                {"lat": 1.0, "lon": 1.0, "time": "2024-01-16T10:00:00"},
                {"lat": 1.5, "lon": 1.5, "time": "2024-01-16T16:00:00"},
                {"lat": 2.0, "lon": 2.0, "time": "2024-01-16T22:00:00"},
            ]
        },
        "vessel": {
            "vessel_type": "container_ship",
            "vessel_state": "low_gm",
        },
    },
)
data = response.json()

const response = await fetch(
  "https://api.wx.spire.com/insights/maritime/route?type=risk",
  {
    method: "POST",
    headers: {
      "spire-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      route: {
        waypoints: [
          { lat: 0.0, lon: 0.0, time: "2024-01-15T22:00:00" },
          { lat: 0.5, lon: 0.5, time: "2024-01-16T04:00:00" },
          { lat: 1.0, lon: 1.0, time: "2024-01-16T10:00:00" },
          { lat: 1.5, lon: 1.5, time: "2024-01-16T16:00:00" },
          { lat: 2.0, lon: 2.0, time: "2024-01-16T22:00:00" },
        ],
      },
      vessel: {
        vessel_type: "container_ship",
        vessel_state: "low_gm",
      },
    }),
  }
);
const data = await response.json();

Python Example¶

Compare risk and efficiency for a voyage:

import requests

headers = {
    'spire-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

route_data = {
    "route": {
        "waypoints": [
            {"lat": 0.0, "lon": 0.0, "time": "2024-01-15T22:00:00"},
            {"lat": 0.5, "lon": 0.5, "time": "2024-01-16T04:00:00"},
            {"lat": 1.0, "lon": 1.0, "time": "2024-01-16T10:00:00"},
            {"lat": 1.5, "lon": 1.5, "time": "2024-01-16T16:00:00"},
            {"lat": 2.0, "lon": 2.0, "time": "2024-01-16T22:00:00"}
        ]
    },
    "vessel": {
        "vessel_type": "bulk_carrier",
        "vessel_state": "loaded_full"
    }
}

# Get risk assessment
risk_response = requests.post(
    'https://api.wx.spire.com/insights/maritime/route?type=risk',
    headers=headers,
    json=route_data
)
risk_data = risk_response.json()['data']

print("=== Risk Assessment ===")
for i, leg in enumerate(risk_data):
    print(f"Leg {i+1}: {leg['combined_risk'].upper()}")
    for category in ['vessel', 'cargo', 'crew']:
        factors = leg['risk_factors'].get(category, {})
        # Every factor is present; print only the ones that were escalated
        for factor, detail in factors.items():
            if detail['risk'] != 'green':
                print(f"  {category}/{factor}: {detail['risk']} - {', '.join(detail['reasons'])}")

# Get efficiency forecast
efficiency_response = requests.post(
    'https://api.wx.spire.com/insights/maritime/route?type=efficiency',
    headers=headers,
    json=route_data
)
efficiency_data = efficiency_response.json()['data']

print("\n=== Efficiency Forecast ===")
for i, leg in enumerate(efficiency_data):
    print(f"Leg {i+1}: {leg['combined_efficiency']}")
    for factor, detail in leg['efficiency_factors'].items():
        print(f"  {factor}: {detail['efficiency']}")