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. For the time beeing, we kindly ask you to 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 both the Hoppe Fleet Data Service Portal and the API Developer 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 contact the Hoppe Support at datasolutions@hoppe-marine.com, 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. Afterwards, your user account will be granted access to the specifically requested data via the Onshore API.

To see which ships' data your account has access to, sign into to the DOCS PORTAL refer to the section Accessible Ships under the User Details or check the vessel list in Fleet Connect Portal.

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. Therefore sign into the API Developer Portal and navigate to the API Key Management tab that provides a list of all your active API keys. Here you add new keys or disable API existing ones.

A new API key can be generated with the Add New API Key button. We suggest following the practice of giving your API keys meaningful descriptions in order to easily identify API keys with different purposes later on. After giving an API Key Description, click on ADD API KEY. An obscured API Key Value is returned, and can be revealed by clicking on the eye icon.

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, APIs have a usage limit set for each user account. The usage plans for our Onshore API is flexible enough, so that most users should not hit any limits. In case you do encounter a Limit exceeded error on any of the Onshore API calls, please reach out to datasolutions@hoppe-marine.com in order to define a custom usage plan to serve your needs.

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.

I like to know which signals are available for a certain vessel?

Please use our signal mapping endpoint by stating the IMO of the respective vessel as a parameter. The endpoint will return a list of signals which are currently being transferred by the vessel ashore. The return includes signal metadata like friendly names, units, limits and groups which will help you to identify the right signals for your purpose.

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.