Report Operations

Gathering historical data is essential for analyzing the causality of past events. The API facilitates this by providing easy access to historical data through the creation and modification of reports. By reviewing and analyzing these reports, users can identify the underlying causes of specific events.

This article will cover the creation of reports and how to view their output:

• Create a report
• Get Output from a Specific Report

The base url for the mentioned endpoints throughout the article is:

https://demo.ghmaritime.com/api/jobserver

Create a Report

There are several types of reports that can be created through the API; their functionality is similar regarding the construction of the request body, however they differentiate in some fields and of course their endpoints.

Every request body should include the following fields:

{
  "name": "{name}"
  "begin": "{year}-{hour}-{minute}T{hour}:{minute}:{seconds}Z",
  "end": "{year}-{hour}-{minute}T{hour}:{minute}:{seconds}Z",
}

The types of reports are listed below, along with their respective endpoint and what they require as extra in their request body:

• Multiple Ship report
  • POST: /stat/multiship
  • Body:
    • ships: List of ship identifiers, i.e. mmsi, imo, etc.
• Port Calls Report
  • POST: /stat/portcalls
  • Body:
    • mmsi: List of ship identifiers as their mmsi definition.
    • shiplist: The id of a predefined shiplist.
    • ports: List of port identifiers, i.e. locode or name
• SOG Distribution Report
  • POST: /stat/sogdist
  • Body:
    • mmsi: List of ship identifiers as their mmsi definition.
    • shiplist: The id of a predefined shiplist.
    • stopped_sog: SOG trigger value as a float number, i.e. 1.1.
• Fishing Report
  • POST: /stat/fishing
  • Body:
    • min_duration: the minimum run time for the report.
    • shape: The GeoJSON definition of the specified area.
    • a_team: List of mmsi values.

When a report has been created, the API will respond with a JSON object containing the id of the created report, which can then be used to get the specification of the report or its’ result. To read more about this, see Get Output from a Specific Report

Visualization of creating a report:

Get Output from a Specific Report

To get the output from a specific report, the id of the report is needed; if the id is unknown or no report has been created beforehand, follow the steps at Create a Report.

There are two endpoints to get output from a specific report, the first is to get the specification of the report;

/stat/{type}/{id}

the second is to get the result of the report:

/stat/{type}/result/{id}

Please note that a report must be completed before its result is available, which may take a few minutes after its creation.

The {type} value in the URLs should be replaced with one of the following values:

• passageline
• nmss
• nmsp
• area
• multiarea
• historicaltrack
• trip
• multipassageline
• multiship
• sogdist
• portcalls
• transitpilot
• fishing

The API will respond with a JSON object that contains a record list of what happened during the specified time frame of the report.

Visualization of getting the report definition:

Visualization of getting the report result: