Anchor Handling Tug Supply (AHTS) vessels are the workhorses of offshore maritime operations—towing and positioning rigs, laying anchors and mooring lines, supporting subsea construction, and executing time-sensitive cargo runs to platforms. Building reliable software for AHTS tracking is hard: you need live AIS positions, short-term history for situational context, predicted ETA into dynamic offshore zones, congestion snapshots at staging ports, and credible emissions analytics for ESG reporting. Stitching that together from scratch is error-prone and slow. This is where Vessels API makes a difference: a single, developer-friendly REST API that delivers consistent AIS-powered data you can depend on for AHTS fleet monitoring and operational analytics.
Why AHTS operators, offshore logistics teams, and developers need a unified maritime API
AHTS operations are complex and compressed: rig moves are scheduled to weather windows; tow wire deployment is phased with support asset arrival; resupply vessels stack up in anchorage ahead of bunkering and deck prep. Without real-time vessel awareness and programmatic access to voyage and port intelligence, planning breaks down. Developers building dashboards, dispatch tools, or reliability engineering systems for these workflows often face:
- Fragmented data sources: separate position feeds, port feeds, and historical analytics stitched at the application layer.
- Inconsistent payloads: different schemas per endpoint increase mapping complexity and introduce edge-case bugs.
- Limited query modes: hard to pull batch updates for fleets or filter to only the vessels and time windows that matter.
- Uncertain ETAs: without route context and weather overlays, arrival predictions degrade quickly for offshore waypoints.
- Regulatory friction: emissions estimation and reporting is tricky to standardize across mixed vessel portfolios (including AHTS).
Vessels-api.com addresses these pain points with 18 REST endpoints under a single base URL, a consistent JSON envelope across responses, and global AIS coverage tuned for near real-time refresh. It scales from indie apps to operational control rooms, so the same codebase can power a proof-of-concept, a field pilot, and a production rollout.
Platform capabilities that matter for maritime applications
As a developer advocate and engineer, I evaluate maritime APIs on their ability to simplify integration while supporting production-grade reliability. For AHTS-centric software, the following capabilities in vessels-api.com are significant:
- Streamlined integration: One base URL, one request header. A single client configuration can call every endpoint without per-endpoint ceremony.
- Consistent JSON envelope: Every response follows the structure { status, success, message, data }, simplifying observability, logging, and error handling rules.
- Global AIS coverage: Near real-time refresh supports offshore ops where positional currency is key to safety and scheduling.
- Performance-minded practices: The endpoints are split by intent (search, tracking, fleet batch, port intelligence). This shape reduces over-fetching and is friendlier to client latency targets. You can route requests per user action or cron cadence instead of forcing a single heavy feed.
- Governance and controls patterns: Use per-application credentials and role-based usage inside your organization, log payload-level audits in your app, and apply data locality policies on your side if you serve multi-region users. Vessels-api.com’s consistent envelope makes writing those middleware controls straightforward.
- Reliability best practices: The API’s clear error codes enable client-side fallback chains and circuit breakers. Implement retries with exponential backoff for transient 5xx; degrade to last-known position cache if 429 or 500 occurs; reset routes after health checks. These patterns align well with the service’s error taxonomy.
Below, I’ll show how to build an AHTS tracking workflow using the endpoints that matter most, then cover the complete endpoint catalog and implementation patterns you can reuse.
AHTS tracking workflow: core endpoints you’ll use first
For AHTS scenarios, I recommend starting with four endpoints:
- GET /vessels/track — live position, history, route, and predicted ETA with optional weather.
- POST /vessels/fleet — batch positions and routes for a working group of tugs and support vessels.
- GET /ports/congestion — congestion and wait-time analytics for staging or bunkering ports.
- GET /vessels/green — IMO CII emissions scoring for compliance and sustainability reporting.
GET /vessels/track — Live AHTS telemetry with context
This endpoint consolidates live position, up to 168 hours of history, current route, predicted ETA, and optional weather into one payload—ideal for AHTS day-to-day ops. Use it to:
- Render a live map with breadcrumb trails for situational awareness around rigs or anchor handling zones.
- Surface dynamic ETAs to crew transfer vessels or supply barges.
- Correlate motion with local weather to flag safety thresholds.
Request example (cURL):
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=48&include_route=true&include_predicted_eta=true&include_weather=true"
Request example (Python):
import requests
BASE_URL = "https://vessels-api.com/api/V1"
headers = {
"X-API-Key": "YOUR_API_KEY"
}
params = {
"mmsi": "258785000",
"hours": 48,
"include_route": "true",
"include_predicted_eta": "true",
"include_weather": "true"
}
r = requests.get(f"{BASE_URL}/vessels/track", headers=headers, params=params, timeout=15)
r.raise_for_status()
payload = r.json()
if payload.get("success"):
vessel = payload["data"]["vessel"]
current = payload["data"]["current_position"]
route = payload["data"].get("route")
print(vessel["name"], current["latitude"], current["longitude"], current["speed_knots"])
else:
print("Tracking error:", payload.get("message"))
Realistic JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessel": {
"imo": "9423671",
"mmsi": "258785000",
"name": "AHTS NORTH STAR"
},
"current_position": {
"latitude": 59.5853,
"longitude": 1.9831,
"speed_knots": 6.2,
"course_degrees": 214,
"heading_degrees": 210,
"navigational_status": "Restricted Manoeuvrability",
"timestamp_utc": "2026-09-23T11:42:31Z",
"destination": "EKOFISK FIELD",
"eta": "2026-09-23T13:15:00Z"
},
"position_history": [
{
"latitude": 59.7104,
"longitude": 2.3121,
"speed_knots": 7.8,
"course_degrees": 219,
"timestamp_utc": "2026-09-23T08:42:27Z"
},
{
"latitude": 59.6668,
"longitude": 2.1734,
"speed_knots": 7.3,
"course_degrees": 217,
"timestamp_utc": "2026-09-23T09:42:27Z"
}
],
"route": {
"departure_port": "NOSTA",
"departure_time": "2026-09-23T05:10:00Z",
"destination_port": "EKOFISK",
"eta": "2026-09-23T13:15:00Z",
"distance_nm": 96.4,
"avg_speed_knots": 8.3
},
"last_port_visits": [
{
"port_id": "NOSTA",
"port_name": "Stavanger",
"arrival_time": "2026-09-22T19:17:00Z",
"departure_time": "2026-09-23T05:10:00Z"
}
]
}
}
Key fields and how to use them:
- current_position.navigational_status: For AHTS, “Restricted Manoeuvrability” or “At Anchor” can trigger special map symbology and HSE alerts.
- position_history: Render tracklines; correlate speed dips with tow or anchor handling phases; compute smoothed COG vectors.
- route.distance_nm and avg_speed_knots: Combine with remaining distance to re-compute live ETA drift vs. predicted_eta.
- last_port_visits: Useful for audit trails and operations recaps in daily reports.
POST /vessels/fleet — Batch updates for an AHTS working group
AHTS ops rarely involve a single vessel. During rig moves, you’ll coordinate multiple tugs, supply vessels, and standby craft. The batch endpoint aggregates positions and route data in one request, reducing client-side overhead and ensuring your UI loads are snappy.
Request example (cURL):
curl -X POST "https://vessels-api.com/api/V1/vessels/fleet" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vessels": [
{ "imo": "9423671" },
{ "mmsi": "235094801" },
{ "mmsi": "309374000" }
],
"include_positions": true,
"include_routes": true
}'
JavaScript example (Node.js/fetch):
import fetch from "node-fetch";
const BASE_URL = "https://vessels-api.com/api/V1";
async function fetchFleet() {
const body = {
vessels: [
{ imo: "9423671" },
{ mmsi: "235094801" },
{ mmsi: "309374000" }
],
include_positions: true,
include_routes: true
};
const res = await fetch(`${BASE_URL}/vessels/fleet`, {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify(body)
});
const payload = await res.json();
if (!payload.success) {
console.error("Fleet error:", payload.message);
return;
}
const { vessels_at_sea } = payload.data.fleet;
console.log("At sea:", vessels_at_sea);
for (const v of payload.data.vessels) {
console.log(v.name, v.position?.speed_knots, v.route?.destination_port);
}
}
fetchFleet().catch(console.error);
Realistic JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"fleet": {
"total_vessels": 3,
"vessels_at_sea": 2,
"vessels_in_port": 1
},
"vessels": [
{
"imo": "9423671",
"mmsi": "258785000",
"name": "AHTS NORTH STAR",
"position": {
"latitude": 59.5853,
"longitude": 1.9831,
"speed_knots": 6.2,
"course_degrees": 214,
"timestamp_utc": "2026-09-23T11:42:31Z"
},
"route": {
"departure_port": "NOSTA",
"destination_port": "EKOFISK",
"eta": "2026-09-23T13:15:00Z",
"distance_nm": 96.4
}
},
{
"imo": "9122556",
"mmsi": "235094801",
"name": "AHTS OCEAN VANGUARD",
"position": {
"latitude": 58.9731,
"longitude": 2.4029,
"speed_knots": 0.3,
"course_degrees": 0,
"timestamp_utc": "2026-09-23T11:41:53Z"
},
"route": null
},
{
"imo": null,
"mmsi": "309374000",
"name": "OFFSHORE SUPPORT 12",
"position": {
"latitude": 58.9763,
"longitude": 5.7330,
"speed_knots": 0.0,
"course_degrees": 90,
"timestamp_utc": "2026-09-23T11:41:07Z"
},
"route": {
"departure_port": "NOSTA",
"destination_port": "NOSTA",
"eta": null,
"distance_nm": 0.0
}
}
]
}
}
Practical uses:
- Operational dashboard: One call to draw markers, speed labels, and route chips for your AHTS pack.
- Dispatch cadence: Poll on a fixed interval (e.g., 30–60 seconds) and diff by MMSI to detect status changes.
- Alerting: If any vessel’s speed_knots drops below a threshold while at sea, raise a towline tension check or DP state check in your ops system.
GET /ports/congestion — Offshore staging port intelligence
Before rig moves, AHTS vessels often stage through key ports for bunkers, deck gear, and crew. Congestion and wait-time statistics help planners sequence port calls and avoid stack-ups. Use this endpoint to surface real-time counts and rolling averages in your scheduling app.
Request example (cURL):
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/ports/congestion?port_id=ARBUE&period=7d"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "ARBUE",
"port_name": "Buenos Aires",
"period": "7d",
"snapshot": {
"vessels_in_anchorage": 24,
"vessels_at_berth": 31
},
"statistics": {
"avg_wait_time_hours_last_7d": 18.6,
"max_wait_time_hours_last_7d": 41.2,
"avg_berth_time_hours_last_7d": 22.9,
"port_calls_count": 412
}
}
}
How to use it:
- Estimate staging buffers: If avg_wait_time_hours_last_7d is above target, re-sequence arrival plans or route via an alternate port.
- KPI boards: Track variance in anchorage vs. berth counts and correlate with your fleet’s demurrage exposure.
GET /vessels/green — CII scoring for AHTS ESG reporting
Even specialized vessels like AHTS are under emissions scrutiny. This endpoint provides a period-bounded estimate of CO2, per-nautical-mile intensity, and an IMO CII rating (A through E) aligned to MEPC.339(76). Integrate it into weekly sustainability digests or automated ESG dashboards.
Request example (cURL):
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/green?mmsi=258785000&period=30d"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"imo": "9423671",
"mmsi": "258785000",
"name": "AHTS NORTH STAR",
"period": "30d",
"distance_nm": 1420.7,
"estimated_emissions": {
"co2_tons": 318.4,
"co2_per_nm": 0.224
},
"cii": {
"score": 11.7,
"rating": "C",
"year": 2026,
"regulation_reference": "IMO MEPC.339(76)"
}
}
}
What to do with it:
- Compare intensity across AHTS assets; prioritize maintenance or operational changes (e.g., towing speed policies) to improve ratings.
- Feed period reports to compliance tools and inform charterer dialogues on performance guarantees.
Comprehensive endpoint coverage: everything available in vessels-api.com
Vessels-api.com exposes 18 REST endpoints under a unified base URL: https://vessels-api.com/api/V1. Below is a complete catalog with descriptions, business value, and implementation notes. All endpoints respond with the same envelope: { status, success, message, data }.
Vessel Intelligence
- GET /vessels/search — Purpose: Discover vessels by fuzzy name, IMO, or MMSI; filter by type, flag, DWT/TEU, year. Business value: onboard a fleet, validate MMSI/IMO, or power user search in your app. Key parameters: query, ship_type, flag, min_dwt/max_dwt, min_teu/max_teu, year_built_from/year_built_to, page, per_page.
- GET /vessels/track — Purpose: Live AIS + history + route + predicted ETA + weather. Business value: single-call situational awareness and ETA management for operations.
- GET /vessels/nearby — Purpose: Proximity scan within radius of a lat/lon; filter by ship_type. Business value: identify support assets near a rig or distress zone; suggest alternates for urgent tows.
- GET /vessels/analytics — Purpose: Aggregated voyage statistics for a vessel, port, or fleet. Business value: utilization, port call counts, speed profiles, and periodic analytics for ops reviews.
Fleet Operations
- POST /vessels/fleet — Purpose: Batch pull for multiple vessels’ positions, routes, and rollups. Business value: efficient dashboards, reduced latency, and fewer requests.
- GET /vessels/green — Purpose: IMO CII emissions estimation and rating. Business value: ESG reporting and operational performance insights.
Port Intelligence
- GET /ports/congestion — Purpose: Congestion and wait-time stats for a port. Business value: staging, scheduling, and berth planning.
- GET /ports — Purpose: Full port catalog. Business value: reference data for UI dropdowns, validation, and geospatial overlays.
- GET /ports/data — Purpose: Detailed port info plus live vessel counts. Business value: operational snapshots and port context in UIs.
- GET /port/expected-arrivals — Purpose: Upcoming arrivals with ETA and origin. Business value: berth planning, resource allocation, and just-in-time scheduling.
- GET /port/activity — Purpose: Recent arrivals and departures. Business value: event feeds for logistics workflows and audit trails.
Legacy Endpoints (stable)
- GET /vessel/info?imo=IMO — Static vessel particulars.
- GET /vessel/route?imo=IMO — Current voyage route details.
- GET /vessel/position?imo=IMO — Last known AIS by IMO.
- GET /vessel/mmsi-position?mmsi=MMSI — Last known AIS by MMSI.
- GET /vessel/port?port=PORT_ID — Vessels in/at a port.
- GET /vessel/port/mmsi?mmsi=MMSI — Current port call by MMSI.
Legacy endpoints are handy for lightweight integrations and backward compatibility; for richer, consolidated payloads, prefer the /vessels/ and /ports/ endpoints above.
Examples and response breakdowns for additional endpoints used in AHTS operations
GET /vessels/search — Fuzzy lookup for onboarding AHTS assets
Use cases:
- Quickly onboard new tugs by name, even if spelling is imperfect.
- Filter by vessel_type to isolate AHTS or Offshore Tug/Supply classes.
- Cross-validate flagged registry or dimensions when building your fleet master.
cURL example:
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/search?query=North%20Star&ship_type=AHTS&flag=Norway&per_page=5"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"vessels": [
{
"imo": "9423671",
"mmsi": "258785000",
"name": "AHTS NORTH STAR",
"flag": "Norway",
"vessel_type": "AHTS",
"gross_tonnage": 4380,
"deadweight_tonnage": 3450,
"year_built": 2010,
"length_m": 78.5,
"width_m": 18.0
}
],
"pagination": {
"current_page": 1,
"per_page": 5,
"total": 1,
"last_page": 1
}
}
}
Field notes:
- vessel_type: Filter for AHTS vs. PSV to avoid mixing mission profiles.
- deadweight_tonnage and length/width: Useful when matching tow assignments to bollard pull classes and deck space requirements.
- pagination: Drive infinite scroll and server-side pagination in your admin UI.
GET /vessels/nearby — Situational awareness around rigs and anchor patterns
AHTS work zones get crowded. With /vessels/nearby you can display the vessels within a radius and restrict by ship_type to surface tugs and support boats only. This helps collision avoidance tooling, operational overlays, or onshore monitoring.
cURL example:
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/nearby?latitude=59.00&longitude=2.00&radius=30&ship_type=AHTS&limit=50"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"center": { "latitude": 59.0, "longitude": 2.0 },
"radius_nm": 30,
"total": 7,
"vessels": [
{
"imo": "9423671",
"mmsi": "258785000",
"name": "AHTS NORTH STAR",
"ship_type": "AHTS",
"position": { "latitude": 59.5853, "longitude": 1.9831, "timestamp_utc": "2026-09-23T11:42:31Z" },
"distance_nm": 9.2,
"speed_knots": 6.2,
"course_degrees": 214,
"navigational_status": "Restricted Manoeuvrability"
}
]
}
}
Use this to:
- Visualize density near an installation and dynamically widen radius for regional monitoring.
- Trigger alerts if non-whitelisted vessels enter sensitive perimeters.
GET /vessels/analytics — AHTS utilization and port-touch profiles
Analytics provide roll-up statistics over windows (24h, 7d, 30d, 90d) for a single vessel, a port lens, or a fleet list. For AHTS, this is ideal for weekly utilization reporting and port call analysis.
cURL examples:
# Vessel analytics (7 days)
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/analytics?type=vessel&mmsi=258785000&period=7d"
# Fleet analytics (30 days)
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/analytics?type=fleet&mmsi_list=258785000,235094801&period=30d"
# Port lens analytics (90 days)
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/analytics?type=port&port_id=NOSTA&period=90d"
JSON response snippet (vessel mode):
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"type": "vessel",
"mmsi": "258785000",
"imo": "9423671",
"name": "AHTS NORTH STAR",
"period": "7d",
"statistics": {
"total_distance_nm": 418.6,
"avg_speed_knots": 7.4,
"max_speed_knots": 12.1,
"port_calls_count": 3,
"total_time_in_port_hours": 37.3,
"ports_visited": ["NOSTA", "EKOFISK"]
}
}
}
How to apply:
- Compare total_time_in_port_hours across tugs to spot underutilization.
- Benchmark avg_speed_knots vs. towing SOPs to detect non-compliant runs.
- Use fleet mode to aggregate KPIs for management reports.
Port data endpoints for staging, berthing, and scheduling
Beyond congestion, your product will likely show expected arrivals, recent activity events, and a port catalog for validation. Here are the relevant endpoints:
GET /ports — Reference catalog
This endpoint returns identifiers, coordinates, and time zones for 248 ports, enabling robust dropdowns, maps, and validation logic.
cURL example:
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/ports"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"ports": [
{ "port_id": "NOSTA", "name": "Stavanger", "country": "Norway", "latitude": 58.9701, "longitude": 5.7331, "timezone": "Europe/Oslo" },
{ "port_id": "ARBUE", "name": "Buenos Aires", "country": "Argentina", "latitude": -34.6037, "longitude": -58.3816, "timezone": "America/Argentina/Buenos_Aires" }
],
"total": 248
}
}
GET /ports/data — Detailed single-port snapshot
Use to show a port profile in your UI with live counts.
cURL example:
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/ports/data?port=NOSTA"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "NOSTA",
"name": "Stavanger",
"country": "Norway",
"latitude": 58.9701,
"longitude": 5.7331,
"timezone": "Europe/Oslo",
"vessels_in_port": 17,
"vessels_expected": 9
}
}
GET /port/expected-arrivals — Plan inbound flows
See which vessels are inbound, from where, and when. For AHTS staging, this helps berth planning and bunkering sequences.
cURL example:
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/port/expected-arrivals?port=NOSTA"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "NOSTA",
"port_name": "Stavanger",
"expected_arrivals": [
{ "mmsi": "258785000", "imo": "9423671", "name": "AHTS NORTH STAR", "vessel_type": "AHTS", "eta": "2026-09-24T06:30:00Z", "departure_port": "EKOFISK" },
{ "mmsi": "235094801", "imo": "9122556", "name": "AHTS OCEAN VANGUARD", "vessel_type": "AHTS", "eta": "2026-09-24T09:20:00Z", "departure_port": "EKOFISK" }
],
"total": 2
}
}
GET /port/activity — Recent arrivals/departures event feed
Ideal for operational timelines and audit logs.
cURL example:
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/port/activity?port=NOSTA"
JSON response snippet:
{
"status": 200,
"success": true,
"message": "OK",
"data": {
"port_id": "NOSTA",
"port_name": "Stavanger",
"arrivals": [
{ "mmsi": "258785000", "name": "AHTS NORTH STAR", "arrival_time": "2026-09-22T19:17:00Z", "from_port": "EKOFISK" }
],
"departures": [
{ "mmsi": "258785000", "name": "AHTS NORTH STAR", "departure_time": "2026-09-23T05:10:00Z", "to_port": "EKOFISK" }
]
}
}
Legacy endpoints for lightweight or backward-compatible integrations
While you’ll typically prefer /vessels/track and /vessels/fleet, the legacy endpoints offer concise payloads when you only need a single datum. Example usage:
- GET /vessel/position?imo=IMO and GET /vessel/mmsi-position?mmsi=MMSI — last-known AIS fix, quick ping for heartbeat checks.
- GET /vessel/info?imo=IMO — static particulars; populate side panels or tooltips.
- GET /vessel/route?imo=IMO — voyage route snapshot for simple UIs.
- GET /vessel/port?port=PORT_ID and GET /vessel/port/mmsi?mmsi=MMSI — quick port association checks in job routing tools.
Tip: Use these for low-latency checks, then fetch richer details from /vessels/track on-demand when a user drills in.
Error handling, observability, and reliability patterns
Vessels-api.com provides clear error codes that map well to resilient client patterns:
- 200 OK — expected success; read payload.success and payload.data.
- 400 Missing/invalid parameter — validate inputs early; sanitize types and ranges.
- 401 Invalid or missing header — treat as configuration fault; raise operational alert.
- 404 Vessel/port not found — present “no results” UI; allow user to refine filters.
- 422 Parameter out of range — e.g., radius > 200 NM in /vessels/nearby; clamp inputs.
- 429 Rate limit exceeded — apply exponential backoff and cache last-known data.
- 500 Server error — retry with jitter; fail over to cached states; implement circuit breakers if persistent.
Observability best practices:
- Log status, endpoint, latency, and success flag on every call; sample payload sizes to watch trends.
- Tag logs by vessel MMSI/IMO to enable per-asset analytics and incident reconstruction.
- Track outlier latencies and implement soft timeouts; degrade gracefully to partial UI (e.g., show position without route).
Performance tips:
- Use /vessels/fleet for dashboards to minimize N calls per vessel.
- For /vessels/track, keep hours close to operational needs (e.g., 24–48h) to reduce payload size and improve render times.
- Apply selective polling intervals: increase for assets “At Anchor” or “Moored”, reduce for “Underway” and “Restricted Manoeuvrability”.
- Cache reference data (ports catalog) for long durations.
Implementation guidance: stitching an AHTS control tower
Let’s connect the dots into a coherent AHTS application:
- Fleet panel: Use POST /vessels/fleet every 30–60 seconds to refresh markers, speeds, and routes. Compute deltas to avoid re-rendering unchanged layers.
- Vessel detail drawer: On click, call GET /vessels/track with include_route and include_predicted_eta for a drilldown view with trackline and ETAs.
- Offshore safety overlay: Poll GET /vessels/nearby around rig coordinates at a smaller radius with ship_type filters; color-code navigational_status and speed thresholds.
- Port staging board: Show GET /ports/congestion, /port/expected-arrivals, and /port/activity for the relevant staging port; incorporate GET /ports/data into a header card.
- Weekly ops and ESG digest: Combine GET /vessels/analytics (fleet mode) with GET /vessels/green per vessel to chart utilization vs. intensity.
Data pipeline notes:
- Normalize all responses via the envelope; define a common TypeScript/Python dataclass layer (Status, Success, Message, Data).
- Implement a compact vessel state store keyed by MMSI and a rolling time series for position_history with max window 168h.
- Use a small diffing engine to emit UI updates only when speed, course, or status crosses thresholds, improving frontend performance.
Complete cURL and Python reference snippets you can copy-paste
cURL quick set:
# Search for AHTS vessels
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/search?query=AHTS&ship_type=AHTS&per_page=10"
# Live track with route and weather
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/track?mmsi=258785000&hours=24&include_route=true&include_weather=true"
# Nearby scan around Ekofisk
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/nearby?latitude=56.55&longitude=3.22&radius=25&ship_type=AHTS"
# Fleet batch
curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"vessels":[{"mmsi":"258785000"},{"mmsi":"235094801"}],"include_positions":true,"include_routes":true}' \
"https://vessels-api.com/api/V1/vessels/fleet"
# Analytics and emissions
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/analytics?type=vessel&mmsi=258785000&period=7d"
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/green?mmsi=258785000&period=30d"
# Port intel
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/ports"
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/ports/congestion?port_id=NOSTA&period=3d"
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/port/expected-arrivals?port=NOSTA"
curl -H "X-API-Key: YOUR_API_KEY" "https://vessels-api.com/api/V1/port/activity?port=NOSTA"
Python helper:
import requests
from typing import Dict, Any, Optional, List
BASE_URL = "https://vessels-api.com/api/V1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
def api_get(path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
r = requests.get(f"{BASE_URL}{path}", headers=HEADERS, params=params, timeout=15)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message") or "Unknown error")
return payload["data"]
def api_post(path: str, body: Dict[str, Any]) -> Dict[str, Any]:
r = requests.post(f"{BASE_URL}{path}", headers={**HEADERS, "Content-Type": "application/json"}, json=body, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("message") or "Unknown error")
return payload["data"]
def track_vessel(mmsi: str) -> Dict[str, Any]:
return api_get("/vessels/track", {
"mmsi": mmsi, "hours": 24, "include_route": "true", "include_predicted_eta": "true"
})
def fleet_batch(ids: List[Dict[str, str]]) -> Dict[str, Any]:
return api_post("/vessels/fleet", {"vessels": ids, "include_positions": True, "include_routes": True})
def port_congestion(port_id: str, period="7d") -> Dict[str, Any]:
return api_get("/ports/congestion", {"port_id": port_id, "period": period})
def emissions(mmsi: str, period="30d") -> Dict[str, Any]:
return api_get("/vessels/green", {"mmsi": mmsi, "period": period})
# Example orchestration
if __name__ == "__main__":
fleet = fleet_batch([{"mmsi": "258785000"}, {"mmsi": "235094801"}])
for v in fleet["vessels"]:
print(v["name"], v.get("position", {}).get("speed_knots"))
detail = track_vessel("258785000")
print("ETA:", detail.get("route", {}).get("eta"))
cong = port_congestion("NOSTA", "3d")
print("Anchorage:", cong["snapshot"]["vessels_in_anchorage"])
cii = emissions("258785000", "30d")
print("CII Rating:", cii["cii"]["rating"])
Parameter behavior and design tips
Design your client requests to fit operational intent:
- /vessels/track hours: Use 24–48h for most dashboards; stretch to 168h when you need extended playback or post-ops analysis.
- /vessels/nearby radius: Keep default at 10–30 NM for rig overlays; expand temporarily during search-and-rescue or weather-avoidance planning. The max is 200 NM.
- /vessels/analytics type: Use vessel for single-asset KPIs, fleet for management rollups, port for demand-side analytics at staging ports.
- Pagination: For /vessels/search, clamp per_page to 100; show page controls for power users.
Data modeling suggestions:
- Create core types: VesselIdentity (imo, mmsi, name), PositionFix, RouteSummary, PortVisit, EmissionsBlock, CongestionStats. This mirrors the API payloads and simplifies UI composition.
- Normalize by MMSI in your in-memory cache and join by IMO if needed; prefer MMSI for live tracking contexts.
- Time zones: Convert timestamp_utc to local port time zones only in the view layer; keep UTC in storage and analytics.
Common developer questions and troubleshooting
- Why is predicted ETA changing frequently? Offshore weather, towing speed, and holding patterns affect ETA. Combine route.distance_nm and current speed for a sanity check, and present ETA drift against the predicted value from /vessels/track.
- How do I avoid over-fetching? Use fleet batch for dashboards; poll detail endpoints only upon user interaction or for active alerts.
- What if I get 404 for a vessel? Validate MMSI/IMO via /vessels/search and ensure the asset is within AIS coverage; cache last-known position to handle temporary dropouts.
- How do I render route lines? Use current_position and position_history to draw polylines; when route exists, connect from last known to destination for a predicted leg overlay.
Security, governance, and data stewardship patterns
Enterprise teams building AHTS control systems often ask about governance mechanics. While the API itself is straightforward, you can layer robust controls in your app thanks to the consistent response envelope:
- Per-application credentials: Assign different service credentials per microservice or app surface to isolate blast radius and facilitate audit trails.
- Roles and scopes in your app: Gate which app surfaces can call fleet batch vs. single-vessel endpoints; log the “who” and “why” with each request for auditing.
- Data locality: If you serve multi-region users, use region-based proxies and store only what you need near the user; the envelope consistency eases proxy policy evaluation.
- Observability: Attach correlation IDs to outbound requests and log the status/success/message triple for uniform dashboards across services.
Putting it all together for AHTS: a reference architecture
A reference control tower for AHTS might look like this:
- Data ingest layer: Scheduled fleet batch polls; on-demand track pulls; nearby scans around installations during active jobs.
- Processing: Normalize vessel states; compute ETA drift; enrich with port congestion and expected arrivals; store last 168 hours of tracks.
- UI: Fleet map with layer toggles (weather, zones, safety perimeters); vessel drawer with route and history; port staging board; analytics and ESG tabs.
- Reliability: Exponential backoff on transient errors; fallback to cached states; health-check pings; circuit breakers around bursty features.
- Governance: Per-surface credentials, request logging, and audit dashboards using the {status, success, message} envelope.
Conclusion: Build faster with AIS data that’s ready for AHTS operations
The demands of AHTS work—precision positioning, tight scheduling, safety in constrained waters—call for live data and clear analytics. Vessels-api.com brings vessel tracking, fleet batch operations, port intelligence, and IMO CII scoring into a unified, consistent, developer-friendly surface. Whether you’re building a new offshore logistics startup or modernizing an existing control room, this API shortens your path to a reliable maritime product.
Explore what you can build with Vessels API. Spin up an AHTS dashboard, plug in route and congestion intelligence, and add emissions scoring with a few well-structured calls. Ready to see it in action? Try Vessels API for free and start shipping features your crews and planners will actually trust. When you’re ready to build your production workflow, Get started with Vessels API and make AHTS tracking a strength in your maritime stack.
