ABB Weather Factor API
API docs by Redocly

Weather Factor API (1.212.0)

Download OpenAPI specification:Download

ABB customer service: support.voyageoptimization@abb.com URL: https://new.abb.com/marine/systems-and-solutions/digital/routing-services

Introduction

With ABB Weather Factor, traders can more accurately determine the voyage costs upfront by using advanced analytics.

ABB Weather Factor uses digital twin models with 20 years of verified weather and ocean data to create numerous voyage simulations, which results in a complete statistical assessment of voyage costs and emissions.

Getting started

The authorization of the WeatherFactor API follows a standard "2-legged OAuth" approach. The client_id and client_secret provided by ABB can be used to fetch an access_token by making an authentication POST request. The access_token is only valid for a limited time (24 hours), after expiration a new access_token must be requested. The access_token can be used as a Bearer authorization header to access the Weather Factor API.

With authorization, clients are able to make POST request towards the Weather Factor API. Within the body of the WeatherFactor request, clients can specify:

  • Destination & departure
  • Estimated time of departure and instructed speed
  • Vessel parameters & safety margins
  • Vessel digital twin particulars

If a successful request is made, numerous voyage simulations are performed based on 20 years of verified weather and ocean data. The outcomes returned will be a complete statistical assessment of voyage cost and emission probabilities.

Tokens

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

grant_type
required
string
Default: "client_credentials"

The type of token request

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

The scope the credentials should belong to.

Responses

Response Schema: application/json
access_token
required
string

The token that should be used in all requests to the Weather Factor API

expires_in
required
integer

The amount of time the token is valid [ s ]

scope
required
string

A space-delimited list of the scopes of the token

token_type
required
string
Default: "Bearer"

The type of token

Response samples

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

Health Check

Health Check

Responses

Response Schema: application/json
status
required
string
env
string
info
string
timestamp
string <date-time>
version
string

Response samples

Content type
application/json
{
  • "status": "up",
  • "version": "1.212.0",
  • "info": "Service is healthy.",
  • "timestamp": "2018-02-10T09:30:00Z",
  • "env": "unknown"
}

Vessel Routing API

See the relevant areas of the Vessel Routing API for supportive information that can be used as input to the Weather Factor API, such as ports, predefined conditional areas, routing restrictions, and custom vessel models.

Voyage Probabilities

Request for voyage probabilities

Request for voyage probabilities by supplying information about a route, restrictions and a vessel. This endpoint returns the probabilities for the weather factor, voyage duration, fuel consumption and the route's distance summary.

Authorizations:
(BearerABBIdentity)
Request Body schema: application/json
etd
required
string <RFC 3339 (UTC)>

The estimated time of departure. The year will be ignored.

required
Array of objects (TemplateRoutePoint) >= 2 items

The ordered fixed way points that must be included in the route (including departure and destination locations).

speed
required
number <knots (kn)> ( 0 .. 50 ]

The speed to use when calculating the route.

required
object (vesselParameters)

Describes the vessel and its state.

object (Restrictions)

The restrictions that should apply for this calculation.

object

Information about the voyage this route is for.

Responses

Response Schema: application/json
One of
apiVersion
required
string

Version of the API this response was generated from

required
object

Summary stats about CO2 emissions.

correlationId
required
string

Internal identifier of the request

required
object

Summary stats about fuel usage.

required
object

The details of the path that was used to calculate the weather factor.

status
required
string

The resulting status of the internal calculation

Value: "Success"
required
object (RouteUsedVariables)

The variables that were used during calculation.

required
object (Summary Stats)

Summary stats about the voyage duration.

warnings
required
Array of strings

Human-readable explanations specific to this occurrence.

required
object (Summary Stats)

Summary stats about the weather factor.

Request samples

Content type
application/json
{
  • "speed": 10,
  • "etd": "2020-09-20T19:20:30.45Z",
  • "points": [
    ],
  • "vesselParameters": {
    },
  • "restrictions": {
    },
  • "voyage": {
    }
}

Response samples

Content type
application/json
Example
{
  • "correlationId": "PsFtKHanDoEF2Gg=",
  • "warnings": [
    ],
  • "apiVersion": "1.212.0",
  • "route": {
    },
  • "status": "Success",
  • "usedVariables": {
    },
  • "weatherFactor": {
    },
  • "voyageDurationStats": {
    },
  • "co2EmissionStats": {
    },
  • "fuelUsedStats": {
    }
}