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 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:

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?"