Introduction

The Marine Visibility API allows subscribed companies to retrieve terminal data about cargo handling on Bulk terminals.

For more commercial information and an overview of data providers, please visit the NxtPort International marketplace.

Prerequisites

Your company is subscribed to the Marine Visibility API and you have a valid API key
You have a Client ID & Secret
You are able to retrieve an authentication token
You have a way to retrieve and store Marine Call IDs, the unique identifiers that will be used to retrieve terminal information. For more information, please contact the terminal you are retrieving data from or create a support ticket on the NxtPort zendesk support pages.

Marine Visibility API description

Base URL

The Marine Visibilty API is hosted on both our Staging/Test and our Production environment.

Staging: https://api-stg.nxtport-international.com/international/marinecalls
Production: https://api.nxtport-international.com/international/marinecalls

Github

A swagger file can be found on the NxtPort International Github pages.

https://nxtport-international.github.io/?api=marine-visibility

Supported terminal

For an overview of supported terminals that provide data for this API call you can follow this link: Marine Visibility data providers.

GET MarineVisibilities

URL:

{{BASEURL}}/MarineVisibilities/{marineCallId}

Usage

Retrieve track & trace & basic cargo information based on a Marine Call ID. The result of the API call will provide a json file that is based on the ISO 28005-2:2011 (E) standard, used for Electronic Port Clearance. A few additions were made to better support the terminal events.

Header parameters

Authorization: Contains the value Bearer {{your-jwt-token}}. To retrieve the token, please refer to the prerequisites.
Ocp-Apim-Subscription-Key: your active API key that can be found in the NxtPort International portal.

Query parameters

marineCallId: the Unique identifier of the Marine Call you are retrieving information from. This identifier needs to be obtained from the terminal.
Please note NxtPort currently does not support functionality to retrieve all MarineCall ID's for a terminal.

Response

 {
  "marineCallId": "string",
  "terminalArrival": [
    {
      "arrivalTime": [
        {
          "dateTime": "2024-04-26T15:00:31.255Z",
          "timeType": "NORTendered"
        }
      ],
      "location": {
        "type": "string",
        "name": "string",
        "code": "string",
        "UNLoCode": "string"
      }
    }
  ],
  "terminalDeparture": [
    {
      "departureTime": [
        {
          "dateTime": "2024-04-26T15:00:31.255Z",
          "timeType": "NORTendered"
        }
      ],
      "location": {
        "type": "string",
        "name": "string",
        "code": "string",
        "UNLoCode": "string"
      }
    }
  ],
  "shipId": {
    "callSign": "string",
    "shipName": "string",
    "MMSINumber": "string",
    "IMONumber": "string",
    "shipType": "string"
  },
  "voyageNumber": "string",
  "agent": {
    "company": "string",
    "companyId": "string"
  },
  "navigationalStatus": "string",
  "trackAndTrace": [
    {
      "arrivalTime": [
        {
          "dateTime": "2024-04-26T15:00:31.255Z",
          "timeType": "NORTendered"
        }
      ],
      "departureTime": [
        {
          "dateTime": "2024-04-26T15:00:31.255Z",
          "timeType": "NORTendered"
        }
      ],
      "location": {
        "type": "string",
        "name": "string",
        "code": "string",
        "UNLoCode": "string"
      }
    }
  ],
  "cargoData": {
    "consignment": [
      {
        "consignmentNumber": "string",
        "cargoItem": [
          {
            "itemNumber": "string",
            "goodsType": {
              "description": "string",
              "HSCode": "string"
            },
            "quantities": {
              "ordered": "string",
              "orderedUom": "string",
              "established": "string",
              "establishedUom": "string"
            }
          }
        ]
      }
    ]
  },
  "company": {
    "organisation": {
      "name": "string",
      "taxIdentifier": "string",
      "registrationCountryCode": "string"
    }
  }
}

Fields

marineCallId

String

ID of the Marine Call. Will always be the ID that has been provided as input parameter

terminalArrival

Array

Contains a list of Arrival related times and the terminal location information

-> arrivalTime

Object

List of different Arrival times. Each arrival time consists of

dateTime field
timeType

--> dateTime

DateTime

date format UTC (zulu time)

The dates are returned using the local terminal time

--> timeType

String

Depending on the terminal, different timetypes can be returned. Currently, the following types are available.

NORTendered
NORAccepted
plannedArrivalAtBerth
actualArrivalAtBerth
plannedFirstHoseConnected
actualFirstHoseConnected

Please contact your terminal for more information on which types are supported.

-> location

Object

Data object containing the location information of the terminal

--> type

String

Will contain "Terminal" for this API

--> name

String

Name of the terminal as it is named by the data provider

--> code

String

Code of terminal, as it is given by the data provider. This code is not linked to a centralised location database.

--> UNLoCode

String

UNLocode of the terminal. For more information on UNLocodes, please visit the NxtPort International marketplace.

terminalDeparture

Array

Contains a list of Departure related times and the terminal location information

-> departureTime

Object

List of different Departure times. Each arrival time consists of

dateTime field
timeType

--> dateTime

DateTime

date format UTC (zulu time)

The dates are returned using the local terminal time

--> timeType

String

Depending on the terminal, different timetypes can be returned. Currently, the following types are available.

plannedLastHoseDisconnected
actualLastHoseDisconnected
plannedDepartureFromLastBerth
actualDepartureFromLastBerth

Please contact your terminal for more information on which types are supported.

-> location

Object

Data object containing the location information of the terminal

--> type

String

Will contain "Terminal" for this API

--> name

String

Name of the terminal as it is named by the data provider

--> code

String

Code of terminal, as it is given by the data provider. This code is not linked to a centralised location database.

--> UNLoCode

String

UNLocode of the terminal. For more information on UNLocodes, please visit the NxtPort International marketplace.

shipId

Object

Object containing the information about the vessel

-> callSign

String

Marine Call visit ID, unique identifier of the call to the terminal

-> shipName

String

Name of the vessel

-> MMINumber

String

MMI number of the vessel

-> IMONumber

String

IMO number of the vessel

-> shipType

String

Will contain the value "Ship"

voyageNumber

String

operator-assigned reference code for one particular voyage

agent

Object

Object containing basic information about the agent representing the vessel

-> company

String

Name of the company, as provided by the data provider

-> companyId

String

Code of the company, as provided by the data provider

navigationalStatus

String

Coded representation of the ship's navigational status. Supported values:

Registered
Scheduled
NOR Tendered
Called In
Arrived
Connect
Disconnect
Departed

trackAndTrace

Array

Object containing all relevant track & trace events at the terminal and or jetty.

-> arrivalTime

Object

List of different Arrival times. Each arrival time consists of

dateTime field
timeType

--> dateTime

dateTime

date format UTC (zulu time)

The dates are returned using the local terminal time

--> timeType

String

Depending on the terminal, different timetypes can be returned. Currently, the following types are available.

NORTendered
NORAccepted
plannedArrivalAtBerth
actualArrivalAtBerth
plannedFirstHoseConnected
actualFirstHoseConnected

Please contact your terminal for more information on which types are supported.

-> departureTime

Object

List of different Departure times. Each arrival time consists of

dateTime field
timeType

--> dateTime

dateTime

date format UTC (zulu time)

The dates are returned using the local terminal time

--> timeType

String

Depending on the terminal, different timetypes can be returned. Currently, the following types are available.

plannedLastHoseDisconnected
actualLastHoseDisconnected
plannedDepartureFromLastBerth
actualDepartureFromLastBerth

Please contact your terminal for more information on which types are supported.

-> location

Object

Object containing the location information for the terminal or Jetty

--> type

String

Two values are supported:

Terminal
Jetty

--> name

String

Name of terminal or jetty, as it is given by the data provider.

--> code

String

Code of terminal or jetty, as it is given by the data provider. This code is not linked to a centralised location database.

cargoData

Object

Object containing the cargo that is being transferred at the terminal

-> consignment

Array

Array containing the consignment information. If multiple cargo items are being transferred, the array will contain multiple items.

-> consignmentNumber

String

Unique identifier of the consignment. Can be empty if not provided by the dataprovider

-> cargoItem

Array

Sub object containing the specific information about the cargo items

--> itemNumber

String

If provided by the dataprovider, will contain reference to this cargo item's location in the document

--> goodsType

Object

This subobject contains a reference to the actual goods type for the cargo item. The coding is based on the World Customs Organization coding scheme

---> description

String

Description of the goods, as provided by the data provider

---> HSCode

String

If provided by the data provider, contain the HS WCO compliant code

--> quantities

Object

Sub object containing the quantities of the transferred goods

---> ordered

String

The ordered quantity, as given by the data provider

---> orderedUom

String

The UOM that is used by the data provider to represent the Ordered quantity. Uses the UN/Cefact-REC20 standard (click here for more information)

---> established

String

The established quantity, as given by the data provider

---> establishedUom

String

The UOM that is used by the data provider to represent the Established quantity. Uses the UN/Cefact-REC20 standard (click here for more information)

company

Object

Data object containing information about the Data provider (ie, the terminal)

-> organisation

Object

Sub object

--> name

String

Name of the company as registered in the NxtPort International platform

--> taxIdentifier

String

Tax identifier of the company as registered in the NxtPort International platform

--> registrationCountryCode

String

ISO country code of the company as registered in the NxtPort International platform

POST MarineVisibilities

URL:

{{BASEURL}}/MarineVisibilities

Usage

Create a new entry to inform a terminal operator about a marine call. The body of the API is a json file that is based on the ISO 28005-2:2011 (E) standard, used for Electronic Port Clearance. A few additions were made to better support the terminal events.

Header parameters

Authorization: Contains the value Bearer {{your-jwt-token}}. To retrieve the token, please refer to the prerequisites.
Ocp-Apim-Subscription-Key: your active API key that can be found in the NxtPort International portal.

Body

{
  "terminalArrival": [
    {
      "arrivalTime": [
        {
          "dateTime": "2024-05-02T09:09:11.359Z",
          "timeType": "PlannedArrivalAtAnchorage"
        }
      ],
      "location": {
        "type": "string",
        "code": "string",
        "UNLoCode": "string"
      }
    }
  ],
  "terminalDeparture": [
    {
      "departureTime": [
        {
          "dateTime": "2024-05-02T09:09:11.359Z",
          "timeType": "PlannedArrivalAtAnchorage"
        }
      ],
      "location": {
        "type": "string",
        "name": "string",
        "code": "string",
        "UNLoCode": "string"
      }
    }
  ],
  "shipId": {
    "shipName": "string",
    "MMSINumber": "string",
    "IMONumber": "string",
    "shipType": "string"
  },
  "voyageNumber": "string",
  "agent": {
    "company": "string",
    "companyId": "string"
  },
  "company": {
    "organisation": {
      "name": "string",
      "taxIdentifier": "string",
      "registrationCountryCode": "string"
    }
  },
  "generalRemark": "string"
}

Fields

terminalArrival	Array	Contains a list of Arrival related times and the terminal location information
-> arrivalTime	Object	List of different Arrival times. Each arrival time consists of dateTime field timeType
--> dateTime	DateTime	date format UTC (zulu time) The dates are returned using the local terminal time
--> timeType	String	Depending on the terminal, different timetypes can be provided. Currently, the following types are supported. ExpectedArrivalDateTimeAtAnchorage (mandatory) laycanStart (optional)
-> location	Object	Data object containing the location information of the terminal
--> type	String	Enter "Terminal" for this API
--> name	String	Name of the terminal as it is known by the terminal operator. Please contact the terminal to clearify which value needs to be entered here.
--> code	String	Code of terminal, as it is requested by the terminal. Please contact the terminal to clearify which value needs to be entered here.
--> UNLocode	String	UNLocode of the terminal. For more information on UNLocodes, please visit the NxtPort International marketplace.
terminalDeparture	Array	Contains a list of Departure related times and the terminal location information
-> departureTime	Object	List of different Departure times. Each arrival time consists of dateTime field timeType
--> dateTime	DateTime	date format UTC (zulu time) The dates are returned using the local terminal time
--> timeType	String	Depending on the terminal, different timetypes can be returned. Currently, the following types are supported. laycanEnd (optional) Please contact your terminal for more information on which types are supported.
-> location	Object	Data object containing the location information of the terminal
--> type	String	Enter "Terminal" for this API
--> name	String	Name of the terminal as it is named by the data provider
--> code	String	Name of the terminal as it is known by the terminal operator. Please contact the terminal to clearify which value needs to be entered here.
--> UNLoCode	String	Code of terminal, as it is requested by the terminal. Please contact the terminal to clearify which value needs to be entered here.
shipId	Object	Object containing the information about the vessel
-> shipName	String	Name of the vessel
-> MMINumber	String	MMI number of the vessel
-> IMONumber	String	IMO number of the vessel
-> shipType	String	Enter the value "Ship"
voyageNumber	String	Voyage number is the reference given by the agent for this specific call of the vessel
agent	Object	Object containing basic information about the agent representing the vessel
-> company	String	Name of the agent company
-> companyId	String	Code of the agent company
company	Object	Data object containing information about the terminal operator. This data needs to be identical to the information as used in the NxtPort International platform
-> organisation	Object	Sub object
--> name	String	Name of the Terminal as registered in the NxtPort International platform
--> taxIdentifier	String	Tax identifier of the Terminal as registered in the NxtPort International platform
--> registrationCountryCode	String	ISO country code of the Terminal operator as registered in the NxtPort International platform (optional)
generalRemark	String	Free text field to leave instructions related to this call

We SUPPORT the power of Together

Search

Marine visibility API

Introduction

Prerequisites

Marine Visibility API description

Base URL

Github

Supported terminal

GET MarineVisibilities

POST MarineVisibilities

We SUPPORT the power of Together

Search

Introduction

Prerequisites

Marine Visibility API description

Base URL

Github

Supported terminal

GET MarineVisibilities

POST MarineVisibilities

Related articles