Embed voyage
optimization
in any product.
VesselFront's REST API gives you programmatic access to the same AI-powered routing engine used by commercial fleets. Weather-aware, ECDIS-compatible, claims-ready by design.
curl https://api.vesselfront.com/v1/organization \
-H "X-API-Key: vf_live_your_key_here"
# → 200 OK
"id": "7a510548-aec2-49b3-…",
"name": "Acme Shipping Ltd" Designed for the teams that move commercial shipping
Fleet operators
Automate voyage planning without replacing your FMS. Submit vessel parameters once; receive optimized waypoints on every departure.
Platform builders
Embed route optimization as a feature in your maritime SaaS. One endpoint call returns a complete route your users can act on immediately.
P&I clubs & underwriters
Every route is exported with a SHA-256 integrity hash — the immutable evidence trail your P&I submissions require.
Port & logistics teams
Pull accurate ETAs backed by real weather forecasts and vessel performance curves. Query active chartings or push live telemetry for deviation tracking.
One endpoint.
The full routing engine.
A single POST to /charting triggers the VesselFront multi-agent engine. Weather forecasts, ECA zones, war-zone avoidance, vessel performance curves, and your custom constraints are applied simultaneously — returning a complete set of waypoints, typically within a minute depending on voyage parameters.
- Configure wave height limits, wind Beaufort scale, max north latitude
- Optimization types: fuel efficiency, ETA, or balanced — set per request
- AlongRoute hybrid-AI forecasts — 3-hour rolling updates, satellite-assimilated
- Natural-language explanation available per route for operator briefings
"id": "cafb8188-674b-424f-88dc-…",
"portFromName": "AABENRAA",
"portToName": "AAHEIM",
"vesselId": "66b72ad4-…",
"optimizationType": "1",
"routeType": "1",
"avoidWarZones": true,
"avoidEca": false,
"speedRangeMin": 11,
"speedRangeMax": 13,
"startDate": "2026-06-01T00:00:00.000Z"
Route output that holds
up in court.
Every optimized route can be exported in RTZ 1.1 format for direct ECDIS upload, or as a signed CSV with a SHA-256 integrity hash. The hash confirms the file wasn't altered after download — a requirement under most P&I standard forms.
- RTZ 1.1 XML — IMO-recommended format, accepted by all major ECDIS
- SHA-256 signed CSV — immutable record for P&I submissions
- FOC estimation endpoint for fuel baseline and sustainability reporting
- Critical-points endpoint for segment-level voyage analysis
# RTZ 1.1 — direct ECDIS import
GET /v1/charting/{id}/rtz
→ RTZ 1.1 XML · ECDIS-ready
# Signed CSV — claims documentation
GET /v1/charting/{id}/csv
→ X-Content-Hash: sha256:a3f9…
# Fuel oil consumption estimate
GET /v1/charting/{id}/foc
→ FOC baseline in mt/day
# Segment-level critical points
GET /v1/charting/{id}/critical-points
→ Key waypoints with weather state
Live vessel data,
in your pipeline.
Push AIS-derived position, engine state, and fuel consumption data to the Telemetry API. Retrieve historical records with time-range filters and pagination. The data feeds voyage deviation tracking, fuel performance analytics, and CII reporting.
- Required: position, speed, heading, RPM, fuel consumption, draft
- Optional: wind, sea state, trim, main engine power
- GET with from/to timestamps returns paginated records for any window
- Works over any connection — VSAT, LTE, or store-and-forward
"timestamp": "2026-06-01T14:23:00.000Z",
// Position
"latitude": 57.41,
"longitude": 8.12,
"heading": 342,
// Performance
"speed": 12.4,
"rpm": 55,
"engineLoad": 72,
"fuelConsumption": 24.6,
"draft": 14.0,
// Optional
"windSpeed": 8.2,
"seaState": 3
Six operations, end to end
Common integration patterns — from first call to production.
POST /v1/charting Submit voyage parameters, receive optimized waypoints
POST to /charting with your vessel's DWT, LBP, pitch, and departure port. The engine applies live weather forecasts, ECA boundaries, piracy avoidance, and your vessel's performance curve simultaneously.
- Wave height, wind limits, and war zone avoidance are configurable per request
- speedRangeMin and speedRangeMax let the engine find the optimal transit speed
- Poll GET /charting/{id} or query /charting/active to track ongoing voyages
curl -X POST https://api.vesselfront.com/v1/charting \
-H "X-API-Key: vf_live_your_key" \
-d '{
"vesselId": "66b72ad4-...",
"portFromName": "AABENRAA",
"portToName": "AAHEIM",
"startDate": "2026-06-01T00:00:00.000Z",
"speedRangeMin": 11,
"speedRangeMax": 13,
"draft": 14, "trim": 2, "rpm": 55,
"optimizationType": "1",
"avoidWarZones": true,
"avoidEca": false
}' POST /v1/constraints Block routes through any geographic area
Create GeoJSON polygon constraints via POST /constraints. Constraints can be applied globally across all vessels, scoped to your organization, or limited to specific vessel types.
- Constraint types: USER_DEFINED, PREDEFINED, MILITARY, HIGH_RISK
- Set start_date and end_date to activate time-limited zones
- The routing engine respects all active constraints automatically on every future charting
curl -X POST https://api.vesselfront.com/v1/constraints \
-H "X-API-Key: vf_live_your_key" \
-d '{
"name": "Black Sea Exclusion Zone",
"type": "HIGH_RISK",
"level": "ORGANIZATION",
"geometry": {
"type": "Polygon",
"coordinates": [[[31.5,46.5],[34.0,46.5],
[34.0,44.0],[31.5,44.0],[31.5,46.5]]]
},
"is_active": true,
"start_date": "2026-06-01",
"end_date": "2026-12-31"
}' POST /v1/telemetry/{vesselId} Stream live vessel data against the planned route
Push AIS-derived position, speed, RPM, and fuel consumption via POST /telemetry/{vesselId}. Query historical telemetry with time-range filters and pagination.
- Required fields: latitude, longitude, speed, heading, rpm, fuelConsumption, draft, engineLoad
- Optional: windSpeed, windDirection, seaState, trimFore, trimAft, mePower
- GET /telemetry/{id}?from=…&to=… returns paginated records for any time window
curl -X POST https://api.vesselfront.com/v1/telemetry/66b72ad4-... \
-H "X-API-Key: vf_live_your_key" \
-d '{
"timestamp": "2026-06-01T14:23:00.000Z",
"latitude": 57.41,
"longitude": 8.12,
"speed": 12.4,
"heading": 342,
"rpm": 55,
"fuelConsumption": 24.6,
"draft": 14.0,
"engineLoad": 72
}' GET /v1/charting/{id}/rtz Download routes in formats accepted by every ECDIS system
GET /charting/{id}/rtz returns the route in RTZ 1.1 XML format, accepted by all major ECDIS systems. GET /charting/{id}/csv returns a signed CSV with a SHA-256 integrity hash for claims documentation.
- RTZ 1.1 is the IMO-recommended interchange format for electronic chart systems
- The CSV hash confirms the route was not altered after download — required for P&I submissions
- Both formats include the full waypoint sequence, speeds, and segment data
# RTZ 1.1 — direct ECDIS import
curl https://api.vesselfront.com/v1/charting/cafb8188-.../rtz \
-H "X-API-Key: vf_live_your_key" \
-o route.rtz
# Signed CSV — claims documentation
curl https://api.vesselfront.com/v1/charting/cafb8188-.../csv \
-H "X-API-Key: vf_live_your_key" \
-o route.csv
# Response header: X-Content-Hash: sha256:a3f9... GET /v1/charting/{id}/foc Benchmark fuel savings against the optimized baseline
GET /charting/{id}/foc returns a fuel oil consumption estimation for any voyage. The model uses the vessel's actual pitch, DWT, LBP, and service speed stored in the vessel profile.
- FOC output gives the optimized baseline your ops team can hold against actual consumption
- Feed the estimate into your reporting workflows or sustainability dashboards
- Pair with GET /charting/{id}/critical-points to understand where fuel is consumed
curl https://api.vesselfront.com/v1/charting/cafb8188-.../foc \
-H "X-API-Key: vf_live_your_key"
# Also available: critical waypoints for the voyage
curl https://api.vesselfront.com/v1/charting/cafb8188-.../critical-points \
-H "X-API-Key: vf_live_your_key" GET /v1/charting/{id}/explanation Get a plain-English explanation of any routing decision
GET /charting/{id}/explanation returns an LLM-generated rationale for the route — why specific waypoints were chosen, what hazards were avoided, and what trade-offs were made.
- Useful for operator briefings, compliance documentation, and incident reviews
- The explanation references the actual weather windows, ECA zones, and constraints active at route time
- Rate-limited to 10 requests per hour per organization
curl https://api.vesselfront.com/v1/charting/cafb8188-.../explanation \
-H "X-API-Key: vf_live_your_key"
# → 200 OK
# {
# "summary": "Route transits via the Norwegian Trench
# corridor to avoid forecasted 4.2m wave heights in
# the central North Sea on June 2. The ECA boundary
# is cleared by 12nm at all waypoints.",
# "generatedAt": "2026-06-01T15:00:00.000Z"
# } From zero to first route in three calls
Verify your key, register a vessel, optimize a route.
# 1. Verify your key
curl https://api.vesselfront.com/v1/organization \
-H "X-API-Key: vf_live_your_key_here"
# 2. Create a vessel profile
curl -X POST https://api.vesselfront.com/v1/vessel \
-H "X-API-Key: vf_live_your_key_here" \
-d '{ "name":"MV Atlantic Star", "dwt":75000, "loa":229, "lbp":220,
"breadth":32.2, "depth":20.1, "draftDesign":14.5,
"serviceSpeed":14.5, "draftScant":15.0, "pitch":5.2,
"dateConstructed":"2015-06-01" }'
# 3. Optimize a route
curl -X POST https://api.vesselfront.com/v1/charting \
-H "X-API-Key: vf_live_your_key_here" \
-d '{ "vesselId":"<vessel-id-from-step-2>",
"portFromName":"AABENRAA", "portToName":"AAHEIM",
"latFrom":55.03, "lngFrom":9.46,
"latTo":62.06, "lngTo":5.51,
"startDate":"2026-06-01T00:00:00.000Z",
"speedRangeMin":11, "speedRangeMax":13,
"draft":14, "trim":2, "rpm":55,
"dwt":68439, "lbp":220, "pitch":5.435,
"optimizationType":"1", "routeType":"1" }'import requests
BASE = "https://api.vesselfront.com/v1"
HEADERS = {"X-API-Key": "vf_live_your_key_here"}
# 1. Verify your key
org = requests.get(f"{BASE}/organization", headers=HEADERS).json()
print(org["name"])
# 2. Create a vessel profile
vessel = requests.post(f"{BASE}/vessel", headers=HEADERS, json={
"name": "MV Atlantic Star", "dwt": 75000,
"loa": 229, "lbp": 220, "breadth": 32.2,
"depth": 20.1, "draftDesign": 14.5,
"serviceSpeed": 14.5, "draftScant": 15.0,
"pitch": 5.2, "dateConstructed": "2015-06-01",
}).json()
# 3. Optimize a route
charting = requests.post(f"{BASE}/charting", headers=HEADERS, json={
"vesselId": vessel["id"],
"portFromName": "AABENRAA",
"portToName": "AAHEIM",
"latFrom": 55.03, "lngFrom": 9.46,
"latTo": 62.06, "lngTo": 5.51,
"startDate": "2026-06-01T00:00:00.000Z",
"speedRangeMin": 11, "speedRangeMax": 13,
"draft": 14, "trim": 2, "rpm": 55,
"dwt": 68439, "lbp": 220, "pitch": 5.435,
"optimizationType": "1", "routeType": "1",
}).json()
print(charting["id"])const BASE = "https://api.vesselfront.com/v1";
const HEADERS = { "X-API-Key": "vf_live_your_key_here",
"Content-Type": "application/json" };
const api = (path, body) => fetch(BASE + path, {
method: body ? "POST" : "GET",
headers: HEADERS,
body: body ? JSON.stringify(body) : undefined,
}).then(r => r.json());
// 1. Verify your key
const org = await api("/organization");
console.log(org.name);
// 2. Create a vessel profile
const vessel = await api("/vessel", {
name: "MV Atlantic Star", dwt: 75000,
loa: 229, lbp: 220, breadth: 32.2,
depth: 20.1, draftDesign: 14.5,
serviceSpeed: 14.5, draftScant: 15.0,
pitch: 5.2, dateConstructed: "2015-06-01",
});
// 3. Optimize a route
const charting = await api("/charting", {
vesselId: vessel.id,
portFromName: "AABENRAA", portToName: "AAHEIM",
latFrom: 55.03, lngFrom: 9.46,
latTo: 62.06, lngTo: 5.51,
startDate: "2026-06-01T00:00:00.000Z",
speedRangeMin: 11, speedRangeMax: 13,
draft: 14, trim: 2, rpm: 55,
dwt: 68439, lbp: 220, pitch: 5.435,
optimizationType: "1", routeType: "1",
});
console.log(charting.id); Common questions before you start
How do I get an API key?
Email support@vesselfront.com with your organization name and intended use case. You'll receive a vf_live_ key for production during onboarding. Access is currently granted on a rolling basis.
How long does a route optimization take?
Route optimizations typically complete within a minute. The exact duration depends on voyage parameters — longer passages, complex constraint configurations, or unusual routing challenges may take somewhat longer.
What weather data powers the routing engine?
The engine uses AlongRoute's hybrid-AI marine weather forecasts, updated every 3 hours via rolling satellite assimilation. AlongRoute applies deep-learning corrections to raw numerical weather prediction outputs, delivering better wave height and wind accuracy than standard Copernicus baselines. Weather parameters are applied along the entire route corridor, not just at departure.
Can I restrict routing to avoid specific geographic areas?
Yes. POST to /constraints with a GeoJSON polygon and set the level (GLOBAL, ORGANIZATION, or VESSEL_TYPE). The routing engine respects all active constraints automatically on every subsequent charting. You can set start_date and end_date to activate time-limited zones.
What export formats does the API support?
RTZ 1.1 XML for direct ECDIS import (/charting/{id}/rtz), and signed CSV with a SHA-256 integrity hash (/charting/{id}/csv). The hash confirms the route file was not altered after download — a requirement for P&I club submissions under most standard forms.
27 endpoints, 6 resource groups
Scope and coverage at a glance. Full reference →
Confirm key validity, retrieve org metadata.
View endpoints →Manage vessel profiles — the performance data the engine runs on.
View endpoints →Create optimizations, export routes, get FOC and critical-point data.
View endpoints →Define geographic no-go polygons scoped globally or per org.
View endpoints →Per-customer routing rules for multi-tenant integrations.
View endpoints →Push and query real-time vessel position and engine performance data.
View endpoints →
The first route is free.
Start building today.
Request credentials and run your first voyage optimization in minutes. No commitment, no card required.
Questions? support@vesselfront.com