Oceanbolt Api
API docs by Redocly

Oceanbolt Data API (3.0.0)

Download OpenAPI specification:Download

API Support: support@oceanbolt.com URL: https://openapi.oceanbolt.com

This API provides access to the data available in the Oceanbolt Data Platform. The API is accessible on the following base url: https://api.oceanbolt.com/v3.

Introduction

This API is documented in OpenAPI format. The api allows for programmatic access to the different data resources that are also accessible in the Oceanbolt Data Platform. The resources are grouped into the following categories:

  • Congestion: congestion data
  • Tonnage: tonnage and speed related data
  • Trade Flows: trade flow data
  • Dry dock: individual dry dock stays on the vessel level and summary timeseries for dry dockings
  • Port Calls: Historic list of port calls on either vessel/port level
  • Entities: listing of various database entities in the Oceanbolt Platform
  • Fleet Management: management user defined fleets
  • Polygon Management: management user defined polygon layers

Detailed information on how to query and filter the data is available in the documentation on the individual endpoints.

Cross-Origin Resource Sharing

This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.

Authentication

Authentication to the Oceanbolt Data Api is done through bearer token. To make calls to the API, send the API token in the Authorization HTTP header using the Bearer authentication scheme. You can create access tokens from your profile page on: Oceanbolt Data Platform. Access tokens should be provided as a bearer token, e.g. it should be in the form of a header with the following format:

Authorization: Bearer <TOKEN>

Base url

Base url:

https://api.oceanbolt.com

Accessing Tanker data

By default the Oceanbolt API will extract data for dry bulk vessels, but it also covers multiple other shipping segments, such as tankers, lng and lpg carriers. In order to extract tanker data from the platform, you will need to specify the platform to connect to when making the request by adding the following header: x-ob-platform This expects to be a comma separated string of the platforms you would like to query data from, the options are:

  • dry
  • tanker
  • lng
  • lpg

E.g.

If you wanted just Tanker data:

x-ob-platform: tanker

If you would like data on Dry, Tanker and LNG then the header will look like the following:

x-ob-platform: dry,tanker,lng

CongestionService

GetCongestionVessels

GetCongestionVessels retrieves congestion data for a specified list of port_ids/segments

Request Body schema: application/json

Congestion request object.

portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the port where the vessel is currently congested.

portUnlocode
Array of strings

List of five letter UNLOCODEs for to filter on.

countryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel is currently congested. Country code can be obtained either from the /entities/countries endpoint.

regionId
Array of strings

The list of regionIds to get congestion data for. This filters on the region where the vessel is currently congested. Region Id can be obtained either from the /entities/regions endpoint.

operation
Array of strings

List of port call operation types to filter on. Allowed values are: **["load","discharge";"yard","unknown"].

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

ladenStatus
Array of strings

Laden status to filter on. Allowed values are ['laden', 'ballast'].

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /portcalls/timeseries endpoint.

frequency
string

Not implemented.

lastLoadCountryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel loaded its prior cargo. Country code can be obtained either from the /entities/countries endpoint.

lastLoadPortId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the ports where the vessel loaded its prior cargo.

exclude
integer <int32>

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of exlude=60'` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

maxStayLength
integer <int32>

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of max_stay_length=60'` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

includeVesselsCurrentlyAtBerth
boolean

Flag to indicate whether vessels that are currently at berth should be included in congestion statistics.

includeVesselsPreviouslyBerthed
boolean

Flag to indicate whether vessels that have already visited a berth (but are not currently in a berth) as part of the current Port Call should be included in congestion statistics.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

displayDate
string

Parameter used to display historical vessel lists for congested vessels. It is only applicable to the CongestionVessels method.

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "portUnlocode": [
    ],
  • "countryCode": [
    ],
  • "regionId": [
    ],
  • "operation": [
    ],
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "ladenStatus": [
    ],
  • "groupBy": "string",
  • "frequency": "string",
  • "lastLoadCountryCode": [
    ],
  • "lastLoadPortId": [
    ],
  • "exclude": 0,
  • "maxStayLength": 0,
  • "includeVesselsCurrentlyAtBerth": true,
  • "includeVesselsPreviouslyBerthed": true,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "sort": "string",
  • "displayDate": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "numberOfCurrentVessels": 0,
  • "currentTopPorts": [
    ],
  • "currentTopSubSegments": [
    ],
  • "currentTopCommodityGroups": [
    ],
  • "currentTopLoadCountries": [
    ],
  • "timeseriesDefault": {
    },
  • "currentVessels": [
    ],
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetCongestionTimeseries

GetCongestionTimeseries retrieves congestion data for a specified list of port_ids/segments

Request Body schema: application/json

Congestion request object.

portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the port where the vessel is currently congested.

portUnlocode
Array of strings

List of five letter UNLOCODEs for to filter on.

countryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel is currently congested. Country code can be obtained either from the /entities/countries endpoint.

regionId
Array of strings

The list of regionIds to get congestion data for. This filters on the region where the vessel is currently congested. Region Id can be obtained either from the /entities/regions endpoint.

operation
Array of strings

List of port call operation types to filter on. Allowed values are: **["load","discharge";"yard","unknown"].

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

ladenStatus
Array of strings

Laden status to filter on. Allowed values are ['laden', 'ballast'].

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /portcalls/timeseries endpoint.

frequency
string

Not implemented.

lastLoadCountryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel loaded its prior cargo. Country code can be obtained either from the /entities/countries endpoint.

lastLoadPortId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the ports where the vessel loaded its prior cargo.

exclude
integer <int32>

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of exlude=60'` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

maxStayLength
integer <int32>

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of max_stay_length=60'` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

includeVesselsCurrentlyAtBerth
boolean

Flag to indicate whether vessels that are currently at berth should be included in congestion statistics.

includeVesselsPreviouslyBerthed
boolean

Flag to indicate whether vessels that have already visited a berth (but are not currently in a berth) as part of the current Port Call should be included in congestion statistics.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

displayDate
string

Parameter used to display historical vessel lists for congested vessels. It is only applicable to the CongestionVessels method.

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "portUnlocode": [
    ],
  • "countryCode": [
    ],
  • "regionId": [
    ],
  • "operation": [
    ],
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "ladenStatus": [
    ],
  • "groupBy": "string",
  • "frequency": "string",
  • "lastLoadCountryCode": [
    ],
  • "lastLoadPortId": [
    ],
  • "exclude": 0,
  • "maxStayLength": 0,
  • "includeVesselsCurrentlyAtBerth": true,
  • "includeVesselsPreviouslyBerthed": true,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "sort": "string",
  • "displayDate": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "numberOfCurrentVessels": 0,
  • "currentTopPorts": [
    ],
  • "currentTopSubSegments": [
    ],
  • "currentTopCommodityGroups": [
    ],
  • "currentTopLoadCountries": [
    ],
  • "timeseriesDefault": {
    },
  • "currentVessels": [
    ],
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetCongestionWeb

GetCongestion retrieves congestion data for a specified list of port_ids/segments

Request Body schema: application/json

Congestion request object.

portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the port where the vessel is currently congested.

portUnlocode
Array of strings

List of five letter UNLOCODEs for to filter on.

countryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel is currently congested. Country code can be obtained either from the /entities/countries endpoint.

regionId
Array of strings

The list of regionIds to get congestion data for. This filters on the region where the vessel is currently congested. Region Id can be obtained either from the /entities/regions endpoint.

operation
Array of strings

List of port call operation types to filter on. Allowed values are: **["load","discharge";"yard","unknown"].

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

ladenStatus
Array of strings

Laden status to filter on. Allowed values are ['laden', 'ballast'].

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /portcalls/timeseries endpoint.

frequency
string

Not implemented.

lastLoadCountryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel loaded its prior cargo. Country code can be obtained either from the /entities/countries endpoint.

lastLoadPortId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the ports where the vessel loaded its prior cargo.

exclude
integer <int32>

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of exlude=60'` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

maxStayLength
integer <int32>

Specifies whether to exclude congestion stays that have a longer duration than N (in days). For example if a value of max_stay_length=60'` is specified then all congestion stays that lasted longer than 60 days will be excluded from the returned data.

includeVesselsCurrentlyAtBerth
boolean

Flag to indicate whether vessels that are currently at berth should be included in congestion statistics.

includeVesselsPreviouslyBerthed
boolean

Flag to indicate whether vessels that have already visited a berth (but are not currently in a berth) as part of the current Port Call should be included in congestion statistics.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

displayDate
string

Parameter used to display historical vessel lists for congested vessels. It is only applicable to the CongestionVessels method.

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "portUnlocode": [
    ],
  • "countryCode": [
    ],
  • "regionId": [
    ],
  • "operation": [
    ],
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "ladenStatus": [
    ],
  • "groupBy": "string",
  • "frequency": "string",
  • "lastLoadCountryCode": [
    ],
  • "lastLoadPortId": [
    ],
  • "exclude": 0,
  • "maxStayLength": 0,
  • "includeVesselsCurrentlyAtBerth": true,
  • "includeVesselsPreviouslyBerthed": true,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "sort": "string",
  • "displayDate": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "numberOfCurrentVessels": 0,
  • "currentTopPorts": [
    ],
  • "currentTopSubSegments": [
    ],
  • "currentTopCommodityGroups": [
    ],
  • "currentTopLoadCountries": [
    ],
  • "timeseriesDefault": {
    },
  • "currentVessels": [
    ],
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

CustomPolygonService

GetPolygonCounts

GetPolygonCounts returns vessels counts (points) in polygon the given filter parameters

Request Body schema: application/json
geojson
string (GeoJSON formatted string with polygon data)
ladenStatus
Array of strings (Laden status to filter on. Allowed values are ['laden', 'ballast'])
segment
Array of strings (List of vessel segments to filter on. Allowed values can be obtained from the **/entities/segments** endpoint. Cannot be supplied alongside subSegment)
subSegment
Array of strings (List of vessel sub segments to filter on. Allowed values can be obtained from the **/entities/segments** endpoint. Cannot be supplied alongside segment)
startDate
string (The UTC start date of the date filter)
endDate
string (The UTC end date of the date filter)

Responses

Request samples

Content type
application/json
{
  • "geojson": "string",
  • "ladenStatus": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "startDate": "string",
  • "endDate": "string"
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ]
}

DistanceCalculatorService

BatchCalculateDistance

Request Body schema: application/json
Array of objects (Array of distance requests)

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "responses": [
    ]
}

CalculateDistance

Calculates distances for the shortest route between a two or more locations. Distances are returned both for the voyage as a whole, and individually for each leg of the voyage. Endpoint also returns the shortest route as a series of points. If speed is specified, expected duration of the voyage will also be returned.

Request Body schema: application/json
Array of objects (distancecalculatorv3Location)

List of locations to calculate the shortest route between. If more than 2 locations are specified, then routing will be calculated through all locations, using intermediary locations as waypoints. The routing order of the locations will be based on the order of the locations in the request body.

speed
number <double>

An optional speed parameter. If this is supplied, then the API will return an estimate of the total duration of the voyage, based on the supplied speed. Speed parameter should be supplied in knots.

transform
string

Specifies a transformation to be applied to the returned shortest path. Allowed values are [great_circle].

longitudeAdjustment
string

Specifies whether the resulting points/lines crossing the antimeridian should be adjusted to form a continuous line for plotting. Allowed values are [antimeridian,none]. Default value is 'antimeridian.

blockSuez
boolean (Flag indicating whether to block navigation through the Suez Canal)
blockPanama
boolean (Flag indicating whether to Block navigation through the Panama Canal)

Responses

Request samples

Content type
application/json
{
  • "locations": [
    ],
  • "speed": 0,
  • "transform": "string",
  • "longitudeAdjustment": "string",
  • "blockSuez": true,
  • "blockPanama": true
}

Response samples

Content type
application/json
{
  • "totalDistance": 0,
  • "totalDurationHours": 0,
  • "totalShortestPath": [
    ],
  • "individualLegs": [
    ],
  • "status": "ERROR"
}

DrydockService

GetDryDockStays

GetDryDockStays retrives individual historical dry dock stays

Request Body schema: application/json
object (filtersVesselFilter)
portId
Array of integers <int32> [ items <int32 > ]

This filters on the port where the vessel is currently in dry dock.

shipyardId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt shipyard ids to filter on.

unlocode
Array of strings

UNLOCODE of the port.

startDate
string (The UTC start date of the date filter)
endDate
string (The UTC end date of the date filter)
latestOnly
boolean

Flat to indiciate whether only the latest port call should be included on an IMO basis. If this is enabled, only the latest port call for each imo passing the filter will be returned.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /drydock/timeseries endpoint.

Responses

Request samples

Content type
application/json
{
  • "vesselFilter": {
    },
  • "portId": [
    ],
  • "shipyardId": [
    ],
  • "unlocode": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "latestOnly": true,
  • "format": "string",
  • "sort": "string",
  • "groupBy": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "csv": "string",
  • "xlsx": "string",
  • "previousToken": "string",
  • "nextToken": "string",
  • "maxResults": 0
}

GetDryDockVessels

GetDryDockVessels retrieves list of currently active dry dock stays for a specified list of port_ids/segments

Request Body schema: application/json

DryDock request object.

portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the port where the vessel is currently in dry dock.

portUnlocode
Array of strings

List of five letter UNLOCODEs for to filter on.

shipyardId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt shipyard ids to filter on. This filters on the shipyard where the vessel is currently in dry dock.

countryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel is currently congested. Country code can be obtained either from the /entities/countries endpoint.

regionId
Array of strings

The list of region IDs to get dry dock data for. Region ID can be obtained either from the /entities/regions endpoint.

segment
Array of strings (Cannot be supplied alongside subSegment)
subSegment
Array of strings (List of vessel sub segments to filter on. Allowed values can be obtained from the **/entities/segments** endpoint. Cannot be supplied alongside segment)
groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /drydock/timeseries endpoint.

exclude
integer <int32>

60 days will be excluded from the returned data.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string (The UTC start date of the date filter)
endDate
string (The UTC end date of the date filter)
lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

displayDate
string

Parameter used to display historical vessel lists for congested vessels. It is only applicable to the DryDockVessels method.

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "portUnlocode": [
    ],
  • "shipyardId": [
    ],
  • "countryCode": [
    ],
  • "regionId": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "groupBy": "string",
  • "exclude": 0,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "sort": "string",
  • "displayDate": "string"
}

Response samples

Content type
application/json
{
  • "numberOfCurrentVessels": 0,
  • "currentTopPorts": [
    ],
  • "currentTopSubSegments": [
    ],
  • "currentTopCountries": [
    ],
  • "currentTopShipyards": [
    ],
  • "timeseriesDefault": {
    },
  • "currentVessels": [
    ],
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetDryDockTimeseries

GetDryDockTimeseries retrieves dry dock timeseries data for a specified list of port_ids/segments

Request Body schema: application/json

DryDock request object.

portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the port where the vessel is currently in dry dock.

portUnlocode
Array of strings

List of five letter UNLOCODEs for to filter on.

shipyardId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt shipyard ids to filter on. This filters on the shipyard where the vessel is currently in dry dock.

countryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel is currently congested. Country code can be obtained either from the /entities/countries endpoint.

regionId
Array of strings

The list of region IDs to get dry dock data for. Region ID can be obtained either from the /entities/regions endpoint.

segment
Array of strings (Cannot be supplied alongside subSegment)
subSegment
Array of strings (List of vessel sub segments to filter on. Allowed values can be obtained from the **/entities/segments** endpoint. Cannot be supplied alongside segment)
groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /drydock/timeseries endpoint.

exclude
integer <int32>

60 days will be excluded from the returned data.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string (The UTC start date of the date filter)
endDate
string (The UTC end date of the date filter)
lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

displayDate
string

Parameter used to display historical vessel lists for congested vessels. It is only applicable to the DryDockVessels method.

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "portUnlocode": [
    ],
  • "shipyardId": [
    ],
  • "countryCode": [
    ],
  • "regionId": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "groupBy": "string",
  • "exclude": 0,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "sort": "string",
  • "displayDate": "string"
}

Response samples

Content type
application/json
{
  • "numberOfCurrentVessels": 0,
  • "currentTopPorts": [
    ],
  • "currentTopSubSegments": [
    ],
  • "currentTopCountries": [
    ],
  • "currentTopShipyards": [
    ],
  • "timeseriesDefault": {
    },
  • "currentVessels": [
    ],
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetDryDockWeb

GetDryDockWeb retrieves current and live dry dock data for a specified list of port_ids/segments

Request Body schema: application/json

DryDock request object.

portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on. This filters on the port where the vessel is currently in dry dock.

portUnlocode
Array of strings

List of five letter UNLOCODEs for to filter on.

shipyardId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt shipyard ids to filter on. This filters on the shipyard where the vessel is currently in dry dock.

countryCode
Array of strings

The list of 2-letter ISO countries to get congestion data for. This filters on the country where the vessel is currently congested. Country code can be obtained either from the /entities/countries endpoint.

regionId
Array of strings

The list of region IDs to get dry dock data for. Region ID can be obtained either from the /entities/regions endpoint.

segment
Array of strings (Cannot be supplied alongside subSegment)
subSegment
Array of strings (List of vessel sub segments to filter on. Allowed values can be obtained from the **/entities/segments** endpoint. Cannot be supplied alongside segment)
groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /drydock/timeseries endpoint.

exclude
integer <int32>

60 days will be excluded from the returned data.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string (The UTC start date of the date filter)
endDate
string (The UTC end date of the date filter)
lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

displayDate
string

Parameter used to display historical vessel lists for congested vessels. It is only applicable to the DryDockVessels method.

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "portUnlocode": [
    ],
  • "shipyardId": [
    ],
  • "countryCode": [
    ],
  • "regionId": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "groupBy": "string",
  • "exclude": 0,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "sort": "string",
  • "displayDate": "string"
}

Response samples

Content type
application/json
{
  • "numberOfCurrentVessels": 0,
  • "currentTopPorts": [
    ],
  • "currentTopSubSegments": [
    ],
  • "currentTopCountries": [
    ],
  • "currentTopShipyards": [
    ],
  • "timeseriesDefault": {
    },
  • "currentVessels": [
    ],
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

EntityService

ListCommodities

ListCommodities retrives all commodities

Responses

Response samples

Content type
application/json
{
  • "commodities": [
    ]
}

ListCountries

ListCountries retrives all countries

Responses

Response samples

Content type
application/json
{
  • "countries": [
    ]
}

SearchPolygons

query Parameters
q
string

Responses

Response samples

Content type
application/json
{
  • "polygons": [
    ]
}

ListPorts

ListPorts retrieves all ports

Responses

Response samples

Content type
application/json
{
  • "ports": [
    ]
}

ListRegions

ListRegions retrives all regions

Responses

Response samples

Content type
application/json
{
  • "regions": [
    ]
}

ListRegionsWithPolygons

ListRegionsWithPolygons retrives all regions with geo polygons

Responses

Response samples

Content type
application/json
{
  • "regions": [
    ]
}

ListSegments

ListSegments retrieves all available vessel segments

Responses

Response samples

Content type
application/json
{
  • "segments": [
    ]
}

ListShipyards

Responses

Response samples

Content type
application/json
{
  • "shipyards": [
    ]
}

SearchVessels

query Parameters
q
string

Responses

Response samples

Content type
application/json
{
  • "vessels": [
    ]
}

ListZones

ListZones retrieves all zones

Responses

Response samples

Content type
application/json
{
  • "zones": [
    ]
}

ListZonesWithPolygons

ListZonesWithPolygons retrieves all zones with Polygons

Responses

Response samples

Content type
application/json
{
  • "zones": [
    ]
}

FleetManagementService

ListFleets

Lists Fleets for the current user (or fleets that are shared with the current user)

Responses

Response samples

Content type
application/json
{
  • "fleets": [
    ],
  • "organizationFleets": [
    ],
  • "predefinedFleets": [
    ]
}

CreateFleet

Creates a new Fleet for the current user.

Request Body schema: application/json
fleetName
string

The new name of the Fleet.

Responses

Request samples

Content type
application/json
{
  • "fleetName": "string"
}

Response samples

Content type
application/json
{
  • "fleetId": "string",
  • "fleetName": "string",
  • "platform": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "vesselsInFleet": 0,
  • "vessels": [
    ],
  • "sharedWithOrg": true
}

GetFleetLiveMap

GetFleetLiveMap display static location for vessels in a fleet (as static image).

query Parameters
fleetId
string

Identifier of the Fleet resource

mapTheme
string

Specifies the map theme. Allowed values are: [light-v10, dark-v10, navigation-night-v1, navigation-day-v1, outdoors-v11, satellite-v9]

Responses

Response samples

Content type
application/json
{
  • "mapImage": "string"
}

UploadFleetList

Uploads file containing fleet data to be parsed into a batch of vessels.

Request Body schema: application/json
fileName
string (Original file name including file extension)
file
string <byte> (Serialized file data) ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[...
fleetId
string (Fleet ID of existing fleet)
fleetName
string (Name of existing fleet)
overwrite
boolean (Specifies whether an existing fleet should be appended or overwritten)

Responses

Request samples

Content type
application/json
{
  • "fileName": "string",
  • "file": "string",
  • "fleetId": "string",
  • "fleetName": "string",
  • "overwrite": true
}

Response samples

Content type
application/json
{ }

DescribeFleet

Retrieves fleet by Fleet id.

path Parameters
fleetId
required
string

Identifier of the Fleet resource to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "fleetId": "string",
  • "fleetName": "string",
  • "platform": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "vesselsInFleet": 0,
  • "vessels": [
    ],
  • "sharedWithOrg": true
}

DeleteFleet

Deletes a Fleet for the current user.

path Parameters
fleetId
required
string

Identifier of the Fleet resource to be deleted.

Responses

Response samples

Content type
application/json
{ }

BatchAddVessels

Batch adds vessels into a Fleet. A maximum of 1000 vessels can be added to a fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource where vessels should be added.

Request Body schema: application/json
Array of objects (Vessel parameters)

List of Vessels to be added.

Responses

Request samples

Content type
application/json
{
  • "vessels": [
    ]
}

Response samples

Content type
application/json
{ }

DropVessels

Drops all the vessels currently in a fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource where vessels should be dropped.

Responses

Response samples

Content type
application/json
{ }

RenameFleet

Changes the name of a Fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource to be renamed.

Request Body schema: application/json
newFleetName
string

The new name of the Fleet.

Responses

Request samples

Content type
application/json
{
  • "newFleetName": "string"
}

Response samples

Content type
application/json
{
  • "fleetId": "string",
  • "fleetName": "string",
  • "platform": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "vesselsInFleet": 0,
  • "vessels": [
    ],
  • "sharedWithOrg": true
}

ReplaceVessels

Replaces the existing vessels in a Fleet with a batch of new vessels. This is equivalent to first calling DropVessels and then calling BatchAddVessels A maximum of 1000 vessels can be added to a fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource where vessels should be added.

Request Body schema: application/json
Array of objects (Vessel parameters)

List of Vessels to be added.

Responses

Request samples

Content type
application/json
{
  • "vessels": [
    ]
}

Response samples

Content type
application/json
{ }

ShareFleet

Sets the shared status of the Fleet to be shared.

path Parameters
fleetId
required
string

Identifier of the Fleet resource to be shared.

Responses

Response samples

Content type
application/json
{
  • "fleetId": "string",
  • "fleetName": "string",
  • "platform": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "vesselsInFleet": 0,
  • "vessels": [
    ],
  • "sharedWithOrg": true
}

UnshareFleet

Sets the shared status of the Fleet to be not shared.

path Parameters
fleetId
required
string

Identifier of the Fleet resource to be shared.

Responses

Response samples

Content type
application/json
{
  • "fleetId": "string",
  • "fleetName": "string",
  • "platform": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "vesselsInFleet": 0,
  • "vessels": [
    ],
  • "sharedWithOrg": true
}

ListVessels

Retrieves list of vessels in a Fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource which vessels to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "vessels": [
    ],
  • "vesselsInFleet": 0
}

AddVessel

Adds new vessel to a Fleet. A maximum of 1000 vessels can be added to a fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource where vessels should be added.

Request Body schema: application/json
object (Vessel parameters)

Responses

Request samples

Content type
application/json
{
  • "vessel": {
    }
}

Response samples

Content type
application/json
{
  • "imo": 0,
  • "dwt": 0,
  • "built": 0,
  • "vesselName": "string",
  • "segment": "string",
  • "subSegment": "string",
  • "flagCode": "string",
  • "exName": "string",
  • "type": "string",
  • "metadata": {
    },
  • "status": {
    },
  • "stoppageEvents": [
    ]
}

ListVesselsWithStatus

Retrieves list of vessels in a Fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource which vessels to be retrieved.

query Parameters
lastDays
integer <int32>

Number of last days from now for vessel StoppageEvents to be retrieved. Cannot be used alongside start_date and end_date.

startDate
string

The UTC start date of the date filter for related events (StoppageEvents etc.)

endDate
string

The UTC end date of the date filter for related events (StoppageEvents etc.)

Responses

Response samples

Content type
application/json
{
  • "vessels": [
    ],
  • "vesselsInFleet": 0
}

GetVessel

Retrieves vessel in a Fleet by Fleet id and imo.

path Parameters
fleetId
required
string

Identifier of the Fleet resource which vessels to be retrieved.

imo
required
integer <int32>

Imo of the vessel.

Responses

Response samples

Content type
application/json
{
  • "imo": 0,
  • "dwt": 0,
  • "built": 0,
  • "vesselName": "string",
  • "segment": "string",
  • "subSegment": "string",
  • "flagCode": "string",
  • "exName": "string",
  • "type": "string",
  • "metadata": {
    },
  • "status": {
    },
  • "stoppageEvents": [
    ]
}

UpdateVessel

Updates existing metadata for a Vessel.

path Parameters
fleetId
required
string

Identifier of the Fleet resource where the vessel should be updated.

imo
required
integer <int32>

IMO number of the vessel to be updated.

Request Body schema: application/json
object (Parameter object for updating a vessel in a Fleet)
upsert
boolean

Flag indicating whether the vessel should be created if it doesnt not already exist. If the upsert flag is set to false, and a vessel does not already exist, the function will return an error.

Responses

Request samples

Content type
application/json
{
  • "vessel": {
    },
  • "upsert": true
}

Response samples

Content type
application/json
{
  • "imo": 0,
  • "dwt": 0,
  • "built": 0,
  • "vesselName": "string",
  • "segment": "string",
  • "subSegment": "string",
  • "flagCode": "string",
  • "exName": "string",
  • "type": "string",
  • "metadata": {
    },
  • "status": {
    },
  • "stoppageEvents": [
    ]
}

DeleteVessel

Removes a vessel from a Fleet.

path Parameters
fleetId
required
string

Identifier of the Fleet resource where the vessel should be deleted.

imo
required
integer <int32>

IMO number of the Vessel to be deleted.

Responses

Response samples

Content type
application/json
{ }

LiveStateService

AisQuality

AisQuality returns the overview of how many positions reseived for vessels in different time periods

Request Body schema: application/json
eta
Array of strings (LiveStateRequestBody live_state_request_body = 1;)

before,after on the eta columns

loadRegion
Array of strings (included load regions)
loadCountry
Array of strings (included load countries)
loadPort
Array of strings (included load ports)
destinationRegion
Array of strings (included discharge regions)
destinationCountry
Array of strings (included discharge countries)
destinationPort
Array of strings (included discharge ports)
destinationUnlocode
Array of strings (included discharge ports)
cargoStatus
Array of strings (included cargo states)
ladenStatus
Array of strings (included laden states)
ladenStatusDraught
Array of strings (included laden states)
speed
Array of numbers <double> (min,max on the speed column) [ items <double > ]
draught
Array of numbers <double> (min,max on the draught column) [ items <double > ]
excludeUnknownDestination
boolean (include rows where destination_country is blank)
group
string (group by filter parameter)
range
string (range value for timeseries request (ex: month/monthly, week/weekly))
flowDate
string (flow date (of load/discharge) for timeseries request)
commodity
Array of strings (included commodity values)
commodityGroup
Array of strings (included commodity values)
object (v4BoundingBox)
zoneId
Array of integers <int64> (included zone ids) [ items <int64 > ]
portId
Array of integers <int64> (included port ids) [ items <int64 > ]
anchorageId
Array of integers <int64> (included anchorage ids) [ items <int64 > ]
berthId
Array of integers <int64> (included berth ids) [ items <int64 > ]
shipyardId
Array of integers <int64> (included shipyard ids) [ items <int64 > ]
direction
Array of strings (included diretions)
portStatus
Array of strings
excludeMpv
boolean
limit
integer <int64>
hoursSinceLast
integer <int64> (parameter for aisquality request)
format
string (response format (default is json, supported csv))
object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "eta": [
    ],
  • "loadRegion": [
    ],
  • "loadCountry": [
    ],
  • "loadPort": [
    ],
  • "destinationRegion": [
    ],
  • "destinationCountry": [
    ],
  • "destinationPort": [
    ],
  • "destinationUnlocode": [
    ],
  • "cargoStatus": [
    ],
  • "ladenStatus": [
    ],
  • "ladenStatusDraught": [
    ],
  • "speed": [
    ],
  • "draught": [
    ],
  • "excludeUnknownDestination": true,
  • "group": "string",
  • "range": "string",
  • "flowDate": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "boundingBox": {
    },
  • "zoneId": [
    ],
  • "portId": [
    ],
  • "anchorageId": [
    ],
  • "berthId": [
    ],
  • "shipyardId": [
    ],
  • "direction": [
    ],
  • "portStatus": [
    ],
  • "excludeMpv": true,
  • "limit": 0,
  • "hoursSinceLast": 0,
  • "format": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "vesselSegmentsByTime": [
    ],
  • "zonesByTime": [
    ],
  • "zonesBySegment": [
    ]
}

VesselsInArea

VesselsInArea gets vessels as geo objects in rectangular area for the given filter parameters

Request Body schema: application/json
eta
Array of strings (LiveStateRequestBody live_state_request_body = 1;)

before,after on the eta columns

loadRegion
Array of strings (included load regions)
loadCountry
Array of strings (included load countries)
loadPort
Array of strings (included load ports)
destinationRegion
Array of strings (included discharge regions)
destinationCountry
Array of strings (included discharge countries)
destinationPort
Array of strings (included discharge ports)
destinationUnlocode
Array of strings (included discharge ports)
cargoStatus
Array of strings (included cargo states)
ladenStatus
Array of strings (included laden states)
ladenStatusDraught
Array of strings (included laden states)
speed
Array of numbers <double> (min,max on the speed column) [ items <double > ]
draught
Array of numbers <double> (min,max on the draught column) [ items <double > ]
excludeUnknownDestination
boolean (include rows where destination_country is blank)
group
string (group by filter parameter)
range
string (range value for timeseries request (ex: month/monthly, week/weekly))
flowDate
string (flow date (of load/discharge) for timeseries request)
commodity
Array of strings (included commodity values)
commodityGroup
Array of strings (included commodity values)
object (v4BoundingBox)
zoneId
Array of integers <int64> (included zone ids) [ items <int64 > ]
portId
Array of integers <int64> (included port ids) [ items <int64 > ]
anchorageId
Array of integers <int64> (included anchorage ids) [ items <int64 > ]
berthId
Array of integers <int64> (included berth ids) [ items <int64 > ]
shipyardId
Array of integers <int64> (included shipyard ids) [ items <int64 > ]
direction
Array of strings (included diretions)
portStatus
Array of strings
excludeMpv
boolean
limit
integer <int64>
hoursSinceLast
integer <int64> (parameter for aisquality request)
format
string (response format (default is json, supported csv))
object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "eta": [
    ],
  • "loadRegion": [
    ],
  • "loadCountry": [
    ],
  • "loadPort": [
    ],
  • "destinationRegion": [
    ],
  • "destinationCountry": [
    ],
  • "destinationPort": [
    ],
  • "destinationUnlocode": [
    ],
  • "cargoStatus": [
    ],
  • "ladenStatus": [
    ],
  • "ladenStatusDraught": [
    ],
  • "speed": [
    ],
  • "draught": [
    ],
  • "excludeUnknownDestination": true,
  • "group": "string",
  • "range": "string",
  • "flowDate": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "boundingBox": {
    },
  • "zoneId": [
    ],
  • "portId": [
    ],
  • "anchorageId": [
    ],
  • "berthId": [
    ],
  • "shipyardId": [
    ],
  • "direction": [
    ],
  • "portStatus": [
    ],
  • "excludeMpv": true,
  • "limit": 0,
  • "hoursSinceLast": 0,
  • "format": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "vesselsTotal": 0,
  • "vesselsReturned": 0,
  • "vesselsInView": 0,
  • "vessels": [
    ]
}

Vessels

Vessels gets a list of vessels for the given filter parameters

Request Body schema: application/json
eta
Array of strings (LiveStateRequestBody live_state_request_body = 1;)

before,after on the eta columns

loadRegion
Array of strings (included load regions)
loadCountry
Array of strings (included load countries)
loadPort
Array of strings (included load ports)
destinationRegion
Array of strings (included discharge regions)
destinationCountry
Array of strings (included discharge countries)
destinationPort
Array of strings (included discharge ports)
destinationUnlocode
Array of strings (included discharge ports)
cargoStatus
Array of strings (included cargo states)
ladenStatus
Array of strings (included laden states)
ladenStatusDraught
Array of strings (included laden states)
speed
Array of numbers <double> (min,max on the speed column) [ items <double > ]
draught
Array of numbers <double> (min,max on the draught column) [ items <double > ]
excludeUnknownDestination
boolean (include rows where destination_country is blank)
group
string (group by filter parameter)
range
string (range value for timeseries request (ex: month/monthly, week/weekly))
flowDate
string (flow date (of load/discharge) for timeseries request)
commodity
Array of strings (included commodity values)
commodityGroup
Array of strings (included commodity values)
object (v4BoundingBox)
zoneId
Array of integers <int64> (included zone ids) [ items <int64 > ]
portId
Array of integers <int64> (included port ids) [ items <int64 > ]
anchorageId
Array of integers <int64> (included anchorage ids) [ items <int64 > ]
berthId
Array of integers <int64> (included berth ids) [ items <int64 > ]
shipyardId
Array of integers <int64> (included shipyard ids) [ items <int64 > ]
direction
Array of strings (included diretions)
portStatus
Array of strings
excludeMpv
boolean
limit
integer <int64>
hoursSinceLast
integer <int64> (parameter for aisquality request)
format
string (response format (default is json, supported csv))
object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "eta": [
    ],
  • "loadRegion": [
    ],
  • "loadCountry": [
    ],
  • "loadPort": [
    ],
  • "destinationRegion": [
    ],
  • "destinationCountry": [
    ],
  • "destinationPort": [
    ],
  • "destinationUnlocode": [
    ],
  • "cargoStatus": [
    ],
  • "ladenStatus": [
    ],
  • "ladenStatusDraught": [
    ],
  • "speed": [
    ],
  • "draught": [
    ],
  • "excludeUnknownDestination": true,
  • "group": "string",
  • "range": "string",
  • "flowDate": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "boundingBox": {
    },
  • "zoneId": [
    ],
  • "portId": [
    ],
  • "anchorageId": [
    ],
  • "berthId": [
    ],
  • "shipyardId": [
    ],
  • "direction": [
    ],
  • "portStatus": [
    ],
  • "excludeMpv": true,
  • "limit": 0,
  • "hoursSinceLast": 0,
  • "format": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "vessels": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

PolygonManagementService

ListLayers

ListLayers lists layers for the current user

Responses

Response samples

Content type
application/json
{
  • "layers": [
    ]
}

CreateLayer

CreateLayer creates new layer for the current user

Request Body schema: application/json
layerId
string

Responses

Request samples

Content type
application/json
{
  • "layerId": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "layerId": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "polygonsInLayer": 0,
  • "polygons": [
    ],
  • "sharedWithOrg": true
}

DescribeLayer

GetLayer gets fleed by layer id for the current user

path Parameters
layerId
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "layerId": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "polygonsInLayer": 0,
  • "polygons": [
    ],
  • "sharedWithOrg": true
}

DeleteLayer

DeleteLayer deletes layer for the current user

path Parameters
layerId
required
string

Responses

Response samples

Content type
application/json
{ }

BatchAddPolygons

BatchAddPolygons adds a batch of polygons to a layer

path Parameters
layerId
required
string
Request Body schema: application/json
Array of objects (v3Polygon1)
upsert
boolean

Responses

Request samples

Content type
application/json
{
  • "polygons": [
    ],
  • "upsert": true
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

CopyLayer

CopyLayer creates a copy of the existing layer for the current user

path Parameters
layerId
required
string
query Parameters
newLayerId
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "layerId": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "polygonsInLayer": 0,
  • "polygons": [
    ],
  • "sharedWithOrg": true
}

DropPolygons

Drop polygons drops all polygons from a layer

path Parameters
layerId
required
string

Responses

Response samples

Content type
application/json
{ }

ListPolygons

GetLayerPolygons gets polygons for a given layer

path Parameters
layerId
required
string

Responses

Response samples

Content type
application/json
{
  • "polygons": [
    ]
}

AddPolygon

AddPolygon adds new polygon to a layer

path Parameters
layerId
required
string
query Parameters
polygonId
string
Request Body schema: application/json
name
string
polygonId
string
geojson
string
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "polygonId": "string",
  • "geojson": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "polygonId": "string",
  • "geojson": "string",
  • "metadata": {
    }
}

UpdatePolygon

UpdatePolygon updates a polygon in a given layer

path Parameters
layerId
required
string
polygonId
required
string
query Parameters
upsert
boolean
Request Body schema: application/json
name
string
polygonId
string
geojson
string
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "polygonId": "string",
  • "geojson": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "polygonId": "string",
  • "geojson": "string",
  • "metadata": {
    }
}

DeletePolygon

DeletePolygon removes a polygon from a given layer

path Parameters
layerId
required
string
polygonId
required
string

Responses

Response samples

Content type
application/json
{ }

ReplacePolygons

ReplacePolygons replaces all existing polygons in a layer with a new batch of polygons

path Parameters
layerId
required
string
Request Body schema: application/json
Array of objects (v3Polygon1)

Responses

Request samples

Content type
application/json
{
  • "polygons": [
    ]
}

Response samples

Content type
application/json
{ }

ShareLayer

Sets the shared status of the layer to be either shared/not shared

path Parameters
layerId
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "layerId": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "polygonsInLayer": 0,
  • "polygons": [
    ],
  • "sharedWithOrg": true
}

UnshareLayer

Sets the shared status of the layer to be either shared/not shared

path Parameters
layerId
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "layerId": "string",
  • "ownerUserId": "string",
  • "organization": "string",
  • "polygonsInLayer": 0,
  • "polygons": [
    ],
  • "sharedWithOrg": true
}

PortCallService

GetPortParticulars

ListPortCalls retrieves lists all port calls for a given vessel. Response is paginated, and endpoint accepts a paging parameter to specify which page to return. It is also possible to set the number of port calls to return per query, default is 50 and maximum is 2000.

Request Body schema: application/json
startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

portId
integer <int32>

Oceanbolt port identifier to filter on.

berthId
integer <int32>

Oceanbolt berth identifier to filter on.

unlocode
string

Unlocode port identifier to filter on.

lastNDays
integer <int32>

Alternative way of specifying date filter. If specified, then data will only be based on port calls in last X days.

Responses

Request samples

Content type
application/json
{
  • "startDate": "string",
  • "endDate": "string",
  • "portId": 0,
  • "berthId": 0,
  • "unlocode": "string",
  • "lastNDays": 0
}

Response samples

Content type
application/json
{
  • "numberOfPortCalls": 0,
  • "loa": {
    },
  • "beam": {
    },
  • "maxDraught": {
    },
  • "reportedDraught": {
    },
  • "dwt": {
    },
  • "airDraught": {
    }
}

GetPortCalls

ListPortCalls retrieves lists all port calls for a set of request params. Response is paginated, and endpoint accepts a paging parameter to specify which page to return. It is also possible to set the number of port calls to return per query, default is 50 and maximum is 2000.

Request Body schema: application/json
portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on.

berthId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt berth ids to filter on.

unlocode
Array of strings

List of five letter UNLOCODEs of ports to filter on.

countryCode
Array of strings

List of two letter ISO country codes to filter on.

region
Array of strings

List of regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

basin
Array of strings

List of basins to filter on. Allowed values are: ["atlantic","indian_ocean","pacific_americas","pacific_asia"].

latestOnly
boolean

Flat to indiciate whether only the latest port call should be included on an IMO basis. If this is enabled, only the latest port call for each imo passing the filter will be returned.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

operation
Array of strings

List of port call operation types to filter on. Allowed values are: **["D","Dx";"L","Lx","B","Y","U"].

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /portcalls/timeseries endpoint.

frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly "yearly"]. Default value is "monthly". This parameter only applies to the /portcalls/timeseries endpoint.

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "berthId": [
    ],
  • "unlocode": [
    ],
  • "countryCode": [
    ],
  • "region": [
    ],
  • "basin": [
    ],
  • "latestOnly": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "operation": [
    ],
  • "sort": "string",
  • "groupBy": "string",
  • "frequency": "string",
  • "limitGroups": true,
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "prevToken": "string",
  • "nextToken": "string",
  • "data": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetPortCallTimeseries

GetPortCallTimeseries retrieves aggregated counts for port calls for a set of request params.

Request Body schema: application/json
portId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt port ids to filter on.

berthId
Array of integers <int32> [ items <int32 > ]

List of Oceanbolt berth ids to filter on.

unlocode
Array of strings

List of five letter UNLOCODEs of ports to filter on.

countryCode
Array of strings

List of two letter ISO country codes to filter on.

region
Array of strings

List of regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

basin
Array of strings

List of basins to filter on. Allowed values are: ["atlantic","indian_ocean","pacific_americas","pacific_asia"].

latestOnly
boolean

Flat to indiciate whether only the latest port call should be included on an IMO basis. If this is enabled, only the latest port call for each imo passing the filter will be returned.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

operation
Array of strings

List of port call operation types to filter on. Allowed values are: **["D","Dx";"L","Lx","B","Y","U"].

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /portcalls/timeseries endpoint.

frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly "yearly"]. Default value is "monthly". This parameter only applies to the /portcalls/timeseries endpoint.

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "portId": [
    ],
  • "berthId": [
    ],
  • "unlocode": [
    ],
  • "countryCode": [
    ],
  • "region": [
    ],
  • "basin": [
    ],
  • "latestOnly": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "startDate": "string",
  • "endDate": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "operation": [
    ],
  • "sort": "string",
  • "groupBy": "string",
  • "frequency": "string",
  • "limitGroups": true,
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetVesselsInPort

GetVesselsInPort lists all vessels that were within a port (or related anchorages) at a certain time.

Request Body schema: application/json
portId
integer <int64> (Database id of the port to filter on)
unlocode
string (UNLOCODE of the port to filter on)
object (filtersVesselFilter)
timestamp
string <date-time>

Timestamp to generate the vessel in port list for. This allows to generate historical snapshots of the vessels that were inside a port at a given time in history. If left blank, then it the vessel list will default to be generated for the current time.

mergeSequentialPolygonStays
boolean

Flag to indicate whether to merge sequential berth stays in same berth (if the stays are within the merge threshold). Default is false, meaning that by default berth stays will not be merged.

mergeThresholdHours
number <double>

The threshold in hours for a merge to take place for multiple consequtive stays. If the time from when the vessel left the berth until it reentered into the same berth is above the threshold, the polygon stays will not be merged. Default value is 6 hours.

Responses

Request samples

Content type
application/json
{
  • "portId": 0,
  • "unlocode": "string",
  • "vesselFilter": {
    },
  • "timestamp": "2019-08-24T14:15:22Z",
  • "mergeSequentialPolygonStays": true,
  • "mergeThresholdHours": 0
}

Response samples

Content type
application/json
{
  • "vesselsInPort": 0,
  • "data": [
    ]
}

SustainabilityService

GetCorruptPortCalls

GetCorruptPortCalls retrieves lists of all port calls inside corrupt ports.

Request Body schema: application/json

Corrupt port call request object.

imo
Array of integers <int64> [ items <int64 > ]

List of IMO numbers of the specified vessels.

startDate
string

Start of port call date range.

endDate
string

End of port call date range.

Responses

Request samples

Content type
application/json
{
  • "imo": [
    ],
  • "startDate": "string",
  • "endDate": "string"
}

Response samples

Content type
application/json
{
  • "visits": [
    ]
}

GetJwcListedAreaPolygons

GetJwcListedAreaPolygons lists all jwc listed polygons.

Request Body schema: application/json
object (v3GetJwcListedAreaPolygonsRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "jwcPolygons": [
    ]
}

GetJwcListedAreaStays

GetJwcListedAreaStays retrieves lists of all stays inside jwc listed areas for a single vessel.

query Parameters
imo
integer <int32>
startDate
string
endDate
string
format
string

Responses

Response samples

Content type
application/json
{
  • "jwcStays": [
    ],
  • "file": "string"
}

GetJwcListedAreaSummary

GetJwcListedAreaSummary retrieves lists of all stays inside jwc listed areas.

Request Body schema: application/json
Array of objects (v3JwcReportingPeriodRequest)
format
string

Responses

Request samples

Content type
application/json
{
  • "reportingPeriods": [
    ],
  • "format": "string"
}

Response samples

Content type
application/json
{
  • "summaryRows": [
    ],
  • "jwcStays": [
    ],
  • "file": "string"
}

GetMarineProtectedAreaPolygons

GetMarineProtectedAreaPolygons lists all marine protected area polygons.

Request Body schema: application/json
object (v3GetMarineProtectedAreaPolygonsRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "mpaPolygons": [
    ]
}

GetMarineProtectedAreaStays

GetMarineProtectedAreaStays retrieves lists of all stays inside marine protected areas for a single vessel.

query Parameters
imo
integer <int32>
startDate
string
endDate
string
format
string

Responses

Response samples

Content type
application/json
{
  • "mpaStays": [
    ],
  • "file": "string"
}

GetMarineProtectedAreaSummary

GetMarineProtectedAreaSummary retrieves lists of all stays inside marine protected areas.

Request Body schema: application/json
Array of objects (v3MpaReportingPeriodRequest)
format
string

Responses

Request samples

Content type
application/json
{
  • "reportingPeriods": [
    ],
  • "format": "string"
}

Response samples

Content type
application/json
{
  • "summaryRows": [
    ],
  • "mpaStays": [
    ],
  • "file": "string"
}

TonnageService

GetTonnageBasinCount

Provides timeseries data on the number of vessels that are within the four major basins.

Request Body schema: application/json
basin
Array of strings
segment
Array of strings
subSegment
Array of strings
startDate
string
endDate
string
excludeMpv
boolean
lastNDays
integer <int32>
format
string

Responses

Request samples

Content type
application/json
{
  • "basin": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "excludeMpv": true,
  • "lastNDays": 0,
  • "format": "string"
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTonnageChineseWaters

Provides chinese waters tonnage timeseries data. This timeseries shows the number of Chinese flagged that are trading inside and outside of Chinese waters respectively.

Request Body schema: application/json
startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

segment
Array of strings

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

subSegment
Array of strings

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

groupBy
string

Determines the grouping of the timeseries data.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

Responses

Request samples

Content type
application/json
{
  • "startDate": "string",
  • "endDate": "string",
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "groupBy": "string",
  • "sort": "string",
  • "format": "string"
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTonnageFleetGrowth

Provides fleet growth timeseries of how the fleet have developed over time. This timeseries shows number of vessels added to/removed from the fleet during any given period.

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly "yearly"]. Default value is "monthly".

segment
Array of strings

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

subSegment
Array of strings

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

groupBy
string

Determines the grouping of the timeseries data.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["count","dwt"]. Default is "count".

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

excludeMpv
boolean

Flag to specify whether or not MPV vessels should be included/excluded. Default is to include.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "groupBy": "string",
  • "metric": "string",
  • "format": "string",
  • "excludeMpv": true,
  • "sort": "string",
  • "startDate": "string",
  • "endDate": "string"
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTonnageFleetStatus

Provides fleet status timeseries of how the fleet have developed over time. This timeseries shows number of active vessels on the water at any given time.

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly "yearly"]. Default value is "monthly".

segment
Array of strings

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

subSegment
Array of strings

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

groupBy
string

Determines the grouping of the timeseries data.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["count","dwt"]. Default is "count".

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

excludeMpv
boolean

Flag to specify whether or not MPV vessels should be included/excluded. Default is to include.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "groupBy": "string",
  • "metric": "string",
  • "format": "string",
  • "excludeMpv": true,
  • "sort": "string",
  • "startDate": "string",
  • "endDate": "string"
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTonnageFleetSpeed

Fetches fleet speed timeseries.

Request Body schema: application/json

Request object for getting tonnage zone data and fleet speed data.

zoneId
Array of integers <int32> [ items <int32 > ]

List of zones ids to filter on. Allowed values can be obtained from the /entities/zones endpoint.

segment
Array of strings

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

subSegment
Array of strings

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

direction
Array of strings

The list of directions to get tonnage data for. The following directions are allowed: ["NNE","ENE","ESE","SSE","SSW","WSW","WNW","NNW"]. Directions can also be obtained from the interactive direction selector found at app.oceanbolt.com.

ladenStatus
Array of strings

The laden status to get tonnage data for. The following values are allowed: ["laden","ballast"].

portStatus
Array of strings

The port status to get tonnage data for. The following values are allowed: ["in_port","at_sea"].

groupBy
string (Not Implemented Yet //TODO)
excludeMpv
boolean

Flag to specify whether or not MPV vessels should be included/excluded. Default is to include.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

Responses

Request samples

Content type
application/json
{
  • "zoneId": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "direction": [
    ],
  • "ladenStatus": [
    ],
  • "portStatus": [
    ],
  • "groupBy": "string",
  • "excludeMpv": true,
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "format": "string",
  • "sort": "string"
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTonnageZoneCount

Fetches tonnage counts timeseries.

Request Body schema: application/json

Request object for getting tonnage zone data and fleet speed data.

zoneId
Array of integers <int32> [ items <int32 > ]

List of zones ids to filter on. Allowed values can be obtained from the /entities/zones endpoint.

segment
Array of strings

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

subSegment
Array of strings

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

direction
Array of strings

The list of directions to get tonnage data for. The following directions are allowed: ["NNE","ENE","ESE","SSE","SSW","WSW","WNW","NNW"]. Directions can also be obtained from the interactive direction selector found at app.oceanbolt.com.

ladenStatus
Array of strings

The laden status to get tonnage data for. The following values are allowed: ["laden","ballast"].

portStatus
Array of strings

The port status to get tonnage data for. The following values are allowed: ["in_port","at_sea"].

groupBy
string (Not Implemented Yet //TODO)
excludeMpv
boolean

Flag to specify whether or not MPV vessels should be included/excluded. Default is to include.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

Responses

Request samples

Content type
application/json
{
  • "zoneId": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "direction": [
    ],
  • "ladenStatus": [
    ],
  • "portStatus": [
    ],
  • "groupBy": "string",
  • "excludeMpv": true,
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "format": "string",
  • "sort": "string"
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetGlobalTonnageStatus

Fetches global tonnage status timeseries.

Request Body schema: application/json

Request object for getting tonnage zone data and fleet speed data.

zoneId
Array of integers <int32> [ items <int32 > ]

List of zones ids to filter on. Allowed values can be obtained from the /entities/zones endpoint.

segment
Array of strings

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

subSegment
Array of strings

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

direction
Array of strings

The list of directions to get tonnage data for. The following directions are allowed: ["NNE","ENE","ESE","SSE","SSW","WSW","WNW","NNW"]. Directions can also be obtained from the interactive direction selector found at app.oceanbolt.com.

ladenStatus
Array of strings

The laden status to get tonnage data for. The following values are allowed: ["laden","ballast"].

portStatus
Array of strings

The port status to get tonnage data for. The following values are allowed: ["in_port","at_sea"].

groupBy
string (Not Implemented Yet //TODO)
excludeMpv
boolean

Flag to specify whether or not MPV vessels should be included/excluded. Default is to include.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days.

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

Responses

Request samples

Content type
application/json
{
  • "zoneId": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "direction": [
    ],
  • "ladenStatus": [
    ],
  • "portStatus": [
    ],
  • "groupBy": "string",
  • "excludeMpv": true,
  • "startDate": "string",
  • "endDate": "string",
  • "lastNDays": 0,
  • "format": "string",
  • "sort": "string"
}

Response samples

Content type
application/json
{
  • "globalTonnageZoneCounts": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTonnageZoneChanges

Provides timeseries data on the number of vessels that cross zone boundaries during any given period.

Request Body schema: application/json
fromZoneId
Array of integers <int32> [ items <int32 > ]
toZoneId
Array of integers <int32> [ items <int32 > ]
segment
Array of strings

List of vessel segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside subSegment.

subSegment
Array of strings

List of vessel sub segments to filter on. Allowed values can be obtained from the /entities/segments endpoint. Cannot be supplied alongside segment.

ladenStatus
Array of strings

The laden status to get tonnage data for. The following values are allowed: ["laden","ballast"].

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

groupBy
string

Determines the grouping of the timeseries data.

sort
string

Specifies whether results should be sorted in ascending or descing order. Allowed values: ["asc","desc"].

format
string

The return format of the data ["csv","json", "xlsx"]. Default is "json".

frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly "yearly"]. Default value is "monthly".

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "fromZoneId": [
    ],
  • "toZoneId": [
    ],
  • "segment": [
    ],
  • "subSegment": [
    ],
  • "ladenStatus": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "groupBy": "string",
  • "sort": "string",
  • "format": "string",
  • "frequency": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

TradeFlowService

GetTradeFlowAggregation

Aggregates tradeflow data across multiple dimensions.

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly", "yearly"]. Default value is "monthly". This parameter only applies to the /tradeflows/timeseries endpoint.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

flowDirection
string

This controls whether to group the date by export date/import date. Allowed values are **["export","import"]. Default value is "export". This parameter only applies to the /tradeflows/timeseries endpoint.

loadPortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load port.

loadPortUnlocode
Array of strings

List of five letter UNLOCODEs for load (export) ports to filter on.

loadBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load berth/terminal.

dischargePortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge port.

dischargePortUnlocode
Array of strings

List of five letter UNLOCODEs for discharge (import) ports to filter on.

dischargeBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge berth/terminal.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

loadCountryCode
Array of strings

List of two letter ISO country codes for loading (export) countries to filter on.

dischargeCountryCode
Array of strings

List of two letter ISO country codes for discharge (import) countries to filter on.

loadRegion
Array of strings

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

dischargeRegion
Array of strings

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

status
Array of strings
excludeIntraCountry
boolean

Determines whether to include/exclude intra country voyages. Default is to include.

excludeUnknownDestinations
boolean

Determines whether to include/exclude voyages with unknown destination. Default is to include.

excludeMissingLoadBerth
boolean

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

excludeMissingDischargeBerth
boolean

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv", "json", "xlsx"]. Default is "json".

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

pivotBy
string

Not implemented.

tallFormat
boolean

Not implemented.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["volume","count","ton_mile_calculated","ton_mile_actual","average_haul","average_speed", "volume_times_duration"]. Default is "volume".

parceling
Array of strings

List of parceling statuses to retrieve. Allowed values are: ["include","exclude","only"].

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descending order. Allowed values: ["asc","desc"].

category
string

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "flowDirection": "string",
  • "loadPortId": [
    ],
  • "loadPortUnlocode": [
    ],
  • "loadBerthId": [
    ],
  • "dischargePortId": [
    ],
  • "dischargePortUnlocode": [
    ],
  • "dischargeBerthId": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "loadCountryCode": [
    ],
  • "dischargeCountryCode": [
    ],
  • "loadRegion": [
    ],
  • "dischargeRegion": [
    ],
  • "status": [
    ],
  • "excludeIntraCountry": true,
  • "excludeUnknownDestinations": true,
  • "excludeMissingLoadBerth": true,
  • "excludeMissingDischargeBerth": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "groupBy": "string",
  • "pivotBy": "string",
  • "tallFormat": true,
  • "metric": "string",
  • "parceling": [
    ],
  • "limitGroups": true,
  • "lastNDays": 0,
  • "sort": "string",
  • "category": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTradeFlowHistogram

GetTradeFlowHistogramValues gets trade flow histogram values by grouping.

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly", "yearly"]. Default value is "monthly". This parameter only applies to the /tradeflows/timeseries endpoint.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

flowDirection
string

This controls whether to group the date by export date/import date. Allowed values are **["export","import"]. Default value is "export". This parameter only applies to the /tradeflows/timeseries endpoint.

loadPortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load port.

loadPortUnlocode
Array of strings

List of five letter UNLOCODEs for load (export) ports to filter on.

loadBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load berth/terminal.

dischargePortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge port.

dischargePortUnlocode
Array of strings

List of five letter UNLOCODEs for discharge (import) ports to filter on.

dischargeBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge berth/terminal.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

loadCountryCode
Array of strings

List of two letter ISO country codes for loading (export) countries to filter on.

dischargeCountryCode
Array of strings

List of two letter ISO country codes for discharge (import) countries to filter on.

loadRegion
Array of strings

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

dischargeRegion
Array of strings

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

status
Array of strings
excludeIntraCountry
boolean

Determines whether to include/exclude intra country voyages. Default is to include.

excludeUnknownDestinations
boolean

Determines whether to include/exclude voyages with unknown destination. Default is to include.

excludeMissingLoadBerth
boolean

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

excludeMissingDischargeBerth
boolean

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv", "json", "xlsx"]. Default is "json".

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

pivotBy
string

Not implemented.

tallFormat
boolean

Not implemented.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["volume","count","ton_mile_calculated","ton_mile_actual","average_haul","average_speed", "volume_times_duration"]. Default is "volume".

parceling
Array of strings

List of parceling statuses to retrieve. Allowed values are: ["include","exclude","only"].

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descending order. Allowed values: ["asc","desc"].

category
string

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "flowDirection": "string",
  • "loadPortId": [
    ],
  • "loadPortUnlocode": [
    ],
  • "loadBerthId": [
    ],
  • "dischargePortId": [
    ],
  • "dischargePortUnlocode": [
    ],
  • "dischargeBerthId": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "loadCountryCode": [
    ],
  • "dischargeCountryCode": [
    ],
  • "loadRegion": [
    ],
  • "dischargeRegion": [
    ],
  • "status": [
    ],
  • "excludeIntraCountry": true,
  • "excludeUnknownDestinations": true,
  • "excludeMissingLoadBerth": true,
  • "excludeMissingDischargeBerth": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "groupBy": "string",
  • "pivotBy": "string",
  • "tallFormat": true,
  • "metric": "string",
  • "parceling": [
    ],
  • "limitGroups": true,
  • "lastNDays": 0,
  • "sort": "string",
  • "category": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "groupingVariable": "string",
  • "numberOfGroups": 0,
  • "groups": [
    ]
}

GetTradeFlows

GetVoyages retrieves all the individual voyages for the given filter parameters. Response is paginated, and endpoint accepts a paging parameter to specify which page to return. It is also possible to set the number of voyages to return per query.

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly", "yearly"]. Default value is "monthly". This parameter only applies to the /tradeflows/timeseries endpoint.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

flowDirection
string

This controls whether to group the date by export date/import date. Allowed values are **["export","import"]. Default value is "export". This parameter only applies to the /tradeflows/timeseries endpoint.

loadPortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load port.

loadPortUnlocode
Array of strings

List of five letter UNLOCODEs for load (export) ports to filter on.

loadBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load berth/terminal.

dischargePortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge port.

dischargePortUnlocode
Array of strings

List of five letter UNLOCODEs for discharge (import) ports to filter on.

dischargeBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge berth/terminal.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

loadCountryCode
Array of strings

List of two letter ISO country codes for loading (export) countries to filter on.

dischargeCountryCode
Array of strings

List of two letter ISO country codes for discharge (import) countries to filter on.

loadRegion
Array of strings

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

dischargeRegion
Array of strings

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

status
Array of strings
excludeIntraCountry
boolean

Determines whether to include/exclude intra country voyages. Default is to include.

excludeUnknownDestinations
boolean

Determines whether to include/exclude voyages with unknown destination. Default is to include.

excludeMissingLoadBerth
boolean

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

excludeMissingDischargeBerth
boolean

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv", "json", "xlsx"]. Default is "json".

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

pivotBy
string

Not implemented.

tallFormat
boolean

Not implemented.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["volume","count","ton_mile_calculated","ton_mile_actual","average_haul","average_speed", "volume_times_duration"]. Default is "volume".

parceling
Array of strings

List of parceling statuses to retrieve. Allowed values are: ["include","exclude","only"].

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descending order. Allowed values: ["asc","desc"].

category
string

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "flowDirection": "string",
  • "loadPortId": [
    ],
  • "loadPortUnlocode": [
    ],
  • "loadBerthId": [
    ],
  • "dischargePortId": [
    ],
  • "dischargePortUnlocode": [
    ],
  • "dischargeBerthId": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "loadCountryCode": [
    ],
  • "dischargeCountryCode": [
    ],
  • "loadRegion": [
    ],
  • "dischargeRegion": [
    ],
  • "status": [
    ],
  • "excludeIntraCountry": true,
  • "excludeUnknownDestinations": true,
  • "excludeMissingLoadBerth": true,
  • "excludeMissingDischargeBerth": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "groupBy": "string",
  • "pivotBy": "string",
  • "tallFormat": true,
  • "metric": "string",
  • "parceling": [
    ],
  • "limitGroups": true,
  • "lastNDays": 0,
  • "sort": "string",
  • "category": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextToken": "string",
  • "prevToken": "string",
  • "csv": "string",
  • "xlsx": "string"
}

GetTradeFlowOnTheWater

Gets aggregated trade flow timeseries (on the water) by period.

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly", "yearly"]. Default value is "monthly". This parameter only applies to the /tradeflows/timeseries endpoint.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

flowDirection
string

This controls whether to group the date by export date/import date. Allowed values are **["export","import"]. Default value is "export". This parameter only applies to the /tradeflows/timeseries endpoint.

loadPortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load port.

loadPortUnlocode
Array of strings

List of five letter UNLOCODEs for load (export) ports to filter on.

loadBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load berth/terminal.

dischargePortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge port.

dischargePortUnlocode
Array of strings

List of five letter UNLOCODEs for discharge (import) ports to filter on.

dischargeBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge berth/terminal.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

loadCountryCode
Array of strings

List of two letter ISO country codes for loading (export) countries to filter on.

dischargeCountryCode
Array of strings

List of two letter ISO country codes for discharge (import) countries to filter on.

loadRegion
Array of strings

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

dischargeRegion
Array of strings

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

status
Array of strings
excludeIntraCountry
boolean

Determines whether to include/exclude intra country voyages. Default is to include.

excludeUnknownDestinations
boolean

Determines whether to include/exclude voyages with unknown destination. Default is to include.

excludeMissingLoadBerth
boolean

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

excludeMissingDischargeBerth
boolean

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv", "json", "xlsx"]. Default is "json".

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

pivotBy
string

Not implemented.

tallFormat
boolean

Not implemented.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["volume","count","ton_mile_calculated","ton_mile_actual","average_haul","average_speed", "volume_times_duration"]. Default is "volume".

parceling
Array of strings

List of parceling statuses to retrieve. Allowed values are: ["include","exclude","only"].

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descending order. Allowed values: ["asc","desc"].

category
string

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "flowDirection": "string",
  • "loadPortId": [
    ],
  • "loadPortUnlocode": [
    ],
  • "loadBerthId": [
    ],
  • "dischargePortId": [
    ],
  • "dischargePortUnlocode": [
    ],
  • "dischargeBerthId": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "loadCountryCode": [
    ],
  • "dischargeCountryCode": [
    ],
  • "loadRegion": [
    ],
  • "dischargeRegion": [
    ],
  • "status": [
    ],
  • "excludeIntraCountry": true,
  • "excludeUnknownDestinations": true,
  • "excludeMissingLoadBerth": true,
  • "excludeMissingDischargeBerth": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "groupBy": "string",
  • "pivotBy": "string",
  • "tallFormat": true,
  • "metric": "string",
  • "parceling": [
    ],
  • "limitGroups": true,
  • "lastNDays": 0,
  • "sort": "string",
  • "category": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetTradeFlowTimeseries

Gets aggregated trade flow timeseries by period.

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly", "yearly"]. Default value is "monthly". This parameter only applies to the /tradeflows/timeseries endpoint.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

flowDirection
string

This controls whether to group the date by export date/import date. Allowed values are **["export","import"]. Default value is "export". This parameter only applies to the /tradeflows/timeseries endpoint.

loadPortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load port.

loadPortUnlocode
Array of strings

List of five letter UNLOCODEs for load (export) ports to filter on.

loadBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load berth/terminal.

dischargePortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge port.

dischargePortUnlocode
Array of strings

List of five letter UNLOCODEs for discharge (import) ports to filter on.

dischargeBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge berth/terminal.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

loadCountryCode
Array of strings

List of two letter ISO country codes for loading (export) countries to filter on.

dischargeCountryCode
Array of strings

List of two letter ISO country codes for discharge (import) countries to filter on.

loadRegion
Array of strings

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

dischargeRegion
Array of strings

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

status
Array of strings
excludeIntraCountry
boolean

Determines whether to include/exclude intra country voyages. Default is to include.

excludeUnknownDestinations
boolean

Determines whether to include/exclude voyages with unknown destination. Default is to include.

excludeMissingLoadBerth
boolean

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

excludeMissingDischargeBerth
boolean

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv", "json", "xlsx"]. Default is "json".

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

pivotBy
string

Not implemented.

tallFormat
boolean

Not implemented.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["volume","count","ton_mile_calculated","ton_mile_actual","average_haul","average_speed", "volume_times_duration"]. Default is "volume".

parceling
Array of strings

List of parceling statuses to retrieve. Allowed values are: ["include","exclude","only"].

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descending order. Allowed values: ["asc","desc"].

category
string

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "flowDirection": "string",
  • "loadPortId": [
    ],
  • "loadPortUnlocode": [
    ],
  • "loadBerthId": [
    ],
  • "dischargePortId": [
    ],
  • "dischargePortUnlocode": [
    ],
  • "dischargeBerthId": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "loadCountryCode": [
    ],
  • "dischargeCountryCode": [
    ],
  • "loadRegion": [
    ],
  • "dischargeRegion": [
    ],
  • "status": [
    ],
  • "excludeIntraCountry": true,
  • "excludeUnknownDestinations": true,
  • "excludeMissingLoadBerth": true,
  • "excludeMissingDischargeBerth": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "groupBy": "string",
  • "pivotBy": "string",
  • "tallFormat": true,
  • "metric": "string",
  • "parceling": [
    ],
  • "limitGroups": true,
  • "lastNDays": 0,
  • "sort": "string",
  • "category": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "timeseries": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

GetLocationVolume

GetLocationVolume gets location (port/berth/country/region) flow stats for the given filter parameters

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly", "yearly"]. Default value is "monthly". This parameter only applies to the /tradeflows/timeseries endpoint.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

flowDirection
string

This controls whether to group the date by export date/import date. Allowed values are **["export","import"]. Default value is "export". This parameter only applies to the /tradeflows/timeseries endpoint.

loadPortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load port.

loadPortUnlocode
Array of strings

List of five letter UNLOCODEs for load (export) ports to filter on.

loadBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load berth/terminal.

dischargePortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge port.

dischargePortUnlocode
Array of strings

List of five letter UNLOCODEs for discharge (import) ports to filter on.

dischargeBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge berth/terminal.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

loadCountryCode
Array of strings

List of two letter ISO country codes for loading (export) countries to filter on.

dischargeCountryCode
Array of strings

List of two letter ISO country codes for discharge (import) countries to filter on.

loadRegion
Array of strings

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

dischargeRegion
Array of strings

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

status
Array of strings
excludeIntraCountry
boolean

Determines whether to include/exclude intra country voyages. Default is to include.

excludeUnknownDestinations
boolean

Determines whether to include/exclude voyages with unknown destination. Default is to include.

excludeMissingLoadBerth
boolean

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

excludeMissingDischargeBerth
boolean

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv", "json", "xlsx"]. Default is "json".

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

pivotBy
string

Not implemented.

tallFormat
boolean

Not implemented.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["volume","count","ton_mile_calculated","ton_mile_actual","average_haul","average_speed", "volume_times_duration"]. Default is "volume".

parceling
Array of strings

List of parceling statuses to retrieve. Allowed values are: ["include","exclude","only"].

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descending order. Allowed values: ["asc","desc"].

category
string

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "flowDirection": "string",
  • "loadPortId": [
    ],
  • "loadPortUnlocode": [
    ],
  • "loadBerthId": [
    ],
  • "dischargePortId": [
    ],
  • "dischargePortUnlocode": [
    ],
  • "dischargeBerthId": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "loadCountryCode": [
    ],
  • "dischargeCountryCode": [
    ],
  • "loadRegion": [
    ],
  • "dischargeRegion": [
    ],
  • "status": [
    ],
  • "excludeIntraCountry": true,
  • "excludeUnknownDestinations": true,
  • "excludeMissingLoadBerth": true,
  • "excludeMissingDischargeBerth": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "groupBy": "string",
  • "pivotBy": "string",
  • "tallFormat": true,
  • "metric": "string",
  • "parceling": [
    ],
  • "limitGroups": true,
  • "lastNDays": 0,
  • "sort": "string",
  • "category": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

GetTradeLaneMetrics

GetTradeflowModelVoyage gets trade flow model voyage values by grouping

Request Body schema: application/json
frequency
string

Frequency determines the granularity/period grouping of the timeseries. Allowed values are: ["daily", "weekly", "monthly","quarterly", "yearly"]. Default value is "monthly". This parameter only applies to the /tradeflows/timeseries endpoint.

commodity
Array of strings

List of commodities to get data for (get a list of all commodities from /entities/commodities).

commodityGroup
Array of strings

List of commodity groups to get data for (get a list of all commodity groups from /entities/commodities).

flowDirection
string

This controls whether to group the date by export date/import date. Allowed values are **["export","import"]. Default value is "export". This parameter only applies to the /tradeflows/timeseries endpoint.

loadPortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load port.

loadPortUnlocode
Array of strings

List of five letter UNLOCODEs for load (export) ports to filter on.

loadBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the load berth/terminal.

dischargePortId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge port.

dischargePortUnlocode
Array of strings

List of five letter UNLOCODEs for discharge (import) ports to filter on.

dischargeBerthId
Array of integers <int32> [ items <int32 > ]

Oceanbolt database identifier of the discharge berth/terminal.

startDate
string

The UTC start date of the date filter.

endDate
string

The UTC end date of the date filter.

loadCountryCode
Array of strings

List of two letter ISO country codes for loading (export) countries to filter on.

dischargeCountryCode
Array of strings

List of two letter ISO country codes for discharge (import) countries to filter on.

loadRegion
Array of strings

List of loading regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

dischargeRegion
Array of strings

List of discharge regions to filter on. Allowed values can be obtained from the /entities/regions endpoint.

status
Array of strings
excludeIntraCountry
boolean

Determines whether to include/exclude intra country voyages. Default is to include.

excludeUnknownDestinations
boolean

Determines whether to include/exclude voyages with unknown destination. Default is to include.

excludeMissingLoadBerth
boolean

Determines whether to include/exclude voyages with that have a missing load_berth_id. Default is to include.

excludeMissingDischargeBerth
boolean

Determines whether to include/exclude voyages with that have a missing discharge_berth_id. Default is to include.

nextToken
string

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

maxResults
integer <int32>

An optional limit for the number of resources returned in a single call.

format
string

The return format of the data ["csv", "json", "xlsx"]. Default is "json".

groupBy
string

Determines the grouping of the timeseries data. This parameter only applies to the /tradeflows/timeseries endpoint.

pivotBy
string

Not implemented.

tallFormat
boolean

Not implemented.

metric
string

The metric to retrieve for timeseries aggregations. Allowed values: ["volume","count","ton_mile_calculated","ton_mile_actual","average_haul","average_speed", "volume_times_duration"]. Default is "volume".

parceling
Array of strings

List of parceling statuses to retrieve. Allowed values are: ["include","exclude","only"].

limitGroups
boolean

Flag to indicate whether grouped timeseries should be limited to top N entries. If the parameter is present, the endpoint will only return the top N groups, and the remaining entries will be grouped into others.

lastNDays
integer <int32>

Short hand parameter for quickly getting data for the last N days. Cannot be supplied along either start_date or end_date.

sort
string

Specifies whether results should be sorted in ascending or descending order. Allowed values: ["asc","desc"].

category
string

Specifies the base category for aggregation queries. This parameter only has effect on the GetTradeFlowAggregation method (REST endpoint: /tradeflows/aggregation).

object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "flowDirection": "string",
  • "loadPortId": [
    ],
  • "loadPortUnlocode": [
    ],
  • "loadBerthId": [
    ],
  • "dischargePortId": [
    ],
  • "dischargePortUnlocode": [
    ],
  • "dischargeBerthId": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "loadCountryCode": [
    ],
  • "dischargeCountryCode": [
    ],
  • "loadRegion": [
    ],
  • "dischargeRegion": [
    ],
  • "status": [
    ],
  • "excludeIntraCountry": true,
  • "excludeUnknownDestinations": true,
  • "excludeMissingLoadBerth": true,
  • "excludeMissingDischargeBerth": true,
  • "nextToken": "string",
  • "maxResults": 0,
  • "format": "string",
  • "groupBy": "string",
  • "pivotBy": "string",
  • "tallFormat": true,
  • "metric": "string",
  • "parceling": [
    ],
  • "limitGroups": true,
  • "lastNDays": 0,
  • "sort": "string",
  • "category": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "groupingVariable": "string",
  • "numberOfGroups": 0,
  • "tradeLaneMetrics": [
    ]
}

VesselService

GetAisSummary

Generates summary data regarding AIS received during a specific requested period for a single vessel

Request Body schema: application/json
imo
integer <int64> (IMO number of the vessel)
startTime
string <date-time> (Start time for the AIS summary request)
endTime
string <date-time> (End time for the AIS summary request)
resolution
string (GetAisSummaryRequestResolution)
Default: "RESOLUTION"
Enum: "RESOLUTION" "DAILY" "HOURLY" "FULL"

Responses

Request samples

Content type
application/json
{
  • "imo": 0,
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "resolution": "RESOLUTION"
}

Response samples

Content type
application/json
{
  • "distanceTraveledNm": 0,
  • "averageSpeedKnots": 0,
  • "numberOfPositions": 0,
  • "initialTimestampForPeriod": "2019-08-24T14:15:22Z",
  • "lastTimestampForPeriod": "2019-08-24T14:15:22Z",
  • "requestedStartTime": "2019-08-24T14:15:22Z",
  • "requestedEndTime": "2019-08-24T14:15:22Z"
}

ListDarkPeriodEvents

Fetches ais based dark period events for a single vessel. A dark period event, is where a vessel has not transmitted AIS data for a period greater than 6 hours.

Request Body schema: application/json
imo
Array of integers <int32> (included vessel imos) [ items <int32 > ]
startDate
string
endDate
string
format
string (response format (default is json, supported: csv, xlsx))

Responses

Request samples

Content type
application/json
{
  • "imo": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "format": "string"
}

Response samples

Content type
application/json
{
  • "darkPeriodEvents": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

ListVessels

Vessels gets a list of vessels for the given filter parameters

Request Body schema: application/json
eta
Array of strings (before,after on the eta columns)
loadRegion
Array of strings (included load regions)
loadCountry
Array of strings (included load countries)
loadPort
Array of strings (included load ports)
destinationRegion
Array of strings (included discharge regions)
destinationCountry
Array of strings (included discharge countries)
destinationPort
Array of strings (included discharge ports)
destinationUnlocode
Array of strings (included discharge port unlocodes)
cargoStatus
Array of strings (included cargo states)
ladenStatus
Array of strings (included laden states)
ladenStatusDraught
Array of strings (included laden states)
speed
Array of numbers <double> (min,max on the speed column) [ items <double > ]
draught
Array of numbers <double> (min,max on the draught column) [ items <double > ]
excludeUnknownDestination
boolean (include rows where destination_country is blank)
group
string (group by filter parameter)
range
string (range value for timeseries request (ex: month/monthly, week/weekly))
flowDate
string (flow date (of load/discharge) for timeseries request)
commodity
Array of strings (included commodity values)
commodityGroup
Array of strings (included commodity values)
zoneId
Array of integers <int64> (included zone ids) [ items <int64 > ]
portId
Array of integers <int64> (included port ids) [ items <int64 > ]
anchorageId
Array of integers <int64> (included anchorage ids) [ items <int64 > ]
berthId
Array of integers <int64> (included berth ids) [ items <int64 > ]
shipyardId
Array of integers <int64> (included shipyard ids) [ items <int64 > ]
direction
Array of strings (included directions)
portStatus
Array of strings (included port_statuses)
limit
integer <int64>
hoursSinceLast
integer <int64> (parameter for aisquality request)
format
string (response format (default is json, supported csv))
object (filtersVesselFilter)

Responses

Request samples

Content type
application/json
{
  • "eta": [
    ],
  • "loadRegion": [
    ],
  • "loadCountry": [
    ],
  • "loadPort": [
    ],
  • "destinationRegion": [
    ],
  • "destinationCountry": [
    ],
  • "destinationPort": [
    ],
  • "destinationUnlocode": [
    ],
  • "cargoStatus": [
    ],
  • "ladenStatus": [
    ],
  • "ladenStatusDraught": [
    ],
  • "speed": [
    ],
  • "draught": [
    ],
  • "excludeUnknownDestination": true,
  • "group": "string",
  • "range": "string",
  • "flowDate": "string",
  • "commodity": [
    ],
  • "commodityGroup": [
    ],
  • "zoneId": [
    ],
  • "portId": [
    ],
  • "anchorageId": [
    ],
  • "berthId": [
    ],
  • "shipyardId": [
    ],
  • "direction": [
    ],
  • "portStatus": [
    ],
  • "limit": 0,
  • "hoursSinceLast": 0,
  • "format": "string",
  • "vesselFilter": {
    }
}

Response samples

Content type
application/json
{
  • "vessels": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

ListStoppageEvents

Fetches ais based stoppage events for a single vessel

Request Body schema: application/json
imo
Array of integers <int32> (included vessel imos) [ items <int32 > ]
startDate
string
endDate
string
format
string (response format (default is json, supported: csv, xlsx))

Responses

Request samples

Content type
application/json
{
  • "imo": [
    ],
  • "startDate": "string",
  • "endDate": "string",
  • "format": "string"
}

Response samples

Content type
application/json
{
  • "stoppageEvents": [
    ],
  • "csv": "string",
  • "xlsx": "string"
}

VesselStateService

GetVesselStates

Returns historical vessel states for the given dates and imo numbers supplied.

Request Body schema: application/json
imo
Array of integers <int32> (included vessel imos) [ items <int32 > ]
startDate
string
endDate
string

Responses

Request samples

Content type
application/json
{
  • "imo": [
    ],
  • "startDate": "string",
  • "endDate": "string"
}

Response samples

Content type
application/json
{
  • "vesselStates": [
    ]
}

GetVesselStatesForDate

Returns all historical states for the entire fleet for a single date.

Request Body schema: application/json
date
string

Responses

Request samples

Content type
application/json
{
  • "date": "string"
}

Response samples

Content type
application/json
{
  • "vesselStates": [
    ]
}