Detect Vessel Route Deviations in Real Time with Vessel API
When managing a fleet, it’s not just about knowing where your ships are — it’s also about knowing when something goes wrong. A vessel drifting off its planned course or running behind schedule can have serious logistical and safety implications. These vessel route deviations can disrupt your operations if not detected in time.
The Datalastic Vessel API gives you the power to monitor these situations in real time. Whether you’re overseeing commercial cargo routes, port entries, or offshore operations, it helps you act fast when a vessel behaves unexpectedly or shows signs of a route deviation.
What This Post Covers:
In this post, we’ll show you how to build a live vessel monitoring system that alerts you when ships drift from their predefined routes or miss arrival/departure times. The goal is to help you detect and respond to vessel route deviations before they cause bigger issues.
How the Vessel Route Deviation Detection System Works?
With the Datalastic API, you won’t just track vessels passively. You’ll actively monitor and react to vessel route deviations:
- Geofenced Area Monitoring: Keeps an eye on vessel movements within specific zones you define.
- Schedule Tracking: Follows planned arrival and departure times using AIS data to see if everything’s on track.
- Deviation Detection: Spots ships that are running late or arriving earlier than expected.
- Custom Alerts: Notifies you instantly when something goes off schedule, based on the limits you set.
1. Fetching Ship Data to Monitor Vessel Route Deviations:
To begin, we use the vessel_bulk endpoint from Datalastic’s AIS API.
It allows for to retrieve real-time vessel data for up to 100 ships within designated geographic zones in a single API call, ideal for spotting vessel route deviations in clusters.
The data returned includes:
Vessel name and IMO/MMSI
Current position and speed
Destination and ETA
Navigational status
This data forms the foundation of your vessel tracking and alerting system.
def query_vessels_bulk(identifiers):
url = "https://api.datalastic.com/api/v0/vessel_bulk"
# Construct query parameters
params = {
"api-key": API_KEY
}
# Add all ship identifiers to the params
for id_type, id_list in identifiers.items():
for id_value in id_list:
params[id_type] = id_value
response = requests.get(url, params=params)
return response.json()2. Analyzing Vessel Details to Predict Route Deviations
The vessel_bulk endpoint returns detailed information for each vessel, essential for real-time tracking and schedule analysis. Data such as:
Vessel Identifiers: MMSI, IMO number, and vessel name
Current Position: Latitude and longitude
Speed and Course: Current speed (knots) and heading
Destination Information: Reported destination and estimated time of arrival (ETA)
Last Position Update: Timestamp of the most recent AIS signal
This data enables accurate monitoring of ship movements and supports proactive schedule tracking.
3. Estimating Arrival Times (ETA):
To determine whether a ship is on schedule, your system can either:
Use the ETA values provided via AIS data when available, or
Calculate your own ETA dynamically using the vessel’s current location, speed, and distance to the destination
This ETA estimation is crucial for identifying delays, early arrivals, or unexpected deviations so you to act before small issues become major disruptions.
def is_vessel_off_schedule(vessel_data, schedule_data):
# Calculate expected position based on departure time, destination, and ETA
expected_position = calculate_expected_position(
departure_coords,
destination_coords,
departure_time,
expected_eta,
current_time
)
# Calculate distance between actual and expected positions
distance_nm = geodesic(current_position, expected_position).nautical
# Check if the vessel is off schedule based on tolerance
if distance_nm > tolerance_distance:
return True, message4. Detecting Schedule Deviations in Vessel Tracking:
A key component of the monitoring system is detecting schedule deviations by comparing a vessel’s actual progress with its expected timeline.
The system evaluates:
Planned vs. Actual ETA: Compares current ETA to the scheduled arrival time
Distance Remaining vs. Time Left: Analyzes whether the vessel’s speed is sufficient to arrive on time
Deviation Thresholds: Flags delays or early arrivals that exceed predefined tolerance levels
def check_vessel_destination(vessel_data, schedule_data):
# Compare reported destination with expected destination
if reported_port != expected_destination:
return True, message5. Sending Notifications:
When a vessel falls off schedule, the system sends an email notification:
def send_notification(subject, message):
msg = MIMEMultipart()
msg['Subject'] = subject
msg.attach(MIMEText(message, 'plain'))
server = smtplib.SMTP(SMTP_SERVER, SMTP_PORT)
server.starttls()
server.login(SMTP_USERNAME, SMTP_PASSWORD)
server.send_message(msg)6. Sending Alerts for Vessel Route Deviations
When a vessel experiences a schedule or route deviation, the system sends a notification:
Requirements:
A valid API key
Python environment with the following packages:
requests,geopySMTP server access (e.g. Gmail SMTP) to enable email alerts
1. Vessel Identifiers:
MONITORED_SHIPS = {
"mmsi": [
"235362000", # GARGANO
"566093000", # MAERSK CHENNAI
# more vessels...
],
"imo": [
"9249403", # GARGANO
"9525338", # MAERSK CHENNAI
# more vessels...
]
}2. Expected Schedules:
SHIP_SCHEDULES = {
"235362000": { # MMSI of GARGANO
"name": "GARGANO",
"expected_route": [
{
"departure_port": "ROTTERDAM",
"departure_time": "2025-04-10T08:00:00Z",
"destination_port": "SUNDERLAND",
"expected_eta": "2025-04-16T14:00:00Z",
"tolerance_hours": 6
}
]
},
# more vessels...
}Running the Monitor
The monitor_ships() function:
- Queries the Datalastic vessel API for all monitored vessels
- Processes each vessel’s data
- Checks for schedule deviations, destination changes, and ETA updates
- Sends notifications when issues are detected
- Updates the ship database
The monitoring runs continuously, with checks performed at the interval specified in CHECK_INTERVAL.
Building Efficient Fleet Monitoring with the Datalastic Vessel API:
The Datalastic Vessel API provides a powerful foundation for building a ship monitoring system. By combining this data with expected schedules, we can create a solution that helps shipping companies stay on top of their fleet operations and quickly respond to any schedule deviations.
This implementation demonstrates how to leverage the API to build a practical monitoring solution that can save time and resources in managing a fleet of vessels.
Read Other Maritime Articles
Maritime Weather API: Current and Hourly Data
If you've ever tried to bolt weather data onto a shipping or logistics tool, you know the annoying part isn't the weather data itself. It's that marine conditions and atmospheric conditions usually come from two different providers with two different schemas, and...
AIS Spoofing in the Red Sea: What’s Really Happening
A cargo ship off Yanbu suddenly reports a position it couldn’t possibly have reached. Its speed jumps to 45 knots, far beyond what a loaded tanker can realistically do. Minutes later, the signal disappears. Hours after that, the vessel reappears somewhere else...
How To Use ChatGPT To Track Ships in Real Time?
Tracking ships using ChatGPT is possible and an easy process when it is connected to a live maritime data source such as Datalastic. On its own, ChatGPT does not maintain a live database of ship positions. It may know general information about vessels, shipping...
How to Connect Datalastic to Claude and ChatGPT?
Connecting Datalastic to Claude and ChatGPT is an easy and fast process that you'll be surprised by it, following this tutorial. By connecting Datalastic through its Model Context Protocol (MCP) server, you can give AI assistants direct access to real-time maritime...
Find Vessels In The Gulf Of Oman
Tracking vessels in the Gulf of Oman is essential for understanding maritime traffic in one of the world’s most strategically important shipping corridors. This region connects the Arabian Sea with the Strait of Hormuz, acting as a gateway for global oil shipments,...
Enterprise Vessel Tracking API
An enterprise vessel tracking API is not defined by features alone. It is defined by scale, reliability, and the ability to perform under real-world pressure. In maritime operations, where systems rely on continuous data flows, even small inefficiencies can quickly...
Recent Comments