Introduction

What is the Onshore API about?

Access your Hoppe sensor and system data anytime via our cloud-based API, facilitated by our Data Butler and Data Inspector Services for ship-to-shore data transmission. Seamlessly integrate your sensor data with your preferred platform or data warehouse. Our API follows industry-standard RESTful architecture, ensuring straightforward data access and integration

Who is the Onshore API specification for?

The Onshore API specification is geared towards developers, data analysts, and other onshore professionals engaged in integrating sensor and system data. For monitoring transmission status, ensuring data quality, troubleshooting, and occasional data downloads, please utilize our Fleet Connect portal.

What does the API feature?

The API enables seamless integration of sensor data, offering access to vessel details, metadata for sensor and system notifications, and the ability to export sensor data as time-series data, along with system notifications represented as an event log.

Use Cases for data integration:

• Data Integration. Seamlessly feed data into your own data warehouse and analytic tools for comprehensive analysis.

• Verification Integration. Integrate your data to validate manually reported data and emission reporting, ensuring accuracy and compliance.

• Case Study Development. Utilize your data to develop case studies, validating retrofits and energy-saving devices for enhanced efficiency and performance.

• Hull Evaluation. Employ our data to feed your hull models, facilitating the evaluation of hull fouling and optimizing vessel performance.

Feel free to explore additional applications beyond these examples!

Service & Support

Our dedicated data solution team comprises experienced data analysts, developers, and maritime experts. Whether you have inquiries, encounter technical issues, require familiarization with our API, or need support for your project and integration, our team is here to provide assistance and guidance tailored to your needs.

Get access

How can I create and register a user account?​

To use the Onshore API and our Fleet Connect Portal you must request and register an user account first. Please contact the user group administrator of your organization, alternatively send your request for a new user account to datasolutions@hoppe-marine.com

Afterwards, you will receive a One-Time Password for activating your account. To activate your account please login with the one time password and set a new password. With the registered email address and the new password, you are now able to access the Fleet Connect portal.

I have activated an user account but I don't have access to data. How do I get access to vessel data?

In order to obtain access to the data of a specific ship you must either contact the administrator of the data ownner or contact the Hoppe Support at datasolutions@hoppe-marine.com. In the latter case, we kindly ask you to prove your identity and request access to the data. Please describe your use case, list the email address with which you are registered and list the IMO numbers of the vessels you were granted access to by the data owner. The Hoppe Support will contact the data owner to verify the legitimacy of your request.

As user group administrator, you can grant access to your ships by inviting users to Fleet Connect portal. You can also create subgroups to manage fine-grained control over your ships.

How can I create or manage my API key to use the Onshore APIs?​

Before you can use our Onshore API you need to create an API key first.

In the Fleet Connect portal, click on the "burger menu" in the top right corner and select "Manage API Keys". This will open a small window with a simple interface for creating and invalidating API keys. To create a new key, click on the "New API Key" button. You will be prompted to give the API key a description. We recommend giving your API keys meaningful descriptions to easily identify them for different purposes later on.

How to use the API key?

A valid API key must be provided in the Authorization header with each API request, following the format:

Authorization: ApiKey <API-KEY-VALUE>

Example Python code:

import os
import requests

IMO = "...IMO-NUMBER..."
API_KEY = "...API-KEY-VALUE..."
API_URL = "https://api.hoppe-sts.com/"

request_url = f"{API_URL}fleet/{IMO}/timeseries?from_date=2024-05-01T13:00:00&to_date=2024-05-01T14:00:00"
response = requests.request("GET", request_url, headers={"Authorization": f"ApiKey {API_KEY}"})

We recommend rotating API keys on a regular basis. A once per year rotation is expected to provide decent security with a medium level of effort. API key rotation is simple. Just create a new API key as mentioned above.

Afterwards, distribute this new API key to your applications and make sure the applications can use the new key successfully. In a next step head to the API key management console and deactivate the old key.

Testing the APIs​

We know that figuring out how to use APIs can be cumbersome. Therefore we'll walk you through a few useful API calls to get you started in below FAQ section.

Are there limits using the APIs?

Typically, each API has a usage limit set for each user account. The usage plans are flexible enough that most users should not hit any limits. These limits are meant as a technical pre-caution to limit load on our server, in particular in case of software bugs. In case you do hit a Limit exceeded (status code 429) error please reach out to datasolutions@hoppe-marine.com. Given your specific use-case, we will assist you to solve the problem and will increase the quota if required.

Currently, the default limits are set as follows:

The API grants only access to data covered by your contract period. The API may respond with status code 402 to indicate access limitation due to limited contract period.

You can access the contract overview via Fleet Connect portal: Select the burger menu on the top right and choose Contract List. Note: The "From & To" periods in the Contract List do not always correspond with the contract's official start and end dates. For instance, the official contract might start after the From date if certain conditions, such as unresolved points after commissioning, need to be addressed.

FAQ

I have a technical issue or need assistance with implementing the API. Whom to contact at Hoppe?

For everything related to our APIs and to our Fleet Connect Portal please contact datasolutions@hoppe-marine.com.

I need to get a list of vessel I have access to. Which endpoint do I need to use?

To derive a complete list of vessel you have access to please use the ship information endpoint from our onshore Fleet API.

• Example URL for the GET request: https://api.hoppe-sts.com/fleet/1234567/signals
• Please replace 1234567 with a valid IMO number and add a valid API Key to the request header :::

Are there metadata (units, description, limits,...) available for the signals? 

Yes, the signal list contains additional information which describes the signals.

The most important metadata is included in the so-called machine code. The machine code is unique, serves as a signal id and also describes some of the properties of the signal.

After the machine code, the friendly name is the second most important metadata: it contains a human readable, friendly description of the signal. For more information about the metadata, check the Fleet API documentation.

I like to export time series data of vessel. Which Endpoint shall be used?

Please use our time series endpoint to export time series data by stating the IMO number of the vessel. You can extend the query by defining a certain period or certain signals. Regarding any limitations please check the question "Which limitations do I need to consider when calling the time series endpoint?"

Which limitations do I need to consider when calling the time series endpoint?

Due to the high amount of data which can be expected from the time series endpoint the following limitations must be taken into account:

• You can query all signals for a period of up to 24 hours
• You can query up to 50 signals for a period up to 30 days.

How frequently is the data updated?

How often data is being updated strongly depends on the export settings and the connectivity of the vessel itself. With standard export settings data is updated every 5 minutes or every hour. In case the vessel is offline or is facing a weak internet connection data will be transferred as soon internet connection allows it again. To monitor the online status of the fleet please check our Fleet Connect portal.

Once received on our cloud server, can data from the vessel be edited or deleted?

It is not possible to edit or delete data onboard by the crew or onshore by users. Data will never be edited in the cloud. In rare cases data might be deleted by Hoppe in close coordination with our customers e.g. cleaning up faulty data.

Can signal list be changed?

Yes, signal list might be changed in rare cases. The signal list is depending on the export configuration of the vessel. This configuration usually doesn't change after successful commissioning.

In which cases is the vessel list being changed or updated?

Whenever a vessel is added or leaving the fleet the vessel list is updated accordingly. If a vessel is already online and commissioned but not available through the API or in the Portal this might indicate a missing service contract.

Is it possible to change the output format of timeseries endpoint like changing structure, signal names or units?

Yes, there are options to export data in different formats. This is limited to our major partners or can be done on request.

I like to export system notifications received by the vessel. Is that possible?

Yes, the system notifications (alerts, sometimes also refert to as HOWAF events) can be exported with the event notifications endpoint.