Report

This endpoint provides details on the inputs and outputs of operations used to create a report and get the result of a specific report.

Content Overview:

• Create a Report
• Get Output from a Specific Report

The base URL for the endpoints throughout the article is:

https://mdmdemo.gatehousemaritime.com/api/jobserver

POST /stat/{shiptype}

To create a report, construct a POST request via the endpoint /stat/{shiptype} where the request body contains information about the ship.

POST /stat/{shiptype}

Every request body should include the name- and beginning and end of the report, which is the following fields:

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

However, if the report requires a GeoJson definition, then this should also be provided.

{
  "name": "{name}"
  "begin": "{year}-{month}-{day}T{hour}:{minute}:{seconds}Z",
  "end": "{year}-{month}-{day}T{hour}:{minute}:{seconds}Z",
  "shape": {
    "type", "{type}",
    "coordinates": [
      {GeoJson-coordinates}
    ]
  }
}

It should be noted that the variable GeoJson-coordinates, should be formatted in 2D arrays.

There are several types of reports that can be substituted for the variable {shiptype}, the following is a list of report types:

• multiship
• portcalls
• sogdist
• fishing
• historicaltrack (requires shape)

They can all be used for the endpoint URL, i.e. /stat/multiship, depending on desired the type of report.

The request body varies based on the selected type. To see the differences, refer to the, ‘Create a Report’ use case.

The multiship report type is chosen for the code example in this article.

The following is a list of parameters that can be altered in the code:

• <credentials>
  • Your username and password for authentication as Base64-encoding
• <ReportName>
  • Name of the report to be created
• “begin”
  • The timestamp describing when a report should begin.
• “end”
  • The timestamp describing when a report should end.
• “ships”
  • A list containing

Code Example:

import requests
import json

URL = f'https://demo.ghmaritime.com/api/jobserver/stat/multiship'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
    "name": "<ReportName>",
    "begin": "{year}-{month}-{day}T{hour}:{minute}:{seconds}Z",
    "end": "{year}-{month}-{day}T{hour}:{minute}:{seconds}Z",
    "ships": [
        "<mmsi1>",
        "<mmsi2>",
        ...
    ]
}

response = requests.post(URL, json=payload, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response Sample:

{
  "id": 3181399200581436
}

This response indicates that the MDA system has successfully created the report.

GET /stat/{shiptype}/result/{id}

To get the output from a specific report, construct a GET request to the /stat/{shiptype}/result/{id} endpoint.

GET /stat/{shiptype}/result/{id}

It should be noted that the report needs to finish computing, before it is possible to get the result of it. If the status code of the response is 202, it means that either the job is not finished or it has been aborted.

To check whether the job is running or aborted, construct a GET call via the endpoint /stat/statistic/{id} and check the status field of the job.

GET /stat/statistic/{id}

This should show whether the job is running, has been aborted or is finished. If the job is currently running, it should display the progress in percentages.

The API will respond with a JSON formatted response, containing a list of events that occured in the report.

The following example uses a passageline report to get a result.

Code Example

import requests
import json

URL = (
    f"https://demo.ghmaritime.com/api/jobserver/stat/passageline/result/{id}"
)
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response Sample

{
    "records": [
        {
            "distance": 365109,
            "left": true,
            "position": {
                "coordinates": [
                    7.345911162594656,
                    55.47363500313613,
                    "2025-07-23T11:43:54Z",
                    162.2,
                    10.4
                ],
                "extensions": [
                    "time",
                    "cog",
                    "sog"
                ],
                "type": "Point"
            },
            "ship": {
                "a2": "FI",
                "callsign": "OJHF",
                "destination": "GBIMM",
                "draught": 6.0,
                "eta": "2025-06-11T15:45:00Z",
                "imo": 9122007,
                "length": 138,
                "mmsi": 230357000,
                "name": "BORE BAY",
                "shiptype": 79,
                "width": 23
            }
        },
        {
            "distance": 93173,
            "left": true,
            "position": {
                "coordinates": [
                    7.312168933281242,
                    57.915643056859864,
                    "2025-07-23T11:14:47Z",
                    92.6,
                    6.9
                ],
                "extensions": [
                    "time",
                    "cog",
                    "sog"
                ],
                "type": "Point"
            },
            "ship": {
                "a2": "FO",
                "callsign": "OZ2158",
                "destination": "FUGLAFJORDUR",
                "draught": 6.1,
                "eta": "2025-07-19T04:00:00Z",
                "imo": 9129122,
                "length": 90,
                "mmsi": 231522000,
                "name": "HAV ATLANTIC",
                "shiptype": 70,
                "width": 14
            }
        },
    ]
}