Home

Introduction

Ship Schedules API

version 1

Ship Schedules API allows you to get instant sailing itineraries for vessels of multiple shipping lines together with full associated details.

OpenAPI Specification

Start designing your API in minutes. The OpenAPI specification file enables you to learn and interact with API elements, including all available endpoints, input and output representations.

OpenAPI Spec

General information

Ship Schedules API is organized around REST.
Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

API endpoint#

1https://sirius.searates.com

All endpoints are only accessible via HTTPS and are located at sirius.searates.com

Schedules by Points

get/schedule

Get schedules for particular direction using locodes for ports, and scac for shipping line filter.

Notes:

  • Any field of transShipments array could be empty or has the value TBN, as fields cutOff and transitTime except type. This means that sealine doesn’t provide this kind of data at the moment.
  • Field named cutOff represents CY date. If sealine doesn’t provide this date it will be set two days before first departure date of transShipments array
  • In case of FEEDER or LAND type transportation fields named: vesselName, vesselCode, voyage, service all will be empty. Some of sealines do not provide schedules for past dates, only from today.
  • The sealines: ONE, COSCO, OOCL, MAERSK, SAFMARINE, SEALAND, YANG MING, HAPAG-LLOYD may require service mode parameter CY or SD for departure port and arrival port to get more schedules.
Headers

Content-Typeapplication/json

Query Parameters
  • sealineREQUIREDstring

    Standard Carrier Alpha Code (SCAC)

    Example:ARKU

    Match pattern:^[A-Z0-9]{4}$

  • portcodeREQUIREDstring

    LOCODE - the locode of departure port

    Example:UAODS

    Match pattern:^[A-Z0-9]{5}$

  • portdestinationcodeREQUIREDstring

    LOCODE - the locode of arrival port

    Example:TRGEM

    Match pattern:^[A-Z0-9]{5}$

  • fromdateREQUIREDstring

    Start from date - specify the date in format dd-mm-yyyy or today

    Examples:today09-10-2020

    Match pattern:^(\d{2}-\d{2}-\d{4})|today$

  • weeksaheadREQUIREDinteger

    Weeks ahead - weeks to display

    >= 1<= 5

    Example:2

  • directionREQUIREDstring

    Sorting by earliest departure or latest arrival

    Allowed values:DA

    Example:D

  • service_mode_fromOptionalstring

    Origin service mode

    Allowed values:CYSD

    Default:CY

  • service_mode_toOptionalstring

    Destination service mode

    Allowed values:CYSD

    Default:CY

  • api_keyREQUIREDstring

    API Key - to get api key, please contact us

    Example:DEMO_KEY

Response example
Successful operation *Note: All errors will be returned with HTTP Status code 200. ALl errors have the same JSON structure as _"Internal server error"_ response example.
1{
2  "response": {
3    "status": "SUCCESS",
4    "routes": [
5      {
6        "transShipments": [
7          {
8            "type": 1,
9            "vesselName": "ODYSSEUS",
10            "vesselCode": null,
11            "voyage": "WBS41W20",
12            "departure": {
13              "date": 1680393600,
14              "portName": "AMBARLI / MARPORT",
15              "portUnloCode": "TRMRP",
16              "terminal": "MARPORT TERMINAL"
17            },
18            "arrival": {
19              "date": 1680739200,
20              "portName": "GEMLIK",
21              "portUnloCode": "TRGEM",
22              "terminal": "BORUSAN"
23            },
24            "service": "WESTMED BLACK SEA SERVICE"
25          }
26        ],
27        "cutOff": 1680220800,
28        "transitTime": 4
29      }
30    ]
31  }
32}
1{
2  "response": {
3    "status": "NO_RESPONSE_FROM_CARRIER",
4    "routes": []
5  }
6}
1{
2  "response": {
3    "status": "UNEXPECTED_ERROR",
4    "routes": []
5  }
6}

Schedules by Vessel

get/schedule/vessel

Get schedules for particular vessel using it's IMO number.

Notes:

  • Schedules are only displayed within 3 months from date of request.
Headers

Content-Typeapplication/json

Query Parameters
  • imoREQUIREDinteger

    IMO - unique identifier of the vessel

    Example:9356165

  • api_keyREQUIREDstring

    API Key - to get api key, please contact us

    Example:DEMO_KEY

Response example
Successful operation *Note: All errors will be returned with HTTP Status code 200. All errors have the same JSON structure as _"Vessel's IMO is not valid"_ response example.
1{
2  "status": "SUCCESS",
3  "message": "SCHEDULES_FOUND",
4  "data": {
5    "vessel": {
6      "name": "CMA CGM BUTTERFLY",
7      "imo": "9365790",
8      "call_sign": "DFPI2",
9      "mmsi": "218843000",
10      "flag": "DE",
11      "year_built": 2008,
12      "capacity": 9661
13    },
14    "locations": [
15      {
16        "id": 1,
17        "name": "MUNDRA",
18        "state": "Gujarat",
19        "country": "India",
20        "country_code": "IN",
21        "locode": "INMUN",
22        "latitude": 22.75602,
23        "longitude": 69.63645,
24        "timezone": null
25      }
26    ],
27    "schedules": [
28      {
29        "carrier_name": "OOCL",
30        "carrier_code": "OOLU",
31        "service_name": "IEX",
32        "service_code": "IEX",
33        "voyages": [
34          "3109"
35        ],
36        "ports": [
37          {
38            "arrival_voyage": "3109",
39            "arrival_local_voyage": null,
40            "departure_voyage": "3109",
41            "departure_local_voyage": null,
42            "estimated_arrival": null,
43            "estimated_berth": null,
44            "estimated_departure": null,
45            "actual_arrival": "2023-03-08 06:40",
46            "actual_berth": null,
47            "actual_departure": "2023-03-09 23:51",
48            "location": 1,
49            "terminal": null,
50            "deadlines": []
51          }
52        ]
53      }
54    ]
55  }
56}
1{
2  "status": "NOT_FOUND",
3  "message": "NO_SCHEDULES_FOR_VESSEL",
4  "data": null
5}
1{
2  "status": "ERROR",
3  "message": "WRONG_IMO",
4  "data": null
5}

Available carriers

get/schedule/available-carriers

Get list of available carriers for schedules.

Headers

Content-Typeapplication/json

Query Parameters
  • byREQUIREDstring

    Filter available carriers

    Allowed values:pointsvessel

Response example
Successful operation
SeaRates 2024—Find a toolRequest an IT quoteContact us