API Docs

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.

Request API access Full reference
27 endpoints
6 resource groups
<1 min typical optimization
RTZ + CSV ECDIS exports
Route cafb8188-… AABENRAA → AAHEIM
Speed range11–13 kn
Draft14.0 m
War zonesavoided
ECA statuscleared
RTZCSV SHA-256 signed
GET · /v1/organization bash 
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"
# }
Who builds with this

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.

Route optimization

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
See the workflows
POST · /v1/charting 201 Created · json 
{
  "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"
}
Compliance & export

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
GET
/v1/charting/{id}/rtz
RTZ 1.1 XML — ECDIS-ready
GET
/v1/charting/{id}/csv
X-Content-Hash: sha256:a3f9…
GET
/v1/charting/{id}/foc
FOC baseline in mt/day
GET
/v1/charting/{id}/critical-points
Key waypoints with weather state
Real-time telemetry

Live vessel data, in your pipeline.

Push AIS-derived position, engine state, and fuel consumption 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
POST · /v1/telemetry/{vesselId} 201 Created · json 
{
  "timestamp":       "2026-06-01T14:23:00.000Z",
  "latitude":        57.41,
  "longitude":       8.12,
  "heading":         342,
  "speed":           12.4,
  "rpm":             55,
  "engineLoad":      72,
  "fuelConsumption": 24.6,
  "draft":           14.0,
  "windSpeed":       8.2,
  "seaState":        3
}
API workflows

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
View in reference
POST /v1/charting bash 
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
View in reference
POST /v1/constraints bash 
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: 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
View in reference
POST /v1/telemetry/{vesselId} bash 
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
View in reference
GET /v1/charting/{id}/rtz bash 
# 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 estimate 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 reporting workflows or sustainability dashboards
  • Pair with GET /charting/{id}/critical-points to understand where fuel is consumed
View in reference
GET /v1/charting/{id}/foc bash 
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, 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
View in reference
GET /v1/charting/{id}/explanation bash 
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 12 nm at all waypoints.",
#   "generatedAt": "2026-06-01T15:00:00.000Z"
# }
Verification & compliance

Routes the API returns are the same routes that defend a P&I claim.

Bureau Veritas SMART
EnE3-Em-W (2026) — engine certification
RTZ 1.1 · IMO-recommended
Native export — drops straight into ECDIS
GDPR · EU-sovereign
Data never leaves the bloc unless you send it
SHA-256 signed CSV
Tamper-evident exports for claims documentation
Quick start

From zero to first route in three calls

Verify your key, register a vessel, optimize a route. Available in cURL, Python, Node.js. Postman collection

1

Verify your API key

Send a GET to /organization with your key in the X-API-Key header.

GET · /v1/organization bash 
curl https://api.vesselfront.com/v1/organization \
  -H "X-API-Key: vf_live_your_key_here"

# → 200 OK
# {
#   "id":   "1ec61828-fb01-4d40-9ed5-...",
#   "name": "Your Organization"
# }
2

Create a vessel profile

Vessel particulars are the performance baseline every routing call inherits.

POST · /v1/vessel 
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"
  }'
import requests

BASE = "https://api.vesselfront.com/v1"
HEADERS = {"X-API-Key": "vf_live_your_key_here"}

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()
const BASE = "https://api.vesselfront.com/v1";
const HEADERS = {
  "X-API-Key": "vf_live_your_key_here",
  "Content-Type": "application/json",
};

const vessel = await fetch(`${BASE}/vessel`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    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",
  }),
}).then(r => r.json());
3

Optimize your first route

POST departure parameters; the engine returns the optimized track in under a minute.

POST · /v1/charting 
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"
  }'
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 charting = await fetch(`${BASE}/charting`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    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",
  }),
}).then(r => r.json());
console.log(charting.id);
Endpoint overview

27 endpoints, 6 resource groups

Scope and coverage at a glance. Browse the full reference

Group Count What it covers
Organization 1 Confirm key validity, retrieve org metadata. View endpoints Vessel 6 Manage vessel profiles — the performance data the engine runs on. View endpoints Charting 11 Create optimizations, export routes, get FOC and critical-point data. View endpoints Constraints 3 Define geographic no-go polygons scoped globally or per organization. View endpoints Client Data 4 Per-customer routing rules for multi-tenant integrations. View endpoints Telemetry 2 Push and query real-time vessel position and engine performance data. View endpoints
FAQ

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 granted on a rolling basis.

How long does a route optimization take?

Typically under a minute. Exact duration varies with voyage parameters — longer passages, complex constraints, or unusual routing challenges may take longer.

What weather data powers the routing engine?

AlongRoute's hybrid-AI marine weather forecasts, updated every three hours via rolling satellite assimilation. AlongRoute applies deep-learning corrections to raw numerical weather prediction outputs, delivering superior wave-height and wind accuracy versus standard Copernicus baselines. Weather is applied along the entire route corridor, not just at departure.

Can I restrict routing to avoid specific geographic areas?

POST to /constraints with a GeoJSON polygon and set level (GLOBAL, ORGANIZATION, or VESSEL_TYPE). The routing engine respects all active constraints automatically on every subsequent charting call. Set start_date and end_date for 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 SHA-256 integrity hash (/charting/{id}/csv). The hash confirms the route file is unaltered after download — required for P&I club submissions.

The first route is free.

Request credentials and run your first voyage optimization in minutes. No commitment, no card required.

Request API access See verified voyages