What Are Tradelens Query APIs : Transport Equipment 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 Transport Equipment Query. 

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

 

Transport Equipment Query APIs

The Transport Equipment Queries APIs group has the APIs that will return a JSON payload listing all the events published by Tradelens Network Members (Ocean Carriers, Ports, Customs….) on the container level. The Container level is the data published on TradeLens that are related to a specific container and not on the Consignment level. All the APIs on this group will require either the 'consignmentId' or the 'transportEquipmentId'. These IDs can be received by calling the API https://platform.tradelens.com/api/v2/consignments explained here.

 

 

 

 

Current Progress APIs

The current progress APIs will return a list of current progress events, ordered by the sequence in which they occur. Together these events indicate the series of locations that each transport equipment will move, or has moved, on its journey and everything that happened along the way. Each current progress event is made up of either a list of actual events, a list of estimated events and the associated planned events, or a generic event.

Transport events are divided into three categories: planned, estimated, and actual. Planned events provide the planned route of transport equipment. Estimated events provide the estimated time things will occur to the transport equipment. Actual events indicate things that occurred to the transport equipment.

Note: the only events returned by this endpoint are either the set of events known as "transport" events or some "generic" events.

The following is the list of generic events that will be supported by the Current Progress API:

• doNotLoad
• carrierRelease
• containerReadyForPickup
• customsRelease
• terminalRelease
• vgmReceived
• vgmSubmitted

This response does NOT include consignment, transport equipment, most generic, or document events. For a complete list of transport events, see the Transport Events category in the Event Publish Swagger documentation. To get all events for a consignment or transport equipment, use the …/events/... endpoint.

Commodity and originator information visibility is restricted to organizations that were onboarded with certain types. If your organization (org) does not have one of these approved types, then you may not have visibility to the following fields in each event:

• Commodity information:
• harmonizedCodes
• commodities.commodityDescription
• commodities.commodityHarmonizedCode
• Originator information:
• originatorName
• originatorId
• senderOrgId

In addition, the originator information on a Party Add/Update/Remove event will be hidden if you are not the org who submitted the event or one of the parties being added. The originator information and 'destinationOrgName' field on a Document event whose 'action' field is 'issued', 'transferred', or 'surrendered' will also be hidden if you are not the org who submitted the event or the org that the document is being transferred to.

 

The three “current progress” APIs:

API GET -  https://platform.tradelens.com/api/v1/transportEquipment/currentProgress/consignmentId/{consignmentId}

This API returns the current progress of all transport equipment associated with that consignment.

 

API GET - https://platform.tradelens.com/api/v1/transportEquipment/currentProgress/transportEquipmentId/{transportEquipmentId}

This API returns the current progress of the transport equipment related to the transportEquipmentId provided at the end of the URL.

 

API GET - https://platform.tradelens.com/api/v1/transportEquipment/currentProgress/splitFromConsignment/{consignmentId}

Ocean Carriers may split a booking into two or more additional consignments, so this API returns the current progress for all of the transport equipment split from the consignment that is not yet associated with another consignment. You will need the consignmentID to call this API.

 

 

Transport Summary APIs

Transport Plan Analysis: This endpoint will construct an up-to-date transport summary for each transport equipment returned by the query. This transport summary will include a list of transport plan events, ordered by the sequence in which they occur. Together these events indicate the series of locations that each transport equipment will move, or has moved, on its journey and everything that happened to it along the way.

Transport events are divided into three categories: planned, estimated, and actual. Planned events provide the planned route of transport equipment. Estimated events provide the estimated time things will occur to the transport equipment. Actual events indicate things that occurred to the transport equipment.

The event filter parameter can be used to control the processing done in the transport plan analysis.

• Latest - The transportPlanIssuanceTime8601 will be used to determine the most recent transport plan. All Actual events will be returned, no filtering is done. For Estimated events, the location, the eventSubmissionTime, the 'originatorID', and the 'fullStatus' fields will be used to determine the most recent version of the event. Estimated events will be replaced by the corresponding Actual events. The resulting list will contain the Planned event (if there is one) followed by the Actual or Estimated (if not Actual).
• All - All the transport plans sent to this 'trade object' will be returned, from most recent to oldest. Each transport plan will have a version, the transport plan issuance date, and the name of the organization that sent the plan, along with the list of Planned events.

 

 

 

Commodity and originator information visibility is restricted to 'orgs' that were onboarded with certain types. If your org does not have one of these correct types, then you may not have visibility to the following fields in each event:

Commodity information:

• harmonizedCodes
• commodities.commodityDescription
• commodities.commodityHarmonizedCode

Originator information:

• originatorName
• originatorId
• senderOrgId

In addition, The originator information on a Party Add/Update/Remove event will be hidden if you are not the org that submitted the event or one of the parties being added. The originator information and 'destinationOrgName' field on a Document event whose 'action' field is 'issued', 'transferred', or 'surrendered' will be hidden if you are not the org who submitted the event or the org that the document is being transferred to.

 

The three “transport summaries” APIs:

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

This API  Returns the transport summary of all transport equipment/containers associated with the 'consignmentID' provided in the URL.

 

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

This API returns the transport summary for all of the transport equipment/containers split from the consignment that is not yet associated with another consignment.

 

API GET - https://platform.tradelens.com/api/v1/transportEquipment/transportSummaries/transportEquipmentId/{transportEquipmentId}

This API returns the transport summary of the transport equipment related to the equipmentID provided on the URL.

 

 

Transport Equipment event APIs

The two Transport Equipment events APIs will query for events belonging to all Transport Equipment associated with the Consignment with the given ID. The event filter parameter can be used to get only the most recent versions of each event or to get all events published, see below:

• Latest - Only the most recent versions of an event will be returned. The transportPlanIssuanceTime8601 will be used to determine the most recent Planned events. All Actual events will be returned, no filtering is done. For Estimated events, the location, the eventSubmissionTime, the 'originatorID', and the 'fullStatus' fields will be used. For nontransport events, the 'eventSubmissionTime' will be used.
• All - No filtering is done. All events are returned.

If the 'eventFilter' is not specified, the default is "all". You may optionally specify a 'transportEquipmentID' to return only results for the transport equipment with that ID.

The list of events is sorted on occurrence time if present, otherwise the submission time.

Commodity and originator information visibility is restricted to 'orgs' that were onboarded with certain types. If your org does not have one of these correct types, then you may not have visibility to the following fields in each event:

Commodity information:

• harmonizedCodes
• commodities.commodityDescription
• commodities.commodityHarmonizedCode

Originator information:

• originatorName
• originatorId
• senderOrgId

In addition, the originator information on a Party Add/Update/Remove event will be hidden if you are not the org who submitted the event or one of the parties being added. The originator information and 'destinationOrgName' field on a Document event whose 'action' field is 'issued', 'transferred', or 'surrendered' will be hidden if you are not the org who submitted the event or the org that the document is being transferred to.

The two “transport equipment events” APIs:

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

The Query for events belonging to all Transport Equipment associated with the Consignment with the given ID. The event filter parameter can be used to control how much processing is done to the resulting list.

 

API GET - https://platform.tradelens.com/api/v1/transportEquipment/events/transportEquipmentId/{transportEquipmentId}

The Query for events for the Transport Equipment with the given ID. The event filter parameter can be used to control how much processing is done to the resulting list.