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.

27 endpoints
6 resource groups
<1 min typical optimization
RTZ + CSV ECDIS exports
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"
# }

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
  • AlongWave 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"
}

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

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
}

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
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
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
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
# 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
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
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

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);

27 endpoints, 6 resource groups

Scope and coverage at a glance. Browse the full reference

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?

AlongWave's hybrid-AI marine weather forecasts, updated every three hours via rolling satellite assimilation. AlongWave 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.

Start building today.

Request credentials and run your first voyage optimization in minutes.

See verified voyages