Technical guide

Global Sailing Schedules API

26 February 2023

Contents
Global Sailing Schedules API .............................................................................................................. 1
Document Purpose ................................................................................................................................. 2
Introduction ............................................................................................................................................... 2
Working with the GSS API.................................................................................................................... 2
Accessing Swagger UI ................................................................................................................................................2
Authentication ...................................................................................................................................................................3
Global Sailing Schedule Routes Request .......................................................................................................3
Global Sailing Schedule Routes Response ...................................................................................................5
API Call Limits .......................................................................................................................................... 9
Error Responses (v2) ............................................................................................................................. 9
Sample error response................................................................................................................................................9
Error Catalog ...................................................................................................................................................................10
Error Responses (v1) ............................................................................................................................ 12
Sample error response.............................................................................................................................................. 12
Error Catalog ................................................................................................................................................................... 12

Global Sailing Schedules API Technical Guide | 1

© 2022 WiseTech Global 28 February 2023
Document Purpose
The purpose of this document is to provide instructions for developers to be able to integrate
with the Global Sailing Schedules (GSS) API version 1 & 2.

Introduction
All CargoWise Global Sailing Schedules are now accessible via Web API. The service allows 3rd
party systems to connect, query and retrieve global sailing schedules (including routes, legs and
relevant details) in JSON format.

Working with the GSS API

API v2 should be used as v1 is no longer maintained

API v2 can be accessed via https://gss.wisegrid.net/api/v2/routes/search

API v2 the error responses adopt the Problem Details model defined by RFC7807:
https://datatracker.ietf.org/doc/html/rfc7807

Accessing Swagger UI
Swagger UI is available to test API filter parameters, requests and responses.

Swagger UI can be accessed via https://gss.wisegrid.net/index.html

Global Sailing Schedules API Technical Guide | 2

© 2022 WiseTech Global 28 February 2023
Authentication
The API uses Basic Authentication. A dedicated set of credentials must be issued to access GSS
API.

Note that API Usernames always consist of 9 characters

Raise CR9 eRequest to request a free trial access

Global Sailing Schedule Routes Request

Following are available filter query parameters:

Parameter Data Type Description Sample Value

carrierCode String Carrier SCAC MSCU

imoNumber String Vessel IMO Number 9204972

Where the IMO number is valid but
does not return any result, the search
will instead use the vessel name. If
neither the IMO nor the Vessel name
can be matched, the search will return
an empty array.

vesselName String Vessel Full Name SPIRIT OF MANILA

voyageNumber String Voyage Number HK939R

loadPort String Port of Loading UNLOCO SGSIN

dischargePort String Port of Discharge UNLOCO AUSYD

Global Sailing Schedules API Technical Guide | 3

© 2022 WiseTech Global 28 February 2023
 etdFrom Date Earliest Local Date of Departure in 2020-01-16
format YYYY-MM-DD

etdTo Date Latest Local Date of Departure in 2020-01-16

format YYYY-MM-DD

etaFrom Date Earliest Local Date of Arrival in format 2020-01-16

YYYY-MM-DD

Note that when this filter isn’t specified,

it will default to today’s date, unless
vesselName or voyageNumber is
specified. In which case, the etaFrom is
ignored.

etaTo Date Latest Local Date of Arrival in format 2020-01-16

YYYY-MM-DD

transitTime Integer Maximum transit time in days 20

legsCount Integer Maximum number of legs 2

includeRelatedPorts Boolean Include nearest related ports False (Default)

sameCarrierRoutes Boolean All legs via same carrier False (Default)

Filter requires at least the following details: Origin, Destination and then either
Departure or Arrival date. Alternatively, a Vessel Name or a Vessel’s IMO Number.

Example cURL request:

curl
"https://gss.wisegrid.net/api/v1/routes/search?carrierCode=MAEU&loadPort=AUSYD&dischargePort=USCHI&etd
From=2020-01-25&etdTo=2020-02-25" --header 'Authorization: Basic <your API credentials>'

Global Sailing Schedules API Technical Guide | 4

© 2022 WiseTech Global 28 February 2023
Global Sailing Schedule Routes Response
Following is a sample JSON response containing multiple legs:

[
{
"Carrier": {
"Code": "MAEU",
"Name": "Maersk Line"
},
"Legs": [
{
"Voyage": {
"Code": "009N",
"Operator": {
"Code": "MAEU",
"Name": "Maersk Line"
},
"TradeLane": {
"Code": "OC1",
"Name": "OC1"
},
"Vessel": {
"ImoNumber": "9391660",
"CallSign": null,
"VesselName": "SPIRIT OF HAMBURG"
}
},
"LoadPort": {
"Unloco": "DEHAM",
"Name": "Hamburg"
},
"Etd": "2020-02-26T14:00:00",
"DischargePort": {
"Unloco": "PAMIT",
"Name": "Manzanillo"
},
"Eta": "2020-03-30T19:00:00",
"LegType": "SEA"
"DepartureReference": "BER0121"
"DepartureReferenceProvider": "DAK"
},
{
"Voyage": {
"Code": "015N",
"Operator": {
"Code": "MAEU",
"Name": "Maersk Line"

Global Sailing Schedules API Technical Guide | 5

© 2022 WiseTech Global 28 February 2023
 },
"TradeLane": {
"Code": "SAE (SOUTH ATLANTIC)",
"Name": "SAE (SOUTH ATLANTIC)"
},
"Vessel": {
"ImoNumber": "9242649",
"CallSign": null,
"VesselName": "BOMAR VICTORY"
}
},
"LoadPort": {
"Unloco": "PAMIT",
"Name": "Manzanillo"
},
"Etd": "2020-04-06T06:00:00",
"DischargePort": {
"Unloco": "USORF",
"Name": "Norfolk"
},
"Eta": "2020-04-18T08:00:00",
"LegType": "SEA"
}
],
"TransitTime": 52,
"CtoCutOff": "2022-06-13T22:00:00",
"DocCutOff": "2022-06-10T00:00:00",
"VgmCutOff": "2022-06-13T00:00:00",
"CtoAvailable": null
}
]

• Number of records per search is limited to 500

• There is no support for pagination and sorting of the result set

• Vessel CallSign is currently not supported and will always return NULL

• Up to 3 months of upcoming schedules are available (carrier specific)

• ETA/ETD contains both date and time information however for some carriers
this can be date only with the time displayed as 00:00

• API provides details about upcoming sailings. While past schedules can be
accessed, these might not be accurate anymore

Global Sailing Schedules API Technical Guide | 6

© 2022 WiseTech Global 28 February 2023
 Element Data Type Description Sample Value

Carrier.Code String Carrier SCAC MAEU

Carrier.Name String Carrier’s Name Maersk Line

Legs.Voyage.Code String Voyage Number 015N

Legs.Voyage.Operator.Code String Operator SCAC MAEU

Legs.Voyage.Operator.Name String Operator’s Name Maersk Line

Legs.Voyage.TradeLane.Code String Trade Lane Code SAE

Legs.Voyage.TradeLane.Name String Trade Lane Name South Atlantic

Legs.Voyage.Vessel.ImoNumber String Vessel’s IMO number 9264348

Legs.Voyage.Vessel.CallSign Null Call Sign (currently Null

not supported)

Legs.Voyage.Vessel.VesselName String Vessel’s name Bomar Victory

Legs.LoadPort.Unloco String 5 characters long PAMIT

UNLOCO of the port
of loading

Legs.LoadPort.Name String Name of the port of Manzanillo

loading

Legs.Etd DateTime Estimated local time 2020-04-

of departure 06T06:00:00

Global Sailing Schedules API Technical Guide | 7

© 2022 WiseTech Global 28 February 2023
 Legs.DischargePort.Unloco String 5 characters long USORF
UNLOCO of the port
of discharge

Legs.DischargePort.Name String Name of the port of Norfolk

discharge

DepartureReference String Departure Reference BER0085

DepartureReferenceProvider String Hamburg DAK

Port Community
System Identifier –
DAK for DAKOSY (DE)

Legs.Eta DateTime Estimated local time 2020-04-

of arrival 18T08:00:00

Legs.LegType String Sea – sea leg SEA

Water – leg where
vessel’s IMO has not
been provided
Road – road leg
Rail – rail leg

TransitTime Integer Total number of days 52

from the time of
departure to the time
of arrival

CtoCutOff DateTime CTO Cargo Cut Off 2022-06-

time 13T22:00:00

DocCutOff DateTime Documentation Cut 2022-06-

Off time 13T22:00:00

VgmCutOff DateTime VGM Cut Off time 2022-06-

13T22:00:00

Global Sailing Schedules API Technical Guide | 8

© 2022 WiseTech Global 28 February 2023
 CtoAvailable DateTime CTO Cargo 2022-06-
Availability time 13T22:00:00

API Call Limits

Free Trail API calls are restricted to 20 calls per minute while paid service is restricted to 60 calls
per minute. Contact us if this limit needs to be increased.

Below is an example of the response header indicating limits and remaining number of calls:

{
"Content-Length": "230",
"Content-Type": "application/json; charset=utf-8",
"Date": "Fri, 24 Jan 2020 04:41:44 GMT",
"X-Rate-Limit-Limit": "20",
"X-Rate-Limit-Period": "1m",
"X-Rate-Limit-Remaining": "3",
"X-Rate-Limit-Reset": "2020-01-24T04:42:39Z"
}

Exceeding this limit would result in the following error with the number of seconds till the limit is
reset:

{
"Content-Length": "58",
"Content-Type": "application/json; charset=utf-8",
"Date": "Fri, 24 Jan 2020 04:44:41 GMT",
"Retry-After": "57"
}

Error Responses (v2)

Sample error response
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-b09459ece54bf4498f988cbd85dd4c35-817b5606d4d1c244-00",
"errors": {
"DischargePort": [
"Port of Discharge UNLOCO is invalid. It must be 5 characters long."
]
}
}

Global Sailing Schedules API Technical Guide | 9

© 2022 WiseTech Global 28 February 2023
Error Catalog

HTTP Filter Property Message

Status
Code

400 RouteFilter Filter doesn't meet the minimum parameter requirements.

Must contain Load Port, Discharge Port and one of the ETA
or ETD. Alternatively Voyage Number and either Vessel
Name or IMO Number.

400 ImoNumber Vessel IMO Number is Invalid.

400 LoadPort Port of Loading UNLOCO is invalid. Must be 5 characters

long.

400 LoadPort Port of Loading UNLOCO cannot be recognised.

400 EtdFrom ETD From is invalid. Must be in the format YYYY-MM-DD.

400 EtdTo ETD To is invalid. Must be in the format YYYY-MM-DD.

400 EtdTo ETA To must be greater than or equal to ETA From.

400 DischargePort Port of Discharge UNLOCO is invalid. Must be 5 characters

long.

400 DischargePort Port of Discharge UNLOCO cannot be recognised.

400 EtaFrom ETA From is invalid. Must be in the format YYYY-MM-DD.

400 EtaTo ETA To is invalid. Must be in the format YYYY-MM-DD.

400 EtaTo ETA To must be greater than or equal to ETA From.

Global Sailing Schedules API Technical Guide | 10

© 2022 WiseTech Global 28 February 2023
 400 CarrierCode Carrier SCAC is invalid. Must be 4 characters long.

400 TransitTime Transit Time is Invalid. Must be a number greater than or

equal to zero.

400 LegsCount Number of Legs is Invalid. Must be a number greater than

zero.

400 IncludeRelatedPorts Related ports option is invalid. Must be a True or a False.

400 SameCarrierRoutes Same carrier routes option is invalid. Must be a True or a

False.

400 - More than 500 records returned.

400 CarrierCode Carrier SCAC is not supported.

401 - Unauthorized. Invalid credentials.

401 - Unauthorized. Invalid username or password.

401 - Unauthorized. Authorization header not found.

429 - API calls quota exceeded. Maximum 20 calls per Minute.

500 - Unexpected Server Error.

500 - Server is taking too long to respond. Try again later, use
different parameters or contact administrator if problems
persist.

Global Sailing Schedules API Technical Guide | 11

© 2022 WiseTech Global 28 February 2023
Error Responses (v1)
Apart from the standard HTTP Status Code the JSON formatted error response provides the
following details:

Key Data Type Description

Name
String Error message unique code

Message String Human readable error message response

DebugId String Unique error response identification for debugging purposes

Sample error response

{
"Name": "NoAuthorizationFound",
"Message": "Unauthorized. Authorization header not found.",
"DebugId": "f0bb7249-b73a-4c9e-867c-8600eaac3839"
}

Error Catalog

HTTP Name Message

Status
Code

400 EmptyFilter Filter is empty. Must contain Load Port, Discharge Port and
one of the ETA or ETD. Alternatively Voyage Number and
either Vessel Name or IMO Number.

400 InvalidFilter Filter doesn't meet the minimum parameter requirements.

Must contain Load Port, Discharge Port and one of the ETA

Global Sailing Schedules API Technical Guide | 12

© 2022 WiseTech Global 28 February 2023
 or ETD. Alternatively Voyage Number and either Vessel
Name or IMO Number.

400 InvalidImoNumber Vessel IMO Number is not 7 digits in length or the check
digit is incorrect.

400 InvalidPortOfLoading Port of Loading UNLOCO is invalid. Must be 5 characters

long.

400 PortOfLoadingNotRecognised Port of Loading UNLOCO cannot be recognised.

400 InvalidEtdFrom ETD From is invalid. Must be in the format YYYY-MM-DD.

400 InvalidEtdTo ETD To is invalid. Must be in the format YYYY-MM-DD.

400 InvalidEtdRange ETA To must be greater than or equal to ETA From.

400 InvalidPortOfDischarge Port of Discharge UNLOCO is invalid. Must be 5 characters

long.

400 PortOfDischargeNotRecognised Port of Discharge UNLOCO cannot be recognised.

400 InvalidEtaFrom ETA From is invalid. Must be in the format YYYY-MM-DD.

400 InvalidEtaTo ETA To is invalid. Must be in the format YYYY-MM-DD.

400 InvalidEtaRange ETA To must be greater than or equal to ETA From.

400 InvalidScac Carrier SCAC format is invalid. Must be 4 characters in

length.

400 InvalidTransitTime Transit Time is Invalid. Must be a number greater than or

equal to zero.

Global Sailing Schedules API Technical Guide | 13

© 2022 WiseTech Global 28 February 2023
 400 InvalidLegsCount Number of Legs is Invalid. Must be a number greater than
zero.

400 InvalidRelatedPorts Related ports option is invalid. Must be a True or a False.

400 InvalidSameCarrierRoutes Same carrier routes option is invalid. Must be a True or a

False.

400 MaxRecordsReached More than 500 records returned.

400 ScacNotSupported Carrier SCAC is not supported/not available in CargoWise.

401 MissingCredentials Unauthorized. Missing credentials.

401 InvalidCredentials Unauthorized. Invalid credentials.

401 InvalidLoginOrPassword Unauthorized. Invalid username or password.

401 AuthorizationRequired Unauthorized. Authorization header not found.

403 ForbiddenRequest You are trying to access restricted or invalid resource.

429 CallQuotaExceeded API calls quota exceeded. Maximum 20 calls per Minute.

500 InternalServerError Unexpected Server Error.

500 ServerTimeout Server is taking too long to respond. Try again later, use
different parameters or contact administrator if problems
persist.

Global Sailing Schedules API Technical Guide | 14

© 2022 WiseTech Global 28 February 2023