What Are Tradelens Query APIs : Consignment Queries

TradeLens offers customers query APIs (Trade Object APIs) that can be used to feed your system’s applications with TradeLens data in JSON format. These APIs are a great choice for web applications or systems that can call APIs.

In this article

The TradeLens query APIs are published to the public on our swagger page. There you will see five groups of APIs on the Swagger page, but in this article, we will only mention the Consignment Query. 

Before you read this section, it is expected that you already understand the Tradelens Data Event Model. You can learn about this here.

Consignment Queries APIs

This group has five APIs that will return a JSON payload or CSV file with the basic information of the ocean carrier booking/consignment. In this document, we will only talk about the three most important APIs, but you can get the full APIs list on our swagger page.

The most important API of this group is the API:  /api/v2/consignments, which will provide you with basic information about the consignments/ocean carrier bookings, together with the 'consignmentId' and 'transportEquipmentId' that will be used to call the APIs in the “Transport Equipment Queries” group.

Below are the three main Consignment APIs

API GET - https://platform.tradelens.com/api/v2/consignments

The API consignment should be the first API to be called when your system needs to receive a JSON payload with the basic information of the ocean carrier booking/consignment and the consignmentId and transportEquipmentIds that will be used to call the APIs on the “Transport Equipment Queries” group.  

This API allows you to use filters to specify the data you expect. Here is an example of a URL with filters added to search for a consignment relate to a specific container number: https://platform.tradelens.com/api/v2/consignments?size=50&equipmentId=MAEU1234567

More information and payload samples are available at: https://platform-sandbox.tradelens.com/documentation/swagger/?urls.primaryName=Trade%20Object%20API

API GET - https://platform.tradelens.com/api/v1/consignments/events/consignmentId/{consignmentId}

This API will return a JSON payload listing all the events published on the consignment/booking level, which are the events "Consignment created/updated", "Consignment visibility added" (parties with access to the consignment), and all planned events that will build the transport plan for each consignment.

API GET - https://platform.tradelens.com/api/v1/consignments/transportSummaries/consignmentId/{consignmentId}

This endpoint will return all the transport plans for the consignment, ordered from most recent to oldest. Each transport plan will include a list of planned events, ordered by the event occurrence time.

Together these events indicate the series of locations that each transport equipment, that is associated with the given consignment, will move on its journey. The planned events sequence in the transport plan will be indicated by the JSON key “sequence” provide at each array.

Also, all event types can be published more than once when more than one Tradelens Network Member is publishing the same event to the same consignment, so all events will have a JSON Key named “eventPriority” to inform that level of priority this event should have over others.