Vessel and Container Route Data
This guide explains how to access detailed container routes and vessel positions data (historical and future positions) using Terminal49 APIs.
This is a technical article describing how to use our Routing Data feature, using the map as an example.
Routing Data (Container Route and Vessel Positions APIs) is a paid feature. These APIs are subject to additional terms of usage and pricing. If you are interested in using these APIs, please contact sales@terminal49.com.
Table of Contents
- Overview of APIs for Mapping
- Visualizing Your Container’s Journey on a Map
- Use Cases
- Recommendations and Best Practices
- Frequently Asked Questions
Overview of APIs for Mapping
Terminal49 offers a suite of powerful APIs to provide granular details about your container shipments and vessel locations.
Two key components are:
- Container Route API: Offers detailed information about each part of your container’s journey, including port locations (latitude, longitude), vessels involved, and key timestamps. This is foundational for placing port markers on your map.
- Vessel Positions API: Provides access to historical and predicted future positions for the vessels.
Visualizing Your Container’s Journey on a Map
To create a map visualization of a container’s journey (similar to the embeddable map), you’ll typically combine data from several API endpoints. Here’s a step-by-step approach:
Step 1: Plotting Port Locations
First, retrieve the overall route for the container. This will give you the sequence of ports the container will visit, along with their geographical coordinates.
Use the GET /v2/containers/{id}/route
endpoint. (See: Get Container Route API Reference)
API Request & Response Snippet for Port Locations
API Request & Response Snippet for Port Locations
How to use:
- Parse the
data.relationships.route_locations.data
array to get the sequence of stops. - For each
route_location
object (found inincluded
using its ID from the previous step), find its corresponding physicallocation
(port) by looking up therelationships.location.data.id
in theincluded
array (wheretype
isport
). - Use the
latitude
andlongitude
from the port attributes to plot markers on your map (e.g., POL, TS1, TS2 as shown in the image). - Each
route_location
inincluded
also contains valuable data likeoutbound_atd_at
,inbound_ata_at
,outbound_vessel.id
,inbound_vessel.id
etc., which you’ll need for the next steps.
Step 2: Drawing Historical Vessel Paths (Actual Route Taken)
For segments of the journey that have already been completed, you can draw the vessel’s actual path using its historical positions.
Use the GET /v2/vessels/{id}?show_positions[from_timestamp]={departure_time}&show_positions[to_timestamp]={arrival_time}
endpoint. (See: Get Vessel Positions API Reference
API Request & Response Snippet for Historical Paths
API Request & Response Snippet for Historical Paths
How to use:
- From the
/containers/{id}/route
response, for each completed leg (i.e., both ATD from origin and ATA at destination are known):- Identify the
outbound_vessel.data.id
from the departureroute_location
. - Use the
outbound_atd_at
(Actual Time of Departure) from the departureroute_location
as thefrom_timestamp
. - Use the
inbound_ata_at
(Actual Time of Arrival) from the arrivalroute_location
as theto_timestamp
.
- Identify the
- Call the
/vessels/{vessel_id}?show_positions...
endpoint with these details. - The
attributes.positions
array will contain a series of latitude/longitude coordinates. Plot these coordinates as a connected solid line on your map to represent the vessel’s actual historical path for that leg (like the green line from POL to TS1 in the image).
Step 3: Drawing Predicted Future Vessel Paths
For segments that are currently underway or planned for the future, you can display predicted vessel paths. These are typically shown as dashed lines.
Using GET /v2/vessels/{id}/future_positions_with_coordinates
(For Vessels Currently En Route)
This endpoint is used when the vessel is currently en route between two ports (e.g., has departed Port A but not yet arrived at Port B). It requires the vessel’s current coordinates as input, in addition to the port of departure and the port of arrival for the leg. The output is a predicted path from the vessel’s current location to the destination port. (See: Get Vessel Future Positions with Coordinates API Reference)
API Request & Response Snippet for Detailed Future Paths (Vessel En Route)
API Request & Response Snippet for Detailed Future Paths (Vessel En Route)
How to use:
- Determine if vessel is en route: From the
/containers/{id}/route
response, check if the leg has anoutbound_atd_at
from the origin port but noinbound_ata_at
at the destination port yet. - Get Current Vessel Coordinates:
- Identify the
outbound_vessel.data.id
from the departureroute_location
. - Fetch the vessel’s current details using
GET /v2/vessels/{vessel_id}
. The response will contain its latestlatitude
,longitude
, andposition_timestamp
in theattributes
section.Example: Fetch current vessel data
- Identify the
- Call
future_positions_with_coordinates
:- Use the
location.data.id
of the original departure port for this leg (asprevious_port_id
or similar parameter, check API ref). - Use the
location.data.id
of the final arrival port for this leg (asport_id
or similar parameter). - Include the fetched current
latitude
andlongitude
of the vessel in the request.
- Use the
- Plot the path: The
attributes.positions
array will provide a sequence of estimated coordinates starting from (or near) the vessel’s current position. Plot these as a connected dashed line on your map (like the dashed line from the vessel’s current position between TS1 and TS2, heading towards TS2 in the image).
Using GET /v2/vessels/{id}/future_positions
(For Legs Not Yet Started)
This endpoint is used when the vessel has not yet departed from the origin port of a specific leg. It takes the origin port (Port A) and destination port (Port B) of the upcoming leg as input and predicts a path between them. (See: Get Vessel Future Positions API Reference)
API Request & Response Snippet for Future Paths Between Ports (Leg Not Started)
API Request & Response Snippet for Future Paths Between Ports (Leg Not Started)
How to use:
- Determine if leg has not started: From the
/containers/{id}/route
response, check if the leg has nooutbound_atd_at
from the origin port (oroutbound_etd_at
is in the future). - Identify vessel and ports:
- Get the
outbound_vessel.data.id
that will perform this leg. - Get the
location.data.id
of the departure port for this leg (asprevious_port_id
). - Get the
location.data.id
of the arrival port for this leg (asport_id
).
- Get the
- Call
future_positions
:
- Plot the path: The
attributes.positions
array will provide estimated coordinates for the full leg. Plot these as a connected dashed line on your map (like the dashed line from TS3 to TS4 in the image, assuming the vessel is still at TS3).
Combining Data for a Complete Map
By iterating through the route_locations
obtained from the initial /containers/{id}/route
call:
- Plot all port markers (Step 1).
- For each leg of the journey:
- If the leg is completed (ATD and ATA are known), use the historical vessel positions API to draw a solid line (Step 2).
- If the leg is in progress or planned for the future (ATD known or ETD known, but ATA is not yet known or is in the future), use one of the future vessel positions APIs to draw a dashed line (Step 3).
This approach allows you to build a comprehensive map view, dynamically showing completed paths with solid lines and future/in-progress paths with dashed lines, providing a clear visualization of the entire shipment journey.
Use Cases
Integrating Terminal49’s Vessel and Container Route APIs enables a variety of advanced capabilities:
- Track Complete Shipment Journeys Visually: Monitor shipments across multiple legs on a map, from the port of lading to the port of discharge, including all transshipment points.
- Identify Transshipment Details Geographically: Clearly see where transshipments occur and the routes taken between them.
- Correlate Timestamps with Locations: Visually connect ETDs, ETAs, ATDs, and ATAs for every leg with their geographical points on the map for precise planning and exception management.
- Improve Internal Logistics Dashboards: Offer your operations team a clear visual overview of all ongoing shipments and their current locations.
Recommendations and Best Practices
- Polling Intervals: For routing data and vessel positions we recommend refreshing up to once per hour.
- Efficient Data Handling: Cache previous vessel positions when possible, as it doesn’t change. Focus polling on active vessel movements.
- Error Handling: Implement proper error handling for API requests, especially for future predictions which might not always be available for all routes or vessels.
If you decide to create your own map:
- Data Layering: Consider layering information on your map. Start with basic port markers and paths, then add details like vessel names, ETAs, or status on hover or click.
- Map Library Integration: Use a robust mapping library (e.g., Leaflet, Mapbox GL) to handle the rendering of markers, lines, and map interactivity.
Frequently Asked Questions
Q: How up-to-date is the vessel position data? A: Vessel location data is updated every 15 minutes, although that does not guarantee there will be a new position every 15 minutes to factors like whether the vessel is transmitting or within range of a satellite or base station.
Q: How accurate are the future predictions? Predicted future positions are based on algorithms and current data, and their accuracy can vary based on many factors such as temporary deviations, seasonality, or how frequently the shipping lane is used.
Q: What if a vessel deviates from the predicted path? A: Predicted paths are estimates. The historical path (once available) will show the actual route taken. Regularly refreshing data for active shipments is key to getting the most accurate information.