DTN Vessel Insights API (v3.2.3347) API Reference API Reference

Accelerate your digitalization journey with quality checked datasets (ais, noon, weather etc.) & vessel performance analysis results.


Introduction

DTN Vessel Insights API provides quality checked datasets & vessel performance analysis results for any vessel performance monitoring, voyage management, commercial intelligence or supply chain analytics dashboard. Vessel Insights API is an all-in-one data solution that collects, collates, and delivers every relevant piece of operational data at the fleet or vessel level. It seamlessly integrates into your existing business processes and acts as a single source of truth for all vessel performance related use cases.

By integrating Vessel Insights API, any vessel performance management dashboard can be up and running in no time. By calling the API, customers can get continuous quality checked performance data along the vessel's track, noon to noon performance analysis results, voyage and performance summaries, CII rating calculations, dataset needed to create post voyage analysis reports etc.

If you would like to request trial of Vessel Insights API, you can do so through DTN's website. Go on the link and click 'REQUEST A TRIAL' button. A sales representative from DTN will get back to you with API credentials.

For questions, contact DTN API support team: apisupport@dtn.com


Available Queries

Vessel Insights is a GraphQL API. This means that we are able to develop dedicated queries for specific use cases of our customers. Currently, following queries are available in Vessel Insights API.

Query Use case
getAllEvents Get continuous quality checked vessel performance relevant data from multiple sources (ais, noon report, weather, digital twin model) along the vessel's track.
trackSummary Generate voyage & performance summaries for any vessel in the entire merchant fleet (calculations use a library of vessel performance models)
noonSummary Generate voyage & performance summaries for your own fleet (calculations use quality checked noon report data)
trackCii Monitor CII ratings for any vessel in the entire merchant fleet. Can be used to estimate Voyage CII, YTD CII, Year End CII, CP Attained CII, Delivery Attained CII etc. (calculations use a library of vessel performance models)
noonCii Monitor CII ratings for any vessel in your own fleet. Can be used to estimate Voyage CII, YTD CII, Year End CII, CP Attained CII, Delivery Attained CII etc. (calculations use quality checked noon report data)
getEvent Get data for a single noon or AIS event.

To access the data through the Vessel Insights API, you will need to execute one of these GraphQL queries. You can execute any query (according to the granted permissions) using a single API endpoint. The structure of the response will match the structure of the query. We continue to develop more queries to support various vessel performance related use cases. In coming months, you can expect to see dedicated queries for post voyage analysis reports (PVARs), hull cleaning decision support etc.


How does it work?

The Vessel Insights is a GraphQL API where you authenticate with OAuth. The response format is typically JSON. Vessel Insights API package consists of following APIs:

  • Shipping Auth0 API: Can be used to request access token
  • Vessel Insights Subscription API : Can be used to subscribe & unsubscribe vessels to Vessel Insights API
  • Insert Noon API : Can be used to insert noon reports in Vessel Insights API
  • Vessel Insights API: Can be used to get continuous quality checked vessel performance relevant data from multiple sources (ais, noon, autolog, weather, vessel digital twin model) along any vessel's track and can also be used to get vessel performance analysis results for any IMO number between a date/time range.

Getting Started

  1. DTN can provide {client_id} and {client_secret} which can be used to get tokens to access all the relevant APIs (Vessel Insights API, Vessel Insights Subscription API & Insert Noon API) or tokens which provide access to a limited set of above mentioned APIs.
  2. This is to facilitate user management on the customer side where customer can make someone responsible for subscribing and unsubscribing vessels, someone else can be responsible for sending noon reports and another group of people might be only authorized to get data from Vessel Insights API.
  3. The required access {token} can be fetched making use of your personal {client_id} and {client_secret} via the authentication endpoint. An example call is described in section below.
    POST https://auth.api.shipping.dtn.com/oauth/token
    {
     "client_id": "<supplied by DTN>",
     "client_secret": "<supplied by DTN>",
     "grant_type": "client_credentials",
     "audience": "https://vesselinsights.api.shipping.dtn.com/vesselinsightsresource"
    }
    
  4. Use the {token} from step 3 to grant access towards the Vessel Insights Subscription API to self-manage vessel subscriptions for Vessel Insights API.
  5. Use the {token} from step 3 to grant access towards the Insert Noon API to insert noon reports in Vessel Insights API.
  6. Use the {token} of the step 3 to grant access towards the Vessel Insights API and specify (in GraphQL format) what information to return from a subscribed vessel that DTN is tracking. With GraphQL you can specify the exact parameters that needs to be returned.
    Authorization: Bearer {token}
    
  7. Using Vessel Insights API you can request time series data and performance analysis results for an IMO number between a date/time range. Example calls are described in section below.

Try Vessel Insights API Now

Download Vessel Insights API Postman collection from this link, import this collection in Postman and add Client ID and Client Secret provided to you by DTN to start testing Vessel Insights API. Sample queries for different scenarios that you can reference to are also available in the collection.
To learn how to import Postman collections, click here.


FAQ

  • Can I send noon reports by email?
    Customers can also send us noon reports by email. We accept multiple industry standard formats. Enquire DTN sales team for further information.

  • How can I send an updated noon report?
    If the customer sends a noon report which has a Report Date and Position Type that matches an existing noon report (for the same IMO number), the new noon report will overwrite the existing noon report. The noon to noon analysis from the previous and next noon report will be redone using the new noon report data. If the customer sends a noon report which has a Report Date that matches an existing noon report but the Position Type is different (for the same IMO number), the new noon report will be available in Vessel Insights API together with the existing noon report. There will be no noon to noon analysis done between these two noon reports. The noon to noon analysis from the next noon report will be redone using the new noon report data.

  • Is AIS track available in Vessel Insights API?
    We create a normalized AIS track where position data is available every 15 minutes.

  • Is weather data available in Vessel Insights API?
    DTN's proprietary hindcast weather data is available every 1 hour along the vessel's track.

  • Can I use Vessel Insights API for real time monitoring? Or is there a latency?
    Please be aware that subscribing a vessel will not immediately result in data being available in Vessel Insights API for this vessel. For all the vessels subscribed to the Vessel Insights API, calculations are done once every day at 0 UTC. These calculations cover the ships timeline from - 48 to - 24 hours. When the calculations are finished, this data is added to the cloud storage and can be accessed by customers using Vessel Insights API endpoints. Therefore, depending on when a customer calls the Vessel Insights API, data for last 24 to 48 hours may not be available in Vessel Insights API. When a delayed or updated noon report comes in, this noon data and the recalculated data from neighbouring noon reports is immediately added to the same cloud storage.

  • Can I access vessel insights dataset of a vessel after I have unsubscribed this vessel from Vessel Insights API?
    User can access Vessel Insights API data for a vessel as long as this vessel is subscribed to Vessel Insights API. Once the vessel is unsubscribed, user cannot access Vessel Insights API data for this vessel anymore. If user wants to access data and analysis results from the period when the vessel was subscribed to Vessel Insights API, they can subscribe the vessel again to Vessel Insights API and access this data.

  • How do you handle gaps in AIS data in Vessel Insights API?
    First we get AIS data from our supplier. Then we normalize this AIS track to create a DTN version of vessel's track. This track has positions every 15 mins. If the gap in AIS data we receive is more than 24 hours, there will be a gap in the normalized track available in Vessel Insights API as well. If the gap in AIS data is smaller, we will still normalize the track and position will be available every 15 minutes. When there is a gap in the normalized track (i.e. when there is no AIS data for more than 24 hours), the first track point that is available after the gap will not have any fuel consumption results from the previous track point.

  • The MMSI of a vessel that I have subscribed to Vessel Insights API has changed. Do I need to update my subscription?
    At this moment, when MMSI of the ship changes, customer needs to inform DTN (contact DTN API support team: apisupport@dtn.com) and the technology team will update the subscription with new MMSI. We are working on a solution so that we can automatically update the MMSI number when it changes.


Release Notes

API Endpoints
production:
https://vesselinsights.api.shipping.dtn.com/graphql

Queries

GetAllEvents

  • This query can be used to get continuous quality checked vessel performance relevant data from multiple sources (ais, noon, autolog, weather, vessel digital twin model) along the vessel's track.
  • This query can be used by customers who send noon reports to DTN and by customers who do not send any noon reports.
  • When noon reports are provided, this query can also be used to get noon to noon performance analysis data along the vessel's track.
  • When noon reports are not provided, this query can also be used to get estimated consumption and emissions data (from main engine, auxiliary engine and boiler) along the vessel's track.
  • Customer can subscribe a vessel to Vessel Insights API and can then use this query to access data.
  • Customer can send noon reports to DTN using Insert Noon API, EasyNoon etc.

(no description)

Example

Request Content-Types: application/json
Query
query getAllEvents($query: GetAllEventsQueryInput!){
  getAllEvents(query: $query){
    items{
      imo
      eventId
      eventType
      location{
        latitude
        longitude
      }
      eventDate
      insertDate
      updatedDate
      customerId
      sourceType
      noonSource
      draft{
        aft
        current
        fwd
      }
      bunkerData{
        rob{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
        bunkered{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
        boiler{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
        mainEngine{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
        tankHeating{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
        holdTankWashing{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
        auxEngines{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
        other{
          hfo
          mgouls
          hfols
          bio
          hfouls
          mgo
          mdo
          mdols
          lng
          freshWater
          mgols
          hfolsdm
          hfoulsdm
        }
      }
      observedWeather{
        seaHeight
        swellDirection
        currentDirection
        pressure
        currentSpeed
        windSpeed
        swellHeight
        windDirection
      }
      cargo
      charterPartySpeed
      observedDistance
      steamingTime
      stoppedTime
      sog
      positionType
      comment
      mainEngineLoad
      averageRpmLast24Hr
      scrubber
      sailingIn
      voyageId
      destination
      departure
      condition
      avgObsSpeed
      facts{
        factsType
        weatherAnalysis{
          windSpeed10m
          windDirection10m
          seaWaveHeight
          seaWavePeriod
          swellHeight
          swellDirection
          swellPeriod
          significantWaveHeight
          currentSpeed
          currentDirection
        }
        distance
        calculatedSog
        calculatedPerfSpeed
        cx
        wx
        calculatedFuelConsumptionME
        calculatedCO2EmissionsME
        timeDifference
        course
        previousEventData{
          location{
            latitude
            longitude
          }
          eventId
          eventDate
          eventType
          noonSource
          isVesselInECA
        }
        avgSog
        avgCourse
        minCx
        avgCx
        maxCx
        minWx
        avgWx
        maxWx
        minPerfSpeed
        avgPerfSpeed
        maxPerfSpeed
        isVesselInECA
        distanceInECA
        timeInECA
        minWeatherAnalysis{
          windSpeed10m
          windDirection10m
          seaWaveHeight
          seaWavePeriod
          swellHeight
          swellDirection
          swellPeriod
          significantWaveHeight
          currentSpeed
          currentDirection
        }
        maxWeatherAnalysis{
          windSpeed10m
          windDirection10m
          seaWaveHeight
          seaWavePeriod
          swellHeight
          swellDirection
          swellPeriod
          significantWaveHeight
          currentSpeed
          currentDirection
        }
        avgWeatherAnalysis{
          windSpeed10m
          windDirection10m
          seaWaveHeight
          seaWavePeriod
          swellHeight
          swellDirection
          swellPeriod
          significantWaveHeight
          currentSpeed
          currentDirection
        }
        calculatedBunkerData{
          bunkerType
          bunkered
          co2Emission
          co2PerMile
          consumption
          energyEfficiencyOperationalIndicator
          rob
          usagePer24Hours
          usagePerMile
          usagePerTonnagePerMile
        }
        operationalPhase
        calculatedFuelConsumptionOther
        calculatedCO2EmissionsOther
      }
    }
    nextToken
  }
}
Variables
{
  "query": {
    "imo": "number",
    "from": "string",
    "to": "string",
    "eventType": "string",
    "updateSince": "string",
    "sort": "string",
    "limit": "number",
    "nextToken": "string"
  }
}
200 OK

Successful operation

type
Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "getAllEvents": {
      "items": [
        {
          "imo": "string",
          "eventId": "string",
          "eventType": "string",
          "location": {
            "latitude": "number",
            "longitude": "number"
          },
          "eventDate": "string",
          "insertDate": "string",
          "updatedDate": "string",
          "customerId": "integer",
          "sourceType": "string",
          "noonSource": "string",
          "draft": {
            "aft": "number",
            "current": "number",
            "fwd": "number"
          },
          "bunkerData": {
            "rob": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            },
            "bunkered": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            },
            "boiler": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            },
            "mainEngine": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            },
            "tankHeating": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            },
            "holdTankWashing": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            },
            "auxEngines": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            },
            "other": {
              "hfo": "number",
              "mgouls": "number",
              "hfols": "number",
              "bio": "number",
              "hfouls": "number",
              "mgo": "number",
              "mdo": "number",
              "mdols": "number",
              "lng": "number",
              "freshWater": "number",
              "mgols": "number",
              "hfolsdm": "number",
              "hfoulsdm": "number"
            }
          },
          "observedWeather": {
            "seaHeight": "number",
            "swellDirection": "integer",
            "currentDirection": "integer",
            "pressure": "number",
            "currentSpeed": "number",
            "windSpeed": "integer",
            "swellHeight": "number",
            "windDirection": "integer"
          },
          "cargo": "string",
          "charterPartySpeed": "string",
          "observedDistance": "number",
          "steamingTime": "number",
          "stoppedTime": "string",
          "sog": "number",
          "positionType": "string",
          "comment": "string",
          "mainEngineLoad": "number",
          "averageRpmLast24Hr": "number",
          "scrubber": "boolean",
          "sailingIn": "string",
          "voyageId": "string",
          "destination": "string",
          "departure": "string",
          "condition": "string",
          "avgObsSpeed": "number",
          "facts": {
            "factsType": "string",
            "weatherAnalysis": {
              "windSpeed10m": "number",
              "windDirection10m": "number",
              "seaWaveHeight": "number",
              "seaWavePeriod": "number",
              "swellHeight": "number",
              "swellDirection": "number",
              "swellPeriod": "number",
              "significantWaveHeight": "number",
              "currentSpeed": "number",
              "currentDirection": "number"
            },
            "distance": "number",
            "calculatedSog": "number",
            "calculatedPerfSpeed": "number",
            "cx": "number",
            "wx": "number",
            "calculatedFuelConsumptionME": "number",
            "calculatedCO2EmissionsME": "number",
            "timeDifference": "number",
            "course": "number",
            "previousEventData": {
              "location": {
                "latitude": "number",
                "longitude": "number"
              },
              "eventId": "string",
              "eventDate": "string",
              "eventType": "string",
              "noonSource": "string",
              "isVesselInECA": "boolean"
            },
            "avgSog": "number",
            "avgCourse": "number",
            "minCx": "number",
            "avgCx": "number",
            "maxCx": "number",
            "minWx": "number",
            "avgWx": "number",
            "maxWx": "number",
            "minPerfSpeed": "number",
            "avgPerfSpeed": "number",
            "maxPerfSpeed": "number",
            "isVesselInECA": "boolean",
            "distanceInECA": "number",
            "timeInECA": "number",
            "minWeatherAnalysis": {
              "windSpeed10m": "number",
              "windDirection10m": "number",
              "seaWaveHeight": "number",
              "seaWavePeriod": "number",
              "swellHeight": "number",
              "swellDirection": "number",
              "swellPeriod": "number",
              "significantWaveHeight": "number",
              "currentSpeed": "number",
              "currentDirection": "number"
            },
            "maxWeatherAnalysis": {
              "windSpeed10m": "number",
              "windDirection10m": "number",
              "seaWaveHeight": "number",
              "seaWavePeriod": "number",
              "swellHeight": "number",
              "swellDirection": "number",
              "swellPeriod": "number",
              "significantWaveHeight": "number",
              "currentSpeed": "number",
              "currentDirection": "number"
            },
            "avgWeatherAnalysis": {
              "windSpeed10m": "number",
              "windDirection10m": "number",
              "seaWaveHeight": "number",
              "seaWavePeriod": "number",
              "swellHeight": "number",
              "swellDirection": "number",
              "swellPeriod": "number",
              "significantWaveHeight": "number",
              "currentSpeed": "number",
              "currentDirection": "number"
            },
            "calculatedBunkerData": [
              {
                "bunkerType": "string",
                "bunkered": "number",
                "co2Emission": "number",
                "co2PerMile": "number",
                "consumption": "number",
                "energyEfficiencyOperationalIndicator": "number",
                "rob": "number",
                "usagePer24Hours": "number",
                "usagePerMile": "number",
                "usagePerTonnagePerMile": "number"
              }
            ],
            "operationalPhase": "string",
            "calculatedFuelConsumptionOther": "number",
            "calculatedCO2EmissionsOther": "number"
          }
        }
      ],
      "nextToken": "string"
    }
  }
}

GetEvent

  • Using this query, user can request data for a single noon or AIS event
  • This can be done by providing the Vessel Insights Event ID in the request
id:
string

(no description)

Example

Request Content-Types: application/json
Query
query getEvent($id: String!){
  getEvent(id: $id){
    imo
    eventId
    eventType
    location{
      latitude
      longitude
    }
    eventDate
    insertDate
    updatedDate
    customerId
    sourceType
    noonSource
    draft{
      aft
      current
      fwd
    }
    bunkerData{
      rob{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
      bunkered{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
      boiler{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
      mainEngine{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
      tankHeating{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
      holdTankWashing{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
      auxEngines{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
      other{
        hfo
        mgouls
        hfols
        bio
        hfouls
        mgo
        mdo
        mdols
        lng
        freshWater
        mgols
        hfolsdm
        hfoulsdm
      }
    }
    observedWeather{
      seaHeight
      swellDirection
      currentDirection
      pressure
      currentSpeed
      windSpeed
      swellHeight
      windDirection
    }
    cargo
    charterPartySpeed
    observedDistance
    steamingTime
    stoppedTime
    sog
    positionType
    comment
    mainEngineLoad
    averageRpmLast24Hr
    scrubber
    sailingIn
    voyageId
    destination
    departure
    condition
    avgObsSpeed
    facts{
      factsType
      weatherAnalysis{
        windSpeed10m
        windDirection10m
        seaWaveHeight
        seaWavePeriod
        swellHeight
        swellDirection
        swellPeriod
        significantWaveHeight
        currentSpeed
        currentDirection
      }
      distance
      calculatedSog
      calculatedPerfSpeed
      cx
      wx
      calculatedFuelConsumptionME
      calculatedCO2EmissionsME
      timeDifference
      course
      previousEventData{
        location{
          latitude
          longitude
        }
        eventId
        eventDate
        eventType
        noonSource
        isVesselInECA
      }
      avgSog
      avgCourse
      minCx
      avgCx
      maxCx
      minWx
      avgWx
      maxWx
      minPerfSpeed
      avgPerfSpeed
      maxPerfSpeed
      isVesselInECA
      distanceInECA
      timeInECA
      minWeatherAnalysis{
        windSpeed10m
        windDirection10m
        seaWaveHeight
        seaWavePeriod
        swellHeight
        swellDirection
        swellPeriod
        significantWaveHeight
        currentSpeed
        currentDirection
      }
      maxWeatherAnalysis{
        windSpeed10m
        windDirection10m
        seaWaveHeight
        seaWavePeriod
        swellHeight
        swellDirection
        swellPeriod
        significantWaveHeight
        currentSpeed
        currentDirection
      }
      avgWeatherAnalysis{
        windSpeed10m
        windDirection10m
        seaWaveHeight
        seaWavePeriod
        swellHeight
        swellDirection
        swellPeriod
        significantWaveHeight
        currentSpeed
        currentDirection
      }
      calculatedBunkerData{
        bunkerType
        bunkered
        co2Emission
        co2PerMile
        consumption
        energyEfficiencyOperationalIndicator
        rob
        usagePer24Hours
        usagePerMile
        usagePerTonnagePerMile
      }
      operationalPhase
      calculatedFuelConsumptionOther
      calculatedCO2EmissionsOther
    }
  }
}
Variables
{
  "id": "string"
}
200 OK

Successful operation

type
Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "getEvent": {
      "imo": "string",
      "eventId": "string",
      "eventType": "string",
      "location": {
        "latitude": "number",
        "longitude": "number"
      },
      "eventDate": "string",
      "insertDate": "string",
      "updatedDate": "string",
      "customerId": "integer",
      "sourceType": "string",
      "noonSource": "string",
      "draft": {
        "aft": "number",
        "current": "number",
        "fwd": "number"
      },
      "bunkerData": {
        "rob": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        },
        "bunkered": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        },
        "boiler": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        },
        "mainEngine": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        },
        "tankHeating": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        },
        "holdTankWashing": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        },
        "auxEngines": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        },
        "other": {
          "hfo": "number",
          "mgouls": "number",
          "hfols": "number",
          "bio": "number",
          "hfouls": "number",
          "mgo": "number",
          "mdo": "number",
          "mdols": "number",
          "lng": "number",
          "freshWater": "number",
          "mgols": "number",
          "hfolsdm": "number",
          "hfoulsdm": "number"
        }
      },
      "observedWeather": {
        "seaHeight": "number",
        "swellDirection": "integer",
        "currentDirection": "integer",
        "pressure": "number",
        "currentSpeed": "number",
        "windSpeed": "integer",
        "swellHeight": "number",
        "windDirection": "integer"
      },
      "cargo": "string",
      "charterPartySpeed": "string",
      "observedDistance": "number",
      "steamingTime": "number",
      "stoppedTime": "string",
      "sog": "number",
      "positionType": "string",
      "comment": "string",
      "mainEngineLoad": "number",
      "averageRpmLast24Hr": "number",
      "scrubber": "boolean",
      "sailingIn": "string",
      "voyageId": "string",
      "destination": "string",
      "departure": "string",
      "condition": "string",
      "avgObsSpeed": "number",
      "facts": {
        "factsType": "string",
        "weatherAnalysis": {
          "windSpeed10m": "number",
          "windDirection10m": "number",
          "seaWaveHeight": "number",
          "seaWavePeriod": "number",
          "swellHeight": "number",
          "swellDirection": "number",
          "swellPeriod": "number",
          "significantWaveHeight": "number",
          "currentSpeed": "number",
          "currentDirection": "number"
        },
        "distance": "number",
        "calculatedSog": "number",
        "calculatedPerfSpeed": "number",
        "cx": "number",
        "wx": "number",
        "calculatedFuelConsumptionME": "number",
        "calculatedCO2EmissionsME": "number",
        "timeDifference": "number",
        "course": "number",
        "previousEventData": {
          "location": {
            "latitude": "number",
            "longitude": "number"
          },
          "eventId": "string",
          "eventDate": "string",
          "eventType": "string",
          "noonSource": "string",
          "isVesselInECA": "boolean"
        },
        "avgSog": "number",
        "avgCourse": "number",
        "minCx": "number",
        "avgCx": "number",
        "maxCx": "number",
        "minWx": "number",
        "avgWx": "number",
        "maxWx": "number",
        "minPerfSpeed": "number",
        "avgPerfSpeed": "number",
        "maxPerfSpeed": "number",
        "isVesselInECA": "boolean",
        "distanceInECA": "number",
        "timeInECA": "number",
        "minWeatherAnalysis": {
          "windSpeed10m": "number",
          "windDirection10m": "number",
          "seaWaveHeight": "number",
          "seaWavePeriod": "number",
          "swellHeight": "number",
          "swellDirection": "number",
          "swellPeriod": "number",
          "significantWaveHeight": "number",
          "currentSpeed": "number",
          "currentDirection": "number"
        },
        "maxWeatherAnalysis": {
          "windSpeed10m": "number",
          "windDirection10m": "number",
          "seaWaveHeight": "number",
          "seaWavePeriod": "number",
          "swellHeight": "number",
          "swellDirection": "number",
          "swellPeriod": "number",
          "significantWaveHeight": "number",
          "currentSpeed": "number",
          "currentDirection": "number"
        },
        "avgWeatherAnalysis": {
          "windSpeed10m": "number",
          "windDirection10m": "number",
          "seaWaveHeight": "number",
          "seaWavePeriod": "number",
          "swellHeight": "number",
          "swellDirection": "number",
          "swellPeriod": "number",
          "significantWaveHeight": "number",
          "currentSpeed": "number",
          "currentDirection": "number"
        },
        "calculatedBunkerData": [
          {
            "bunkerType": "string",
            "bunkered": "number",
            "co2Emission": "number",
            "co2PerMile": "number",
            "consumption": "number",
            "energyEfficiencyOperationalIndicator": "number",
            "rob": "number",
            "usagePer24Hours": "number",
            "usagePerMile": "number",
            "usagePerTonnagePerMile": "number"
          }
        ],
        "operationalPhase": "string",
        "calculatedFuelConsumptionOther": "number",
        "calculatedCO2EmissionsOther": "number"
      }
    }
  }
}

TrackSummary

  • This query can be used to generate voyage & performance summaries for any vessel in the entire merchant fleet.
  • This query should be used when no actual consumption data is available from ships.
  • All calculations are based on normalized AIS tracks & DTN's weather and digital twin models. Consumption from main engine, auxiliary engine and boiler are estimated consumption and may differ from actual consumption.
  • Customer can subscribe a vessel to Vessel Insights API and can then use this query to generate voyage & performance summaries for this vessel (from time of subscription onwards)
  • A customer has to just enter the IMO number and a time range and this query will generate voyage and performance summary on the fly by analyzing the available performance dataset in Vessel Insights API.

(no description)

Example

Request Content-Types: application/json
Query
query trackSummary($query: SummaryQueryInput!){
  trackSummary(query: $query){
    distance
    distanceInsideECA
    distanceOutsideECA
    timeInsideECA
    timeOutsideECA
    fuelConsumptionMEInsideECA
    fuelConsumptionMEOutsideECA
    otherFuelConsumptionInsideECA
    otherFuelConsumptionOutsideECA
    cO2EmissionsME
    cO2EmissionsMEInsideECA
    cO2EmissionsMEOutsideECA
    otherCO2Emissions
    otherCO2EmissionsInsideECA
    otherCO2EmissionsOutsideECA
    cO2Emissions
    warnings{
      missingAisTrack{
        from
        to
      }
    }
  }
}
Variables
{
  "query": {
    "imo": "number",
    "from": "string",
    "to": "string"
  }
}
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "trackSummary": {
      "distance": "number",
      "distanceInsideECA": "number",
      "distanceOutsideECA": "number",
      "timeInsideECA": "number",
      "timeOutsideECA": "number",
      "fuelConsumptionMEInsideECA": "number",
      "fuelConsumptionMEOutsideECA": "number",
      "otherFuelConsumptionInsideECA": "number",
      "otherFuelConsumptionOutsideECA": "number",
      "cO2EmissionsME": "number",
      "cO2EmissionsMEInsideECA": "number",
      "cO2EmissionsMEOutsideECA": "number",
      "otherCO2Emissions": "number",
      "otherCO2EmissionsInsideECA": "number",
      "otherCO2EmissionsOutsideECA": "number",
      "cO2Emissions": "number",
      "warnings": {
        "missingAisTrack": [
          {
            "from": "string",
            "to": "string"
          }
        ]
      }
    }
  }
}

NoonSummary

  • This query in Vessel Insights API can be used to generate voyage & performance summaries for your own fleet.
  • Calculations are based on noon report data received from the customer's fleet.
  • Customer can subscribe a vessel to Vessel Insights API and send noon reports to DTN (using Insert Noon API, EasyNoon etc.). Customers can then use this query to generate voyage & performance summaries for this vessel.
  • The validations for the missing noon reports are based on the time range user provides in the query and not on the day itself. If the query is this:
    noonSummary(query: {
      imo: 9347827
      from: "2023-02-01T00:00:00.000Z"
      to: "2023-02-16T06:00:00.000Z"
    }
    
    Then VIA would check if there is a noon report available between 2023-02-16T00:00:00.000Z and 2023-02-16T06:00:00.000Z. If there is no noon report available in this time range, it will return 2023-02-16 under missingNoonReports field.

(no description)

Example

Request Content-Types: application/json
Query
query noonSummary($query: SummaryQueryInput!){
  noonSummary(query: $query){
    bunkerDataAnalysis{
      bunkerType
      totalBunkered
      totalCO2Emissions
      totalConsumption
      mainEngineConsumption
      auxEngineConsumption
      boilerConsumption
    }
    totalObservedDistance
    totalCO2EmissionsAllFuel
    warnings{
      missingNoonReports
    }
  }
}
Variables
{
  "query": {
    "imo": "number",
    "from": "string",
    "to": "string"
  }
}
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "noonSummary": {
      "bunkerDataAnalysis": [
        {
          "bunkerType": "string",
          "totalBunkered": "number",
          "totalCO2Emissions": "number",
          "totalConsumption": "number",
          "mainEngineConsumption": "number",
          "auxEngineConsumption": "number",
          "boilerConsumption": "number"
        }
      ],
      "totalObservedDistance": "number",
      "totalCO2EmissionsAllFuel": "number",
      "warnings": {
        "missingNoonReports": [
          "string"
        ]
      }
    }
  }
}

TrackCII

  • This query in Vessel Insights API can be used to estimate CII for any vessel in the entire merchant fleet.
  • This query should be used when no actual consumption data is available from ships.
  • CII calculations are based on normalized AIS tracks & DTN's weather and digital twin models. Consumption from main engine, auxiliary engine and boiler are estimated consumption and may differ from actual consumption.
  • Customer can subscribe a vessel to Vessel Insights API and can then use this query to calculate CII ratings for this vessel (from time of subscription onwards)
  • CII correction factors and voyage adjustments are not accounted for.
  • Optional fields that customers can specify in the track CII query are: extraDistance, extraCO2Emissions, ciiVesselType, deadWeight, grossTonnage, ratingYear

(no description)

Example

Request Content-Types: application/json
Query
query trackCii($query: CiiQueryInput!){
  trackCii(query: $query){
    ciiVesselType
    deadWeight
    grossTonnage
    totalDistance
    totalCO2Emissions
    ratingYear
    attainedCii
    referenceCii
    requiredCii
    ciiRating
    warnings{
      missingAisTrack{
        from
        to
      }
      otherWarnings
    }
  }
}
Variables
{
  "query": {
    "imo": "number",
    "from": "string",
    "to": "string",
    "extraDistance": "number",
    "extraCO2Emissions": "number",
    "ciiVesselType": "string",
    "deadWeight": "number",
    "grossTonnage": "number",
    "ratingYear": "number"
  }
}
200 OK

Successful operation

type
Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "trackCii": {
      "ciiVesselType": "string",
      "deadWeight": "number",
      "grossTonnage": "number",
      "totalDistance": "number",
      "totalCO2Emissions": "number",
      "ratingYear": "integer",
      "attainedCii": "number",
      "referenceCii": "number",
      "requiredCii": "number",
      "ciiRating": "string",
      "warnings": {
        "missingAisTrack": [
          {
            "from": "string",
            "to": "string"
          }
        ],
        "otherWarnings": [
          "string"
        ]
      }
    }
  }
}

NoonCII

  • This query in Vessel Insights API can be used to calculate CII rating for your own fleet.
  • Calculations are based on noon report data received from the customer's fleet.
  • CII correction factors and voyage adjustments are not accounted for in this release.
  • We are updating our noon reporting tools to collect extra data needed for these calculations. After that, we will update CII calculations to include correction factors and voyage adjustments (future release).
  • Customer can subscribe a vessel to Vessel Insights API and send noon reports to DTN (using Insert Noon API, EasyNoon etc.). Customers can then use this query to calculate CII rantings for this vessel.
  • Optional fields that customers can specify in the noon CII query are: extraDistance, extraCO2Emissions, ciiVesselType, deadWeight, grossTonnage, ratingYear
  • The validations for the missing noon reports are based on the time range user provides in the query and not on the day itself. If the query is this:
    noonCii(query: {
      imo: 9347827
      from: "2023-02-01T00:00:00.000Z"
      to: "2023-02-16T06:00:00.000Z"
    }
    
    Then VIA would check if there is a noon report available between 2023-02-16T00:00:00.000Z and 2023-02-16T06:00:00.000Z. If there is no noon report available in this time range, it will return 2023-02-16 under missingNoonReports field.

(no description)

Example

Request Content-Types: application/json
Query
query noonCii($query: CiiQueryInput!){
  noonCii(query: $query){
    ciiVesselType
    deadWeight
    grossTonnage
    totalDistance
    totalCO2Emissions
    ratingYear
    attainedCii
    referenceCii
    requiredCii
    ciiRating
    warnings{
      missingNoonReports
      otherWarnings
    }
  }
}
Variables
{
  "query": {
    "imo": "number",
    "from": "string",
    "to": "string",
    "extraDistance": "number",
    "extraCO2Emissions": "number",
    "ciiVesselType": "string",
    "deadWeight": "number",
    "grossTonnage": "number",
    "ratingYear": "number"
  }
}
200 OK

Successful operation

type
Response Content-Types: application/json
Response Example (200 OK)
{
  "data": {
    "noonCii": {
      "ciiVesselType": "string",
      "deadWeight": "number",
      "grossTonnage": "number",
      "totalDistance": "number",
      "totalCO2Emissions": "number",
      "ratingYear": "integer",
      "attainedCii": "number",
      "referenceCii": "number",
      "requiredCii": "number",
      "ciiRating": "string",
      "warnings": {
        "missingNoonReports": [
          "string"
        ],
        "otherWarnings": [
          "string"
        ]
      }
    }
  }
}

Schema Definitions

AWSDateTime

The AWSDateTime scalar type provided by AWS AppSync, represents a valid extended ISO 8601 DateTime string. In other words, this scalar type accepts datetime strings of the form YYYY-MM-DDThh:mm:ss.SSSZ. The scalar can also accept "negative years" of the form -YYYY which correspond to years before 0000. For example, " -2017-01-01T00:00Z" and " -9999-01-01T00:00Z" are both valid datetime strings. The field after the two digit seconds field is a nanoseconds field. It can accept between 1 and 9 digits. So, for example, " 1970-01-01T12:00:00.2Z", " 1970-01-01T12:00:00.277Z" and " 1970-01-01T12:00:00.123456789Z" are all valid datetime strings. The seconds and nanoseconds fields are optional (the seconds field must be specified if the nanoseconds field is to be used). The time zone offset is compulsory for this scalar. The time zone offset must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.

Boolean

Built-in Boolean

BunkerAnalysisData

bunkerType

Represents the type of bunker fuel

totalBunkered

The total amount of bunker fuel bunkered by the vessel [mT]

totalCO2Emissions

The total amount of CO2 emissions produced by the vessel as a result of consuming the bunker fuel [mT]

totalConsumption

The total consumption of bunker fuel by the vessel [mT]

mainEngineConsumption

The consumption of bunker fuel by the main engine of the vessel [mT]

auxEngineConsumption

The consumption of bunker fuel by the auxiliary engines of the vessel [mT]

boilerConsumption

The consumption of bunker fuel by the boilers on the vessel [mT]

BunkerData

rob

List of bunkers that are still on board. Reported data in noon report split by the available bunker types. [metric tons (MT)]

bunkered

List of bunkered values. Reported data in noon report split by the available bunker types. [metric tons (MT)]

boiler

Fuel consumption by boiler. Reported data in noon report split by the available bunker types. [metric tons (MT)]

mainEngine

Fuel consumption by main engine. Reported data in noon report split by the available bunker types. [metric tons (MT)]

tankHeating

Fuel consumption by tank heating. Reported data in noon report split by the available bunker types. [metric tons (MT)]

holdTankWashing

Fuel consumption by hold tank washing. Reported data in noon report split by the available bunker types. [metric tons (MT)]

auxEngines

Fuel consumption by aux engines. Reported data in noon report split by the available bunker types. [metric tons (MT)]

other

Other fuel consumer. Reported data in noon report split by the available bunker types. [metric tons (MT)]

BunkerDataValues

These properties represent the different types of fuel and water that are used or stored on a ship.

hfo

HFO (ISO 8217 Grades RME through RMK) with sulphur content>0.5% (Cf = 3,114) [metric tons (MT)]

mgouls

Marine Gas Oil Ultra Low Sulfur

hfols

HFO (ISO 8217 Grades RME through RMK) with 0.1%<sulphur content<=0.5% (Cf = 3,114) [metric tons (MT)]

bio

Bio Diesel (Cf = 2,834) [metric tons (MT)]

hfouls

HFO (ISO 8217 Grades RME through RMK) with sulphur content <=0.1% (Cf = 3,114) [metric tons (MT)]

mgo

Marine Gas Oil

mdo

Marine Diesel Oil

mdols

Marine Diesel Oil Low Sulfur

lng

Liquefied Natural Gas (LNG) (Cf = 2,75) [metric tons (MT)]

freshWater

Fresh Water

mgols

Marine Gas Oil Low Sulfur

hfolsdm

MGO/MDO (ISO 8217 Grades DMX to DMB) with 0.1%<sulphur content<=0.5% (Cf = 3,206) [metric tons (MT)]

hfoulsdm

MGO/MDO (ISO 8217 Grades DMX to DMB) with sulphur content <=0.1% (Cf = 3,206) [metric tons (MT)]

CalculatedBunkerData

bunkerType

The type of bunker being analyzed.

bunkered

The amount of the bunker added to the ship between the noon reports, reported data coming from noon report. [metric tons (MT)]

co2Emission

Fuel consumption * emission factor. Every bunker type has a fixed emission factor. [metric tons (MT)]

co2PerMile

Co2Emissions * 1000 / Distance in nm. [kg of CO2/mile]

consumption

The amount of the bunker consumed between the noon reports. [metric tons (MT)]

energyEfficiencyOperationalIndicator

EEOI = CO2Emission * 1000000 / (distance in nm * cargo in tons). [grams of CO2/(tonne-mile)]

rob

The remaining tons of this type of bunker on board, reported data coming from noon report. [metric tons (MT)]

usagePer24Hours

Fuel Consumption*24/(time difference between noon reports) [metric tons (MT)]

usagePerMile

Fuel consumption / distance between noon reports [metric tons (MT)/mile]

usagePerTonnagePerMile

Fuel consumption / (distance in nm * cargo in tons). [metric tons (MT)/(tonne-mile)]

CiiQueryInput

CII query input

imo
Int

IMO number of the ship for which data is returned

from

Date & Time from which the data is requested. Date & Time format should be valid (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ)

to

Date & Time until which the data is requested. Date & Time format should be valid (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ)

extraDistance

Additional distance that can be entered by user. It can be positive, negative or zero. This value is added to the total distance sailed by the vessel before CII is calculated. This is an optional field which can be used to analyze what-if scenarios for CII calculations. [nautical miles (nm)]

extraCO2Emissions

Additional CO2 emissions that can be entered by user. It can be positive, negative or zero. This value is added to the total emissions made by the vessel before CII is calculated. This is an optional field which can be used to analyze what-if scenarios for CII calculations. [MT]

ciiVesselType

CII Vessel Type provided by user (should not be empty or whitespace). This is an optional field which can be used to analyze what-if scenarios for CII calculations. If no user input is provided, CII ratings will be calculated by using vessel type from an internal ship information database.

  • ContainerVessel
  • BulkCarrier
  • Tanker
  • GasCarrier
  • LNGCarrier
  • CruisePassengerVessel
  • RoRoCargoVessel
  • RoRoPassengerVessel
  • RoRoCargoVesselVehicleCarrier
  • RefrigeratedCargoCarrier
  • CombinationCarrier
  • GeneralCargoVessel
deadWeight

Deadweight provided by user (should be greater than zero). This is an optional field which can be used to analyze what-if scenarios for CII calculations. If no user input is provided, CII ratings will be calculated by using deadweight from an internal ship information database. [MT]

grossTonnage

Gross Tonnage provided by user (should be greater than zero). This is an optional field which can be used to analyze what-if scenarios for CII calculations. If no user input is provided, CII ratings will be calculated by using Gross Tonnage from an internal ship information database. [GT]

ratingYear
Int

The rating year provided by user (should be between 2020 and 2026). This is an optional field which can be used to analyze what-if scenarios for CII calculations. If no user input is provided, CII ratings will be calculated for the year mentioned in the “from” field in CII query input.

Draft

aft

Actual Aft draft at the moment the position was measured (or latest available) [meters]

current

Actual mean draft at the moment the position was measured [meters]

fwd

Actual Fwd draft at the moment the position was measured (or latest available) [meters]

Event

imo

IMO number of the ship for which data is returned

eventId

Unique reference ID to an event. An event is either an AIS track point or a noon report.

eventType

“TrackPoint” or “Noon”

location

Latitude and longitude of the AIS or Noon event in decimal degrees. See the “Location” data block for details.

eventDate

Date and Time in UTC of the moment the ship's position was measured for AIS or noon report

insertDate

Date and Time in UTC when this AIS or Noon report was first inserted into Vessel Insights API

updatedDate

Date and Time in UTC when this AIS or Noon report was last updated in Vessel Insights API

customerId
Int

The Salesforce ID of the customer who has sent this noon report. This variable is null for AIS track events. This variable is for DTN internal use only.

sourceType

The source of the noon report (Veslink, Easynoon, Insert Noon API etc.). This variable is null for AIS track events.

noonSource

ID of the noon report in the Position Log API. This variable is null for AIS track events. This variable is for DTN internal use only.

draft

Reported Draft taken from Noon report (Fwd, Aft and Current). This variable is null for AIS track events. See the “Draft” data block for details. [meters]

bunkerData

Reported Bunker data taken from noon reports split by the available bunker types. This is a nested array of data. This variable is null for AIS track events. See the “BunkerData” data block for details. [metric tons (MT)]

observedWeather

Reported Weather data by the vessel in Noon reports. This is a nested array of data. This variable is null for AIS track events. See the “ObservedWeather” data block for details.

cargo

Cargo onboard the ship at the moment the position was measured (as per MRV regulation), taken from Noon reports. This variable is null for AIS track events. [metric tons (MT)]

charterPartySpeed

Reported Charter party speed in noon report. This should be the Charter Party speed of the next leg. This variable is null for AIS track events. [knots]

observedDistance

Distance sailed (over ground) since last noon report, taken from noon reports. This variable is null for AIS track events. [nautical miles (nm)]

steamingTime

Time since last noon report for which vessel was sailing (under way using main engine), taken from noon reports. This variable is null for AIS track events. [hours]

stoppedTime

Time since last noon report for which vessel was stopped (main engine stopped) [hours]

sog

Speed Over Ground (SOG) of the ship at the moment the position was measured [knots]

positionType

The type of ship report

comment

Comments or remarks

mainEngineLoad

Average Main Engine Load since last noon report [kW]

averageRpmLast24Hr

Average Propeller RPM since last noon report [rpm]

scrubber

Is vessel equipped with a Scrubber? True or False.

sailingIn

Non (S)ECA, Fuel Changeover, (S)ECA

voyageId

Customer Identifier of a Voyage

destination

UN LOCATION CODE for transport related locations. Do not include spaces. Example : IEDUB

departure

UN LOCATION CODE for transport related locations. Do not include spaces. Example : NLRTM

condition

Loading condition (Ballast/Laden/Partly Laden) at the moment noon report is created

avgObsSpeed

Average speed over ground (SOG) since last noon report [knots]

facts

Analysis data from AIS and Noon events.

EventFacts

factsType

String identifying the fact type: AIS event facts or noon event facts

weatherAnalysis

Spot weather data from DTN's hindcast weather model for the location and time of the AIS or Noon event. This data is added every hour for the AIS events and for every noon event. This is a nested array of data.

distance

For AIS event, this is the distance traveled from previous AIS track point calculated using rhumbline calculation. For Noon event, this is the distance travelled from previous noon event calculated using rhumbline calculations on the final AIS track. [nautical miles (nm)]

calculatedSog

This is the calculated SOG between this and the previous AIS track point. This is the speed over ground calculated by dividing the distance (traveled from previous AIS track point calculated using rhumbline calculation) with time difference between the two AIS events. [knots]

  • This field is null for noon events.
calculatedPerfSpeed

This is the calculated performance speed between this and the previous AIS track point. Performance Speed is the set speed or the ordered speed by the captain. It is the same as calm water speed. This is calculated from previous AIS track point as calculatedSog + Cx + Wx. [knots]

  • This field is null for noon events.
cx

This is the calculated current effect between this and the previous AIS track point. This is the impact of ocean currents on the ships speed from previous AIS track point calculated using Current data (speed and direction) and ship's course. Positive value of Cx means: current is opposing the ship's speed. So against the vessel is positive and assisting the vessel is negative. [knots]

  • This field is null for noon events.
wx

This is the calculated weather effect between this and the previous AIS track point. This is the impact of weather (wind, waves and swell) on the ships speed from previous AIS track point calculated using weather data, ship's course and digital twin models. Positive value of Wx means: weather is opposing the ship's speed. So against the vessel is positive and assisting the vessel is negative. [knots]

  • This field is null for noon events.
calculatedFuelConsumptionME

This is the calculated Main Engine Fuel Consumption between this and the previous AIS track point. Its calculated using the digital twin model and the performance speed. Calculation assumes that only Heavy fuel oil (HFO) is used during this period. [metric tons (MT)]

  • This field is null for noon events.
calculatedCO2EmissionsME

This is the calculated CO2 emissions from Main Engine between this and the previous AIS track point. Its calculated using the digital twin model, performance speed and HFO and MGO/MDO emission factor as specified by IMO. Calculation assumes that Heavy fuel oil (HFO) is used when ship is outside ECA and MGO/MDO is used when ship is inside ECA. [metric tons (MT)]

  • This field is null for noon events.
timeDifference

For AIS event, this is Time passed since previous AIS event. For Noon event, this is Time passed since previous noon event. [hours]

course

For AIS event, this is the course from previous AIS track point calculated using rhumbline calculation. For Noon event, this is the course from previous Noon report calculated using rhumbline calculation. [clock-wise degrees from true north]

previousEventData

For AIS event, this provides information about previous AIS event. For Noon event, this provides information about previous Noon event. The information about previous event is a nested array of data.

avgSog

For Noon event, this is the average speed over ground calculated by dividing the distance (travelled from previous noon event calculated using rhumbline calculations on the final AIS track) with time difference between the two Noon events. [knots]

  • This field is null for AIS events.
avgCourse

For Noon event, this is the average course from previous noon event calculated using weighted avg. method on the final AIS track from previous Noon to this Noon position. [clock-wise degrees from true north]

  • This field is null for AIS events.
minCx

For Noon event, this is the minimum Cx on the final AIS track from previous Noon to this Noon position. [knots]

  • This field is null for AIS events.
avgCx

For Noon event, this is calculated using weighted avg. of Cx on the final AIS track from previous Noon to this Noon position. Positive value of Cx means: current is opposing the ship's speed. [knots]

  • This field is null for AIS events.
maxCx

For Noon event, this is the maximum Cx on the final AIS track from previous Noon to this Noon position. [knots]

  • This field is null for AIS events.
minWx

For Noon event, this is the minimum Wx on the final AIS track from previous Noon to this Noon position. [knots]

  • This field is null for AIS events.
avgWx

For Noon event, this is calculated using weighted avg. of Wx on the final AIS track from previous Noon to this Noon position. Positive value of Wx means: weather is opposing the ship's speed. [knots]

  • This field is null for AIS events.
maxWx

For Noon event, this is the maximum Cx on the final AIS track from previous Noon to this Noon position. [knots]

  • This field is null for AIS events.
minPerfSpeed

For Noon event, this is the minimum Perf Speed on the final AIS track from previous Noon to this Noon position. [knots]

  • This field is null for AIS events.
avgPerfSpeed

For Noon event, this is calculated using weighted avg. of Performance speed on the final AIS track from previous Noon to this Noon position. [knots]

  • This field is null for AIS events.
maxPerfSpeed

For Noon event, this is the maximum Perf Speed on the final AIS track from previous Noon to this Noon position. [knots]

  • This field is null for AIS events.
isVesselInECA

For both AIS and Noon events, this field indicates whether the vessel is currently operating within an Emission Control Area (ECA)

distanceInECA

For Noon events, this field represents the distance that the vessel has traveled within an Emission Control Area (ECA) since the previous noon event. For AIS events, this field represents the distance that the vessel has traveled within an Emission Control Area (ECA) since the previous AIS event. [nautical miles]

timeInECA

For Noon events, this field represents the amount of time that the vessel has spent within an Emission Control Area (ECA) since the previous noon event. For AIS events, this field represents the amount of time that the vessel has spent within an Emission Control Area (ECA) since the previous AIS event. [hour]

minWeatherAnalysis

For Noon event, this is the minimum weather encountered on the final AIS track from previous Noon to this Noon position.

  • This field is null for AIS events.
maxWeatherAnalysis

For Noon event, this is the maximum weather encountered on the final AIS track from previous Noon to this Noon position.

  • This field is null for AIS events.
avgWeatherAnalysis

Weighted avg. of all weather (wind, wave, swell, current) elements on final AIS track from previous Noon to this Noon position.

  • This field is null for AIS events.
calculatedBunkerData

Bunker usage data split by the available bunker types. This is a nested array of data.

  • This field is null for AIS events.
operationalPhase

Represents the current operational phase of the vessel: NormalCruising, Manoeuvring, Anchored, AtBerth. The operational phase is calculated for every track event in Vessel Insights API using the speed over ground (SOG), the location of the vessel and an internal port/anchorage database.

  • This field is null for noon events.
calculatedFuelConsumptionOther

This is the calculated fuel consumption from auxiliary engines and boilers between this and the previous AIS track point. The calculation is based on digital twin models, operational phase of the vessel on this leg and if the vessel is sailing inside or outside ECA. [metric tons (MT)]

  • This field is null for noon events.
calculatedCO2EmissionsOther

This is the calculated CO2 emissions from auxiliary engines and boilers between this and the previous AIS track point. The calculation is based on digital twin models, operational phase of the vessel on this leg and if the vessel is sailing inside or outside ECA. [metric tons (MT)]

  • This field is null for noon events.

Float

Built-in Float

GetAllEventsQueryInput

List of events query input

imo
Int

IMO number of the ship for which data is requested

from

Date & Time from which the data is requested. Date & Time format should be valid (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ)

to

Date & Time until which the data is requested. Date & Time format should be valid (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ).

eventType

The value can be either “TrackPoint” or “Noon”. User can use this variable to filter AIS track events and Noon report events.

updateSince

This field can be used to get events that have been update or inserted since this date in Vessel Insights API. This can be useful for checking if a noon report has been inserted with a delay or if a noon report was updated by the crew. Date & Time format should be valid (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ).

sort

Can be used to sort results in 'asc' or 'desc' order based on the event time. Default value is 'asc'.

limit
Int

It can be used to set the amount of events returned in one request. Can be any value between 1 to 4000. Default value is 100.

nextToken

Can be added from a previous request to get the next bulk of data. This can be seen as a pagination token.

Int

Built-in Int

ListEvents

items
Array of Event

The main data block in Vessel Insights API which contains data for all the events. See the “Event” data block for details.

nextToken

The pagination token needed to get the next bulk of data from Vessel Insights API.

Location

latitude

Vessel latitude in degrees (North = positive, South = negative)

longitude

Vessel longitude in degrees (East = positive, West = negative)

NoonCii

ciiVesselType

Vessel Type used for CII calculations

deadWeight

Deadweight used for CII calculations [metric tons (MT)]

grossTonnage

Gross Tonnage used for CII calculations [(GT])

totalDistance

The total distance used for CII calculations [nautical miles]

totalCO2Emissions

Total CO2 emissions used for CII calculations [mT]

ratingYear
Int

The year for which CII rating is calculated

attainedCii

The CII (AER) attained with the given calculated inputs [gCO2/capacity.nm]

referenceCii

The reference CII (AER) for 2019 for the selected vessel type and capacity [gCO2/capacity.nm]

requiredCii

The required annual operational CII (AER) for the selected rating year calculated by applying appropriate reduction factor on reference CII (gCO2/capacity.nm)

ciiRating

The CII Rating calculated with the given input A, B, C, D, E

warnings

Contains information about any warnings related to the CII calculation

NoonCiiWarnings

missingNoonReports
Array of String

An array of strings that represents the dates on which noon reports were missing for the vessel.

otherWarnings
Array of String

An array of strings that represents any other warnings related to the CII calculation

NoonSummary

bunkerDataAnalysis

An array of objects that represent the analysis of bunker data for the vessel in the requested time range. This analysis is based on data from noon reports.

totalObservedDistance

The total observed distance traveled by the vessel. This is calculated by adding the sailed distance data from noon reports. [nautical miles]

totalCO2EmissionsAllFuel

The total amount of CO2 emissions produced by the vessel, based on all fuel consumption data from noon reports. [mT]

warnings

An object that contains information about any warnings related to the noon summary calculations.

NoonSummaryWarning

missingNoonReports
Array of String

An array of strings that represents the dates on which noon reports were missing for the vessel.

ObservedWeather

seaHeight

Reported Wave Height in noon report. [meters]

swellDirection
Int

Reported Swell Direction in noon report (nautical convention). [degrees]

currentDirection
Int

Reported Current Direction in noon report (nautical convention). [degrees]

pressure

Reported Pressure in noon report. [hPa]

currentSpeed

Reported current speed in noon report. [knots]

windSpeed
Int

Reported wind speed at 10 meters in noon report. [knots]

swellHeight

Reported Swell Height in noon report. [meters]

windDirection
Int

Reported wind direction at 10 meters in noon report (nautical convention). [degrees]

PreviousEventData

location

Latitude and longitude of the previous AIS or Noon event

eventId

Unique reference ID of the previous AIS or Noon event

eventDate

Time when previous AIS or Noon report was generated in UTC format

eventType

Noon or AIS Track Point

noonSource

ID of the previous noon report in the Position Log API (for internal use only). Only returned for noon events.

isVesselInECA

This field indicates whether the vessel was operating within an Emission Control Area (ECA) during the previous AIS or Noon event.

Sort

object
asc
object
desc

String

Built-in String

SummaryQueryInput

Summary query input

imo
Int

IMO number of the ship for which data is returned

from

Date & Time from which the data is requested. Date & Time format should be valid (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ)

to

Date & Time until which the data is requested. Date & Time format should be valid (YYYY-MM-DDThh:mm:ss.sssZ or YYYY-MM-DDThh:mm:ssZ)

TimeRange

from

Starting time of a time period for which AIS track data is not available.

to

End time of a time period for which AIS track data is not available.

TrackCii

ciiVesselType

Vessel Type used for CII calculations

deadWeight

Deadweight used for CII calculations [metric tons (MT)]

grossTonnage

Gross Tonnage used for CII calculations [(GT])

totalDistance

The total distance used for CII calculations [nautical miles]

totalCO2Emissions

Total CO2 emissions used for CII calculations [mT]

ratingYear
Int

The year for which CII rating is calculated

attainedCii

The CII (AER) attained with the given calculated inputs [gCO2/capacity.nm]

referenceCii

The reference CII (AER) for 2019 for the selected vessel type and capacity [gCO2/capacity.nm]

requiredCii

The required annual operational CII (AER) for the selected rating year calculated by applying appropriate reduction factor on reference CII (gCO2/capacity.nm)

ciiRating

The CII Rating calculated with the given input A, B, C, D, E

warnings

Contains information about any warnings related to the CII calculation

TrackCiiWarnings

missingAisTrack
Array of TimeRange

An array of TimeRange objects that represent time periods in which AIS tracking data is not available.

otherWarnings
Array of String

An array of strings that represents any other warnings related to the CII calculations.

TrackSummary

distance

Total distance travelled by the vessel. This is calculated using normalized AIS track. [nautical miles]

distanceInsideECA

Total distance travelled by the vessel inside Emission Control Area (ECA). [nautical miles]

distanceOutsideECA

Total distance travelled by the vessel outside Emission Control Area (ECA). [nautical miles]

timeInsideECA

Total time spent by the vessel inside Emission Control Area (ECA). [hour]

timeOutsideECA

Total time spent by the vessel outside Emission Control Area (ECA). [hour]

fuelConsumptionMEInsideECA

Total estimated fuel consumption of the vessel's main engine inside an Emission Control Area (ECA). [mT]

fuelConsumptionMEOutsideECA

Total estimated fuel consumption of the vessel's main engine outside of an Emission Control Area (ECA). [mT]

otherFuelConsumptionInsideECA

Total estimated fuel consumption of auxiliary engines and boilers inside an Emission Control Area (ECA). [mT]

otherFuelConsumptionOutsideECA

Total estimated fuel consumption of auxiliary engines and boilers outside of an Emission Control Area (ECA). [mT]

cO2EmissionsME

Total estimated CO2 emissions generated by the main engine of the ship. [mT]

cO2EmissionsMEInsideECA

Total estimated CO2 emissions generated by the main engine of the ship when the vessel is inside an Emissions Control Area (ECA). [mT]

cO2EmissionsMEOutsideECA

Total estimated CO2 emissions generated by the main engine of the ship when the vessel is outside of an Emissions Control Area. (ECA) [mT]

otherCO2Emissions

Total estimated CO2 emissions generated by auxiliary engines and boilers. [mT]

otherCO2EmissionsInsideECA

CO2 emissions generated auxiliary engines or boilers, when the vessel is inside an Emissions Control Area (ECA) [mT]

otherCO2EmissionsOutsideECA

Total estimated CO2 emissions generated auxiliary engines or boilers, when the vessel is inside an Emissions Control Area (ECA). [mT]

cO2Emissions

Total estimated CO2 emissions generated by the ship, including both the main engine and other sources. [mT]

warnings

Provides information about potential issues or warnings related to the ship's track summary calculations.

TrackSummaryWarning

missingAisTrack
Array of TimeRange

An array of TimeRange objects that represent time periods in which AIS tracking data is not available.

WeatherAnalysis

windSpeed10m

The speed of the wind at 10 meters above sea level, averaged over 10 minutes [knots]

windDirection10m

The direction from which the wind is blowing at 10 meters above sea level [degrees]

seaWaveHeight

significant height of the wind waves [meters]

seaWavePeriod

mean period of the wind waves [seconds]

swellHeight

significant height of the swell waves [meters]

swellDirection

The mean direction from which swell waves are coming [degrees]

swellPeriod

mean period of swell waves [seconds]

significantWaveHeight

The total significant wave height, i.e. of all waves [meters]

currentSpeed

The mean speed with which water is moving at sea surface level [knots]

currentDirection

The mean direction into which water is moving at sea surface level [degrees]