ABB Product API
API docs by Redocly

Product API (1.798)

Download OpenAPI specification:Download

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

Introduction

Product API can be used by Routeguard and Voyage Configuration API customers for accessing products like the Route Advice Report and Route Comparison Report.

For Routeguard customers:

  • RouteGuard customers can get all the route advices that are sent to their vessels by ABB's route analysts in PDF, RTZ, CSV and JSON format by calling this API.
  • By using the Get Last Sent Product endpoint, RouteGuard customers can get the last sent route advice for any vessel.

For Voyage Configuration API customer:

  • Download all the products that are created using Voyage Configuration API
  • Search all products for any vessel in any time range
  • Get the latest status of any product using the CorrelationID returned by Voyage Configuration 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"
}

Products

Download Product

Authorizations:
(BearerABBIdentity)
path Parameters
correlationId
required
string <uuid> (CorrelationId)
Example: abcd1234-0000-1111-2222-abcdef123456

This is the unique ID for a product. The correlation ID is the same as the 'ABB REFERENCE NR' that is available in the footer of route advice and route comparison PDF reports. The correlation ID is generated when a new product is created through the Create Route Advice or Create Route Comparison Report endpoint. The correlation ID is also generated every time the Route Calculation Scheduler creates a new Route Calculation.

filename
required
string
Example: RouteAdvice.pdf

The file name with its extension.

Responses

Response Schema:
One of
correlationId
required
string <uuid> (CorrelationId)

Report's correlation ID generated by ABB. This ID can be used to fetch the products from Product API.

requestId
required
string

For ABB internal use only.

version
required
string

The version of the service this response was generated from.

status
required
string
Value: "Success"

The calculation succeeded.

creationDate
required
string <RFC 3339 (UTC)>

Voyage orchestration result creation date

origin
required
string
Enum: "VoyageConfigurationAPI" "RouteGuardConsultancy"

Specifies the origin that triggered the creation of the report. This indicates whether the report was generated through RouteGuard Consultancy or Voyage Configuration API.

required
object (PreCalculatedRequest)
required
Array of objects (RouteResults)

The resulting routes, currently is always size of one.

Response samples

Content type
Example
{
  • "correlationId": "abcd1234-0000-1111-2222-abcdef123456",
  • "requestId": "2613af67-b901-4e53-b13e-ebf18d9a1d2e",
  • "version": "$VERSION",
  • "origin": "VoyageConfigurationAPI",
  • "status": "Success",
  • "creationDate": "2023-06-05T07:00:00.000Z",
  • "request": {
    },
  • "routeResults": [
    ]
}

Get Last Sent Product Location

Authorizations:
(BearerABBIdentity)
query Parameters
imo
required
string
Example: imo=1234567

The vessel's imo associated with the product.

productName
string (productName)
Enum: "RouteAdvice" "RouteComparison" "RouteCalculation"
Example: productName=RouteAdvice

The product's name.

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

Customer Reference Id used to generate this product. This will be ignored if ReferenceId is present in the token.

Responses

Response Schema: application/json
correlationId
string <uuid> (CorrelationId)

This is the unique ID for a product. The correlation ID is the same as the 'ABB REFERENCE NR' that is available in the footer of route advice and route comparison PDF reports. The correlation ID is generated when a new product is created through the Create Route Advice or Create Route Comparison Report endpoint. The correlation ID is also generated every time the Route Calculation Scheduler creates a new Route Calculation.

productName
string (productName)
Enum: "RouteAdvice" "RouteComparison" "RouteCalculation"

The product's name.

statusTimestamp
string <RFC 3339 (UTC)>

The timestamp of product's delivery status.

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

Customer Reference Id used to generate this product. This will be ignored if ReferenceId is present in the token.

origin
string
Enum: "VoyageConfigurationAPI" "RouteGuardConsultancy"

Specifies the origin that triggered the creation of the report. This indicates whether the report was generated through RouteGuard Consultancy or Voyage Configuration API.

voyageInfoId
string

Unique ID specific to the voyage. For RouteGuard customers, this is the unique RouteGuard voyage ID.

status
string

Indicates that the product has been delivered. Either it was downloaded from the product API or delivered through an alternative method.

Value: "Sent"
Array of objects (Deliverables)
warnings
Array of strings (Warnings)
creationDate
string <RFC 3339 (UTC)>

The timestamp when the product was created.

Response samples

Content type
application/json
{
  • "correlationId": "abcd1234-0000-1111-2222-abcdef123456",
  • "productName": "RouteAdvice",
  • "statusTimestamp": "2024-02-05T00:00:00.000Z",
  • "customerReferenceId": "123456789",
  • "origin": "RouteGuardConsultancy",
  • "voyageInfoId": "voyage-1234",
  • "status": "Sent",
  • "deliverables": [
    ],
  • "warnings": [
    ],
  • "creationDate": "2024-02-05T00:00:00.000Z"
}

Search Products Location

Authorizations:
(BearerABBIdentity)
query Parameters
imo
required
string
Example: imo=1234567

The vessel's imo associated with the product. Required if routeCalculationScheduleId is not provided.

from
required
string <date (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ)>
Example: from=2024-02-05T00:00:00Z

Date & Time from which the data is requested. Required if correlationId is not provided. For successful statuses (New, Announced, Sent), filters by creation date. For failed status, filters by failure date. Required if routeCalculationScheduleId is not provided.

to
required
string <date (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ)>
Example: to=2024-02-05T00:00:00Z

Date & Time until which the data is requested. For successful statuses (New, Announced, Sent), filters by creation date. For failed status, filters by failure date.

productName
string or null
Enum: "RouteAdvice" "RouteComparison" "RouteCalculation"
Example: productName=RouteAdvice

The product's name.

status
string or null
Default: "All"
Enum: "All" "New" "Announced" "Sent" "Failed"
customerReferenceId
string (CustomerReferenceId) <= 20 characters ^[a-zA-Z0-9]+$
Example: customerReferenceId=123456789

Customer Reference Id used to generate this product. This will be ignored if ReferenceId is present in the token.

voyageInfoId
string

Unique ID specific to the voyage. For RouteGuard customers, this is the unique RouteGuard voyage ID.

routeCalculationScheduleId
string
Example: routeCalculationScheduleId=b7f43e1a-076a-4e46-a6a8-04ff46f11d70

Route calculation schedule unique identifier. If provided, no other parameters required.

Responses

Response Schema: application/json
Array
One of
correlationId
string <uuid> (CorrelationId)

This is the unique ID for a product. The correlation ID is the same as the 'ABB REFERENCE NR' that is available in the footer of route advice and route comparison PDF reports. The correlation ID is generated when a new product is created through the Create Route Advice or Create Route Comparison Report endpoint. The correlation ID is also generated every time the Route Calculation Scheduler creates a new Route Calculation.

productName
string (productName)
Enum: "RouteAdvice" "RouteComparison" "RouteCalculation"

The product's name.

statusTimestamp
string <RFC 3339 (UTC)>

The timestamp of product's delivery status.

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

Customer Reference Id used to generate this product. This will be ignored if ReferenceId is present in the token.

origin
string
Value: "VoyageConfigurationAPI"

Specifies the origin that triggered the creation of the report. This indicates whether the report was generated through RouteGuard Consultancy or Voyage Configuration API.

voyageInfoId
string

Unique ID specific to the voyage. For RouteGuard customers, this is the unique RouteGuard voyage ID.

status
string

Status in which the product has been created but was not announced to the customer.

Value: "New"
Array of objects (Deliverables)
warnings
Array of strings (Warnings)
creationDate
string <RFC 3339 (UTC)>

The timestamp when the product was created.

Response samples

Content type
application/json
[
  • {
    }
]

Get Product Status

Authorizations:
(BearerABBIdentity)
path Parameters
correlationId
required
string <uuid> (CorrelationId)
Example: abcd1234-0000-1111-2222-abcdef123456

This is the unique ID for a product. The correlation ID is the same as the 'ABB REFERENCE NR' that is available in the footer of route advice and route comparison PDF reports. The correlation ID is generated when a new product is created through the Create Route Advice or Create Route Comparison Report endpoint. The correlation ID is also generated every time the Route Calculation Scheduler creates a new Route Calculation.

Responses

Response Schema: application/json
One of
correlationId
string <uuid> (CorrelationId)

This is the unique ID for a product. The correlation ID is the same as the 'ABB REFERENCE NR' that is available in the footer of route advice and route comparison PDF reports. The correlation ID is generated when a new product is created through the Create Route Advice or Create Route Comparison Report endpoint. The correlation ID is also generated every time the Route Calculation Scheduler creates a new Route Calculation.

productName
string (productName)
Enum: "RouteAdvice" "RouteComparison" "RouteCalculation"

The product's name.

statusTimestamp
string <RFC 3339 (UTC)>

The timestamp of product's delivery status.

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

Customer Reference Id used to generate this product. This will be ignored if ReferenceId is present in the token.

origin
string
Value: "VoyageConfigurationAPI"

Specifies the origin that triggered the creation of the report. This indicates whether the report was generated through RouteGuard Consultancy or Voyage Configuration API.

voyageInfoId
string

Unique ID specific to the voyage. For RouteGuard customers, this is the unique RouteGuard voyage ID.

status
string
Value: "InProgress"

Status in which the product is being generated.

Response samples

Content type
application/json
Example
{
  • "correlationId": "abcd1234-0000-1111-2222-abcdef123456",
  • "productName": "RouteAdvice",
  • "statusTimestamp": "2024-02-05T00:00:00.000Z",
  • "customerReferenceId": "123456789",
  • "origin": "VoyageConfigurationAPI",
  • "voyageInfoId": "voyage-1234",
  • "status": "InProgress"
}

Voyage Configuration API

The Product API contains the routes, route advices and comparison reports created by the Voyage Configuration API

Voyage Configuration API

Notification API

The Notification API will provide immediate notifications when a product or report has been generated.

Notification API