ABB Voyage Configuration API
API docs by Redocly

Voyage Configuration API (1.549)

Download OpenAPI specification:Download

ABB customer service: support.voyageoptimization@abb.com URL: https://new.abb.com/marine

Introduction

By using Voyage configuration API, customer can access the voyage optimization services offered by ABB.

Rate Limiting

This API implements rate limiting to ensure fair usage and optimal performance for all customers.

  • Rate Limit: 20 requests per second per endpoint
  • Rate Limit Headers: Each response includes headers indicating your current rate limit status

When you approach or exceed the rate limit, you'll receive appropriate HTTP status codes and should implement exponential backoff in your retry logic.

Postman Collection

To help you get started quickly with the API, we provide a ready-to-use Postman collection that includes all endpoints with sample requests.

Download: Voyage Configuration API Postman Collection

The collection includes:

  • Pre-configured authentication setup
  • Sample requests for all endpoints (including Product API)

Authentication

Get a token

Get token for use in HTTP requests.

Request Body schema: application/x-www-form-urlencoded
client_id
required
string

Client ID as provided by ABB

client_secret
required
string

Client secret as provided by ABB

scope
required
string
Default: "https://genb2crs03euwprod.onmicrosoft.com/rs.iam/region"

The scope the credentials should belong to.

grant_type
required
string
Default: "client_credentials"

The type of token request

Responses

Response Schema: application/json
access_token
required
string

The token used for authentication in API requests

expires_in
required
integer

The duration (in seconds) for which the token remains valid

token_type
required
string
Default: "Bearer"

The type of token

scope
required
string

A space-delimited list of the scopes of the token

resource
string

Resource associated to the token

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "token_type": "Bearer",
  • "scope": "string",
  • "resource": "string"
}

Route Advice Report

This endpoint can be used to convert a precalculated route into route advice. Using this endpoint, it is possible to generate route advices in PDF, RTZ and CSV format which can easily be shared with the crew and other stakeholders. The route advice PDF is created in standard ABB designed format, is always less than 2MB in file size, is always white-labeled and contain the logo provided to ABB during on-boarding of the customer. Customer needs to provide the logo during onboarding. Sample payload and output files can be downloaded from here: PDF | RTZ | CSV

This endpoint uses the correlation IDs of routes calculated by the Routing API to generate reports. The reports will be announced on the WebSocket connection of the Notification API and made available on the Product API.

Route Calculation Requirements:

To successfully generate route advice PDFs, the following parameters must be provided during the route calculation request sent to the Vessel Routing API:

  • Provide vessel name (vesselParameters.vesselName) in the route calculation request
  • Provide cargo load condition (vesselParameters.cargo.loadCondition) in the route calculation request
  • If these parameters are missing, the report generation will fail and the status will be marked as Failed (in Product API). Error messages will be included in the response from the Get Product Status endpoint of Product API. Alternatively, if connected to the Notification API websocket, error messages will be included in the notification message received once the report generation has failed

Image Generation Requirements:

  • Provide meaningful waypoint names (points[i].properties.name) in the route calculation request. At least waypoint names should be provided for departure, destination and any intermediate stops.
  • Waypoint names will be truncated in the generated images if they are too long
  • If no waypoint names are provided or if images cannot be generated for any reason, warning messages will be included in the response from the Get Product Status endpoint of Product API. Alternatively, if connected to the Notification API websocket, warnings will be included in the notification message received once the report has been generated

Text Display Guidelines for PDF Reports:

To ensure optimal PDF report generation and quality, the following text fields are truncated in PDF reports when they exceed the display limit:

  • Voyage names (if longer than 2 lines)
  • Destination and port names provided during route calculation (if longer than 60 characters)

Note: Additional display guidelines for specific fields (such as voyage name, comments, etc.) are documented in the individual field descriptions.

Create route advice report

Allows clients to create a new route advice report.

Authorizations:
(BearerABBIdentity)
Request Body schema: application/json
required
routingCorrelationId
required
string

The identifier that will be used to fetch the result of the pre-calculated route from the Vessel Routing API

updateType
required
string
Enum: "RouteAdvice" "InitialAdvice" "DailyAdvice"

Type of route advice. Indicates the category of routing advice being generated. This value determines the title displayed in the report to identify whether the advice is one-off, initial, or part of a recurring daily update.

Update Type Report Header Title Description
RouteAdvice Route Advice Can be used for one-off route advice recommendation.
InitialAdvice Initial Route Advice Can be used for the first route advice created for a voyage.
DailyAdvice Daily Route Advice Can be used for creating daily route advice updates for a voyage.
required
object (VoyageInfo)

Information about the voyage this route is for.

routeSourceType
required
string
Value: "PreCalculated"

Used to indicate that the route has already been calculated.

customerReferenceId
string (CustomerReferenceId) <= 20 characters ^[a-zA-Z0-9]+$

This field can be used to separate products. For example, integrators might use this to separate their customers. They can use this ID to filter products when calling Product API.

previousReportCorrelationId
string

The identifier of the previous route advice report. This can be used to reference the older report and its contents.

Usage Guidelines:

  • When previousReportCorrelationId is provided, the system calculates relevant changes from the older advice
  • Changes (such as change in ETA) are included in the new route advice report
  • If the provided ID is invalid, warning messages will be included in the response from the Get Product Status endpoint of Product API. Alternatively, if connected to the Notification API websocket, warnings will be included in the notification message received once the report has been generated

Responses

Request samples

Content type
application/json
{
  • "routingCorrelationId": "K4w-THf4DoEERsg=",
  • "customerReferenceId": "123456789",
  • "routeSourceType": "PreCalculated",
  • "updateType": "RouteAdvice",
  • "previousReportCorrelationId": "055ee7a9-b24c-4f09-9be3-6d09291a6814",
  • "voyageInfo": {
    }
}

Response samples

Content type
application/json
{
  • "correlationId": "b7f43e1a-076a-4e46-a6a8-04ff46f11d70"
}

Route Comparison Report

This endpoint can be used to convert up to 3 precalculated routes into route comparison PDF. Using this endpoint, it is possible to generate route comparison reports in PDF format which can easily be shared with the crew and other stakeholders. The route comparison PDF is created in standard ABB designed format, is always less than 2MB in file size, is always white-labeled and contain the logo provided to ABB during on-boarding of the customer. Customer needs to provide the logo during onboarding. Sample payload and output files can be downloaded from here: PDF

This endpoint uses the correlation IDs of routes calculated by the Routing API to generate reports. The reports will be announced on the WebSocket connection of the Notification API and made available on the Product API.

Route Calculation Requirements:

To successfully generate route comparison PDFs, the following parameters must be provided during the route calculation request sent to the Vessel Routing API:

  • Provide vessel name (vesselParameters.vesselName) in the route calculation request
  • Provide cargo load condition (vesselParameters.cargo.loadCondition) in the route calculation request
  • If these parameters are missing, the report generation will fail and the status will be marked as Failed (in Product API). Error messages will be included in the response from the Get Product Status endpoint of Product API. Alternatively, if connected to the Notification API websocket, error messages will be included in the notification message received once the report generation has failed

Image Generation Requirements:

  • Provide meaningful waypoint names (points[i].properties.name) in the route calculation request. At least waypoint names should be provided for departure, destination and any intermediate stops.
  • Waypoint names will be truncated in the generated images if they are too long
  • If no waypoint names are provided or if images cannot be generated for any reason, warning messages will be included in the response from the Get Product Status endpoint of Product API. Alternatively, if connected to the Notification API websocket, warnings will be included in the notification message received once the report has been generated

Text Display Guidelines for PDF Reports:

To ensure optimal PDF report generation and quality, the following text fields are truncated in PDF reports when they exceed the display limit:

  • Voyage names and route names (if longer than 2 lines)
  • Destination and port names provided during route calculation (if longer than 2 lines)

Note: Additional display guidelines for specific fields (such as comments, route names, etc.) are documented in the individual field descriptions.

Create route comparison report

Allows clients to create a new route comparison report.

Authorizations:
(BearerABBIdentity)
Request Body schema: application/json
required
required
Array of objects (RouteItem) [ 1 .. 3 ] items

Information about the routes to compare.

required
object (schemas-VoyageInfo)

Information about the voyage this route is for.

customerReferenceId
string (CustomerReferenceId) <= 20 characters ^[a-zA-Z0-9]+$

This field can be used to separate products. For example, integrators might use this to separate their customers. They can use this ID to filter products when calling Product API.

includeCosts
boolean
Default: true

Determines if costs are added to the report tables.

includeFuelConsumption
boolean
Default: true

Determines if fuel consumption values are added to the report tables.

keyWeatherEvents
Array of strings <RFC 3339 (UTC)> <= 2 items unique [ items <RFC 3339 (UTC) > ]

Timestamps for key weather events to include in the report.

Usage Guidelines:

  • These timestamps will generate weather images in the PDF, including vessel positions at those moments
  • Time range: Weather images can be plotted from 1 year ago up to 7 days in the future

Responses

Request samples

Content type
application/json
{
  • "routes": [
    ],
  • "customerReferenceId": "123456789",
  • "includeCosts": true,
  • "includeFuelConsumption": true,
  • "keyWeatherEvents": [
    ],
  • "voyageInfo": {
    }
}

Response samples

Content type
application/json
{
  • "correlationId": "b7f43e1a-076a-4e46-a6a8-04ff46f11d70"
}

Notification API

The Notification API is used to get immediate notifications when product and reports from the Voyage Configuration API have been created.

Notification API

Product API

The Product API is used to download the products and reports generated by the Voyage Configuration API.

Product API