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.

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)
`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. By default all legs start as “green” — if any risky weather condition is detected along the leg, it is escalated to “amber” or “red” with an explanation.

{
  "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": {},
        "cargo": {
          "humidity": {
            "risk": "red",
            "reasons": [
              "relative humidity is greater than 60 %"
            ]
          }
        },
        "crew": {}
      }
    },
    {
      "start": {
        "time": "2024-01-15T04:00:00",
        "lat": 23.32,
        "lon": -62.11
      },
      "end": {
        "time": "2024-01-15T05:00:00",
        "lat": 23.36,
        "lon": -62.13
      },
      "combined_risk": "green",
      "risk_factors": {
        "vessel": {},
        "cargo": {},
        "crew": {}
      }
    }
  ]
}

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, {})
        if factors:
            for factor, detail in factors.items():
                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']}")