GETNo key

Vessel-first cards

GETapi.schedulesmcp.com/public/schedules/cards

The same sailings shaped as vessel-first cards, the way a desk scans them. One card per physical vessel and departure, with the slot partners selling it grouped inside. A card carries more keys than the example below, including routing legs, CO2 and the per-carrier cut-off detail.

Query parameters

originstringrequired

Origin UN/LOCODE.

destinationstringrequired

Destination UN/LOCODE.

fromstring

Start from date - specify the date in format yyyy-mm-dd. Must be current date or future date

weeksinteger

How many weeks forward from the start date. One of 4, 6, 8, 10. Defaults to 4

carrierstring

Filter by carrier. One or more SCAC codes, comma-separated. Defaults to all carriers

transshipmentboolean

"true" - sailings with transshipment; "false" - direct schedules only; omit it for all sailings

Response schema

72 fields

Derived from the example response, nested as the JSON is.

okboolean

Whether the request succeeded.

dataobject

The payload. Everything an endpoint returns sits under this key.

originstring

Origin code (airport IATA or UN/LOCODE).

destinationstring

Destination code (airport IATA or UN/LOCODE).

fromstring

tostring

weeksnumber

min_obsnumber

Minimum observations required to rank a carrier.

carriersobject[]

Carriers, ranked.

truncatedboolean

True when the book was larger than one report can carry and the list was cut. An untruncated empty list means nothing was at risk; a truncated one does not.

countnumber

How many cards the lane returned.

lane_capacityobject

Weekly TEU offered on the lane, summed over distinct vessels.

total_teunumber

Total TEU across the sailings returned. Null when no vessel carried a capacity.

sailingsnumber

Matching sailings.

teu_per_weeknumber

TEU offered per week on this lane. Null when the window is too short to divide.

span_weeksnumber

sailings_without_capacitynumber

estimatedboolean

True when any card in the total used an estimated capacity.

suspected_blanksobject[]

Gaps of more than about eleven days on a weekly service, which usually mean a skipped sailing. Suspected, not confirmed.

cardsobject[]

Vessel-first sailing cards. One per physical vessel and departure, with every carrier selling a slot on it grouped inside.

cards[]object

vessel_namestring

Name of the carrying vessel, or null when the carrier named none.

vessel_imostring

IMO number of the carrying vessel, or null when unknown.

voyage_numberstring

Carrier voyage number.

service_namestring

Carrier service or loop name.

published_departurestring

The departure the carrier published (ISO 8601). Null when it published none.

published_arrivalstring

The arrival the carrier published (ISO 8601). Null when it published none.

transit_daysnumber

Port-to-port transit in days.

leg_countnumber

How many legs the routing has. One means a direct sailing.

is_transshipmentboolean

True when the box changes ship, false when it does not, null when we cannot say.

transship_viaany | null

The hub UN/LOCODEs. Null on a direct sailing, and also when the carrier did not name its hubs.

capacity_teunumber

Vessel capacity in TEU. Null when we hold neither a real nor an estimated figure.

capacity_estimatedboolean

True when the TEU figure is derived from deadweight rather than published. Read it before quoting the number.

confidenceobject

On a card, whether the slot partners agree with each other. On a prediction, how much to trust the shifted arrival.

sourcesnumber

How many carriers published this vessel and departure.

etd_spread_hoursnumber

Hours between the earliest and latest departure the partners published. Null on a single source.

eta_spread_hoursnumber

Hours between the earliest and latest arrival the partners published. Null on a single source.

levelstring

On a port, the congestion level. On a sailing card confidence block, high when at least two carriers agree within a day, then medium, low, or single_source when only one published it.

predictionobject

The published arrival shifted by the carrier observed average delay on this lane. Null until we hold a confident sample.

predicted_arrivalstring

When we expect it to actually arrive (ISO 8601), as against the published arrival.

delay_hoursnumber

The average delay applied, in hours.

basis_obsnumber

How many observed sailings the shift rests on.

band_hoursnumber

Uncertainty band around the prediction, in hours, from the carrier schedule churn.

confidencestring

On a card, whether the slot partners agree with each other. On a prediction, how much to trust the shifted arrival.

partner_countnumber

How many carriers sell a slot on this sailing.

partnersobject[]

The carriers selling this vessel, best reliability first. Each carries its own cut-offs, because a forwarder books a slot rather than a vessel.

partners[]object

carrier_codestring

Carrier SCAC.

carrier_namestring

Carrier name.

service_namestring

Carrier service or loop name.

voyage_numberstring

Carrier voyage number.

published_departurestring

The departure the carrier published (ISO 8601). Null when it published none.

published_arrivalstring

The arrival the carrier published (ISO 8601). Null when it published none.

reliability_pctnumber

Share of this carrier sailings that arrived on time on this lane.

reliability_obsnumber

How many sailings that percentage rests on.

reliability_provisionalboolean

True when the sample is below min_obs, so the percentage is indicative rather than a ranking.

cutoffsobject

Every deadline this carrier published for this sailing, by its own name. Null, never an empty array, when it published none.

cystring

Container yard deadline (ISO 8601), or null when the carrier published none.

docstring

Documentation deadline (ISO 8601), or null when the carrier published none.

vgmstring

Verified gross mass deadline (ISO 8601), or null when the carrier published none.

cutoff_statusstring

Why a cut-off is missing. published: this carrier published them. not_published: it publishes none here. not_held: another line sold the slot, so these deadlines were never ours.

vesselobject

Vessel currently carrying the container, or null when we hold neither a name nor an IMO. Its lat and lng are always null here; the keyed endpoints carry the live position under vessel_position.

imostring

IMO number of the vessel.

teunumber

Vessel capacity in TEU.

teu_estimatedboolean

True when the TEU figure is derived rather than published.

length_mnumber

Overall length in metres.

year_builtnumber

Year the hull was delivered.

flagstring

Flag state of the vessel, as a two-letter code. Null when we hold none.

latnumber

Latitude.

lngnumber

Longitude.

speed_knotsnumber

Speed over ground, in knots.

nav_statusstring

Navigational status as reported by AIS, for example "Under way using engine" or "Moored". We drop a moored or anchored claim that the position contradicts.

position_updated_atstring

When we last wrote the position row.

last_moveany | null

The most recent schedule change we observed for this sailing. Null when it has not moved.

Errors

Every refusal is { "ok": false, "error": { "code", "message", "parameter"? } }. The code is stable and safe to branch on, the message is a sentence for a person, and parameter names the input at fault where one input is at fault. A filter that matches nothing is not an error: it answers 200 with an empty list, which is a true answer about the filter rather than about the lane.

MISSING_PARAMETER400

origin or destination was not given. `parameter` names the missing half, and neither when both are absent.

INVALID_DATE_FORMAT400

from is not a calendar date as YYYY-MM-DD, is not a real date (2026-02-30), carries a time or an offset, is more than a century ahead, or was given twice. `parameter` is from.

DATE_IN_PAST400

from is before today UTC. Schedules are forward-looking, so a past window is refused rather than quietly returning nothing. `parameter` is from.

INVALID_WEEKS400

weeks is not one of 4, 6, 8, 10, or was given twice. `parameter` is weeks.

INVALID_SCAC400

A value in carrier is not four characters of capitals and digits. The message lists the offending values, clipped. `parameter` is carrier.

INVALID_TRANSSHIPMENT400

transshipment is something other than true or false. Deliberately strict: 1, yes and TRUE are refused rather than half-accepted. `parameter` is transshipment.

DB_ERROR500

The read failed on our side. Nothing was filtered out, so a retry is safe.

Try it No key

origin * query destination * query from query weeks query carrier query transshipment query

curl 'https://api.schedulesmcp.com/public/schedules/cards?origin=CNSHA&destination=NLRTM&from=2026-10-08&weeks=4&carrier=MAEU%2CHLCU&transshipment=true'

const res = await fetch("https://api.schedulesmcp.com/public/schedules/cards?origin=CNSHA&destination=NLRTM&from=2026-10-08&weeks=4&carrier=MAEU%2CHLCU&transshipment=true");
const data = await res.json();

import requests

res = requests.get("https://api.schedulesmcp.com/public/schedules/cards?origin=CNSHA&destination=NLRTM&from=2026-10-08&weeks=4&carrier=MAEU%2CHLCU&transshipment=true")
data = res.json()

Sample response example

{
  "ok": true,
  "data": {
    "origin": "CNSHA",
    "destination": "NLRTM",
    "from": "2026-10-08T00:00:00.000Z",
    "to": "2026-11-05T00:00:00.000Z",
    "weeks": 4,
    "min_obs": 5,
    "carriers": [],
    "truncated": false,
    "count": 1,
    "lane_capacity": {
      "total_teu": 23656,
      "sailings": 1,
      "teu_per_week": 23656,
      "span_weeks": 1,
      "sailings_without_capacity": 0,
      "estimated": false
    },
    "suspected_blanks": [],
    "cards": [
      {
        "vessel_name": "EVER GIVEN",
        "vessel_imo": "9811000",
        "voyage_number": "0FBB3E1MA",
        "service_name": "AEU2",
        "published_departure": "2026-08-14T18:00:00Z",
        "published_arrival": "2026-09-12T06:00:00Z",
        "transit_days": 29,
        "leg_count": 1,
        "is_transshipment": false,
        "transship_via": null,
        "capacity_teu": 23656,
        "capacity_estimated": false,
        "confidence": {
          "sources": 2,
          "etd_spread_hours": 6,
          "eta_spread_hours": 12,
          "level": "high"
        },
        "prediction": {
          "predicted_arrival": "2026-09-14T12:00:00Z",
          "delay_hours": 54,
          "basis_obs": 18,
          "band_hours": 24,
          "confidence": "medium"
        },
        "partner_count": 2,
        "partners": [
          {
            "carrier_code": "EGLV",
            "carrier_name": "Evergreen",
            "service_name": "AEU2",
            "voyage_number": "0FBB3E1MA",
            "published_departure": "2026-08-14T18:00:00Z",
            "published_arrival": "2026-09-12T06:00:00Z",
            "reliability_pct": 71.4,
            "reliability_obs": 18,
            "reliability_provisional": false,
            "cutoffs": {
              "cy": "2026-08-12T12:00:00Z",
              "doc": "2026-08-11T16:00:00Z",
              "vgm": "2026-08-12T09:00:00Z"
            },
            "cutoff_status": "published"
          }
        ],
        "vessel": {
          "imo": "9811000",
          "teu": 23656,
          "teu_estimated": false,
          "length_m": 399.9,
          "year_built": 2018,
          "flag": "PA",
          "lat": 29.97,
          "lng": 32.57,
          "speed_knots": 0,
          "nav_status": "Moored",
          "position_updated_at": "2026-08-07T05:30:00Z"
        },
        "last_move": null
      }
    ]
  }
}

This preview uses documented example data and makes no live request. Get a key to run live.