ocean-schedules

Compare ocean carriers serving an origin→destination port pair, ranked by on-time reliability and transit time. Use this to decide which line to book.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin port UN/LOCODE, e.g. CNSHA"
    },
    "destination": {
      "type": "string",
      "description": "Destination port UN/LOCODE, e.g. NLRTM"
    }
  },
  "required": [
    "origin",
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

On-time performance and delay distribution for a specific carrier (by SCAC), optionally on a given lane.

{
  "type": "object",
  "properties": {
    "carrier_code": {
      "type": "string",
      "description": "Carrier SCAC, e.g. MAEU"
    }
  },
  "required": [
    "carrier_code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Observed transit-time distribution (median / p90, in days) for a carrier on an origin→destination lane.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin port UN/LOCODE"
    },
    "destination": {
      "type": "string",
      "description": "Destination port UN/LOCODE"
    },
    "carrier_code": {
      "type": "string",
      "description": "Optional carrier SCAC to filter"
    }
  },
  "required": [
    "origin",
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Observed and derived upcoming departures on an origin→destination lane, with carrier and frequency.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin port UN/LOCODE"
    },
    "destination": {
      "type": "string",
      "description": "Destination port UN/LOCODE"
    }
  },
  "required": [
    "origin",
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Published forward sailing schedules on an origin→destination lane: carrier, vessel, voyage, ETD/ETA and cut-offs, soonest first. Sourced from carrier connectors (and aggregator coverage). Use this to find concrete upcoming departures to book.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin port UN/LOCODE, e.g. CNSHA"
    },
    "destination": {
      "type": "string",
      "description": "Destination port UN/LOCODE, e.g. NLRTM"
    }
  },
  "required": [
    "origin",
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Decision query: the best upcoming sailings on a lane, ONE per carrier (next bookable departure), ranked. Filter by date window, max transit days, min on-time reliability, cut-off still open, and direct-vs-transshipment. Use this to answer "what should I book?".

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin port UN/LOCODE or name resolves upstream, e.g. CNSHA"
    },
    "destination": {
      "type": "string",
      "description": "Destination port UN/LOCODE, e.g. NLRTM"
    },
    "from": {
      "type": "string",
      "description": "Earliest departure date YYYY-MM-DD (default: today)"
    },
    "to": {
      "type": "string",
      "description": "Latest departure date YYYY-MM-DD (default: +60 days)"
    },
    "max_transit_days": {
      "type": "number",
      "description": "Maximum transit time in days"
    },
    "reliability_floor": {
      "type": "number",
      "description": "Minimum 90-day on-time %, 0-100"
    },
    "cutoff_open": {
      "type": "boolean",
      "description": "Only sailings whose booking cut-off has not passed"
    },
    "direct_only": {
      "type": "boolean",
      "description": "Exclude transshipment routings"
    },
    "sort": {
      "type": "string",
      "enum": [
        "recommended",
        "reliability",
        "fastest",
        "soonest"
      ],
      "description": "Ranking (default recommended = reliability blended with transit)"
    }
  },
  "required": [
    "origin",
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Watch a lane for schedule alerts (PAID): get emailed when a sailing on it is blanked, a booking cut-off is about to close, or a sailing slips. Also alerts on reliability drops. Returns the created watch.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin port UN/LOCODE, e.g. CNNGB"
    },
    "destination": {
      "type": "string",
      "description": "Destination port UN/LOCODE, e.g. NLRTM"
    },
    "carrier_code": {
      "type": "string",
      "description": "Optional SCAC to scope the watch to one carrier"
    },
    "alert_blank": {
      "type": "boolean",
      "description": "Alert on suspected blank sailings (default true)"
    },
    "alert_cutoff": {
      "type": "boolean",
      "description": "Alert when a booking cut-off is closing (default true)"
    },
    "alert_slip": {
      "type": "boolean",
      "description": "Alert when a sailing slips vs schedule (default true)"
    },
    "cutoff_lead_hours": {
      "type": "number",
      "description": "Hours before cut-off to alert (default 48)"
    }
  },
  "required": [
    "origin",
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Congestion and dwell signals for a port (UN/LOCODE) — average wait and vessels at anchor.

{
  "type": "object",
  "properties": {
    "port": {
      "type": "string",
      "description": "Port UN/LOCODE, e.g. NLRTM"
    }
  },
  "required": [
    "port"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Carrier league table — ocean carriers ranked by overall on-time reliability across all tracked lanes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fused port-congestion signal for a port (UN/LOCODE): effective level (mild/moderate/severe), expected added wait in days (for ETA-band widening), a 0–1 confidence, and per-source detail — weiyun broad-AIS analysis + IMF PortWatch throughput + our own AIS wait/density.

{
  "type": "object",
  "properties": {
    "port": {
      "type": "string",
      "description": "Port UN/LOCODE, e.g. NLRTM"
    }
  },
  "required": [
    "port"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Live tropical cyclones (typhoons/hurricanes) currently active on ocean trade lanes — name, basin, category, center position, max wind, pressure and movement, from CMA (NW-Pacific) + NHC (Atlantic/E-Pacific) + JTWC (Indian/Southern Hemisphere) + GDACS (global). Use this to see which storms are at sea right now.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Whether an origin→destination ocean lane currently passes through an active cyclone's forecast gale field (a "storm-exposed" sailing at risk of weather delay). Omit ports to list every exposed lane.

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin port UN/LOCODE, e.g. CNSHA"
    },
    "destination": {
      "type": "string",
      "description": "Destination port UN/LOCODE, e.g. USLAX"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}