# Overview

# 1 - Short Description of the API

Best For: BCOs and NVOs who need real-time container tracking from the moment the empty container leaves the depot (export side) to when it is returned empty (import side). Valid for dry containers. Regions: Global Purpose: Real-time container tracking for Port to Port, door to door and port to door booking across all transport legs (pre-carriage, ocean leg, and on-carriage).

# 2 - Long Description of the API

# 2.1 - Introduction

Our smart container fleet takes the tracking experience to a new level: Live Position enables our customers to track their container in real -time throughout the entire journey. From ship to rail to truck – they benefit from full visibility no matter which mode of transport is used.

# Features:

  • Push API: Real-time data is pushed directly to your system.
  • Real-Time Data: Longitude and latitude data of containers.
  • Data coverage: The data coverage starts from the gate-out event when the empty container leaves the export depot and continues until the gate-in event when the empty container is returned to the import depot. The data transmission starts and end automatically.
  • Frequency: Pre- & On-Carriage: Updates every 15 minutes. Ocean Leg: Updates every 24 hours.
  • Covers all legs of the journey (pre-carriage, ocean, on-carriage).
  • Designed for seamless integration with your system.
  • This API is based on DCSA IoT events standard

# 2.2 - Description of the API Use Cases

This Push API improves supply chain visibility by automating container tracking data delivery at the specified frequency, enabling you to streamline operations and enhance customer experience.

  • Leverage the dot-on-the-map in the customer’s internal platform (i.e. Transport Management System e.g. Cargowise or Enterprise Resource Platform e.g. SAP)
  • Create value-added services and products to the customer’s end users
  • Enhance internal operational efficiency, i.e. yard management, reduce empty miles
  • Data-driven decision making and improved planning e.g., street turns, automated warehouse gate scheduling.
  • Create geofence events on gate-in and gate-out movements on your customer premise

# 2.3 - How the API works

# Who can get access?

Hapag Lloyd customers, freight forwarders and their partners acting on behalf of the Hapag Lloyd customers can get access to the API. While many customers are eager to leverage this data to optimize their supply chains, we will initially collaborate with pilot customers who commit to tracking at least 5,000 containers per year using this API. This focused approach allows us to gather valuable feedback and further refine and optimize the API for broader usage in the future.

# What are the different authorizations available?

Oauth 2.0, Static API key, cryptographic secrets (recommended by DCSA), Bearer tokens

# How many calls I can make?

We configured the rate limit for subscription management calls to allow for handling all the business volume for both on-demand and automatic subscriptions. Push mechanism is not rate limited, so you should expect to receive all events for your containers within their shipment journey with the standard frequency (Pre- & On-Carriage: 15 minutes / Ocean Leg: 24 hours)

# How to buy and pay live position API?

Customers who have purchased Live Position API contract may integrate to our API Portal. To obtain Live Position API Packages offer please contact your respective account managers: https://www.hapag-lloyd.com/en/services-information/offices-localinfo.html Please reach out to liveposition@hlag.com for further queries.

# What are the different subscription options?

  1. On-Demand Shipment Customers can purchase the Live Position API for a specific shipment. This allows them to receive real-time data for all containers associated with the selected shipment reference.
  2. All Shipments Customers can opt to receive real-time data automatically for all their shipments. This includes every shipment booked with Hapag-Lloyd, provided the service is active for the agreed contract period (e.g. one year).

# Invoicing Details

The invoicing is based on the number of containers tracked. Charges for the Live Position API are included as a value-added service (VAS) within the sea freight invoice. The freight payer of the sea freight is also responsible for covering the costs associated with the Live Position API.

# Subscription Process:

  1. Customers initiate a subscription by providing their Hapag-Lloyd Shipment number or all shipment reference.
  2. This subscription request is sent to our system, where it is processed and recorded.
  3. The customer subscribes to get Live Position data for dry containers.

# POST Request for subscription:

{
 "callbackUrl": "https://www.test.com",
    "callbackCredentials": {
        "apiKeys": [
            {
                "apiKeyName": "x-ibm-client-id",
                "apiKeyLocation": "header",
                "apiKeyValue": "abcd1234abcd1234abcd1234abcd1234"
            },
            {
                "apiKeyName": "x-ibm-client-secret",
                "apiKeyLocation": "header",
                "apiKeyValue": "abcd1234abcd1234abcd1234abcd1234"
            }
        ]
    },
  "eventType": "IOT",
  "carrierBookingReference": "12345678"
}

# Response (200):

{
    "subscriptionID": "1a1a12a1-123a-12avf-12a1-ab123a1a1234",
    "subscriptionCreatedDateTime": "2024-01-02T03:04:05Z",
    "subscriptionUpdatedDateTime": "2024-01-02T03:04:05Z",
    "carrierBookingReference": 12345678,
    "subscriptionStatus": "ACTIVE"
}

# Data Push Mechanism:

  1. Our system will regularly gather relevant data or updates related to the specified shipment and container numbers.
  2. Based on the frequency mentioned above, our system will push this data to the specified URL provided by the customer.

# 3.1 - Change log

# 3.2 - Product Roadmap

Yes! We are currently working on an exciting solution that will provide predictive ETA for each milestone in real-time using AI and machine learning. This feature is planned to be available by Q2 2025. Stay tuned!

# 3.3 - FAQs

# What dry container types are supported by the Live Position API?

  • The following container types are valid:
    • 22GP: General Purpose Container without Ventilation
    • 22UT: Open-Top Container
    • 25UT: Open-Top Container High Cube
    • 42GP: General Purpose Container without Ventilation
    • 42UT: Open-Top Container
    • 45GP: General Purpose Container without Ventilation
    • 45UT: Open-Top Container High Cube

# If I opt for on-demand shipment tracking, how can I buy this product for a specific shipment?

  • You can raise a subscription API call using the Hapag-Lloyd shipment reference in the subscription request. You will receive a subscription confirmation message instantly via the API. There is no need to mention the VAS in the booking process, include it in remarks, or manually purchase the product through the Hapag-Lloyd Online Business Suite.

# How do I handle scenarios where IoT data is not available?

  • In case IoT data is unavailable due to a technical failure or device unavailability, the API will return an error message indicating the issue. This ensures transparency and allows you to handle such cases programmatically.For specific IoT-equipped containers that are not released, the charges are automatically reversed by the system.

# What is the subscription buy window for a specific shipment if I opt for on-demand shipment tracking?

  • You can subscribe to this product anytime from the moment the booking is created until the empty container has been picked up from the depot for the specific shipment. This is because we need to inform the depot in advance to ensure that the smart container is released for the shipment that the customer wishes to track.

# How is invoicing handled for Live Position API?

  • Invoices are based on the number of containers tracked. The Live Position API charges are added as a value-added service (VAS) to the sea freight invoice. The freight payer of the sea freight will also pay for the Live Position API charges.

# Even though I book port-to-port shipping (only vessel leg) with Hapag-Lloyd, will I get complete real-time visibility of the end-to-end transport?

  • Yes, that’s the main pain point we aim to solve with this API. We want to share the data starting from the moment the container leaves the export depot until it is returned to the empty depot on the import side. You will receive end-to-end visibility, including the pre-vessel leg, vessel leg, and post-vessel leg.

# If we want to opt for All Shipments, how will this data be sent to our backend? What effort is needed from us?

You only need to perform a one-time subscription to provide your endpoint where the data will be channeled. This can even be done using a simple Postman call. Once the contract is finalized, our IT system will automatically detect all newly created shipments. Subscriptions will be created seamlessly, and you will start receiving the data for every dry container directly into your backend automatically.

# How would I know the first and last position of a specific container?

You can use the iotEventTypeCode from the payload: For the first message of the container, the code is "TRS". For the last message, the code is "TRF".