Wingo Marine API reference

Quick start

1. Create a free account (no card). New accounts get 200 API credits to try the API.
2. Open Developer in the app and create a key. It is shown once — keep it server-side.
3. Ask for any vessel by MMSI or IMO:

curl -H "X-API-Key: $WINGO_KEY" \
  https://marine.wingo.ro/api/public/v1/vessels/211331640

The response headers X-Credits-Cost and X-Credits-Remaining tell you what the call cost and what is left.

Authentication

Send your key in the X-API-Key header on every request. There is no OAuth on the public API. You can hold up to 10 active keys and revoke any of them in the Developer page, which also charts your daily usage.

X-API-Key: ais_••••••••••••••••••••••••••••••••

• Missing header → 401 Cheie API lipsă; unknown or revoked key → 401 Cheie API invalidă.
• Disabled account → 403 Cont dezactivat.
• Never put the key in a browser or mobile app: call the API from your server.

Credits and limits

Every call spends its published cost. Credits come first from your plan's monthly bucket (refilled at each renewal), then from top-up packs (never expire). When both are empty the API answers 402 and charges nothing — there are no overage fees. Plans start at €9.99/month; one-time credit packs need no subscription.

• Rate limit: 10 requests per second per key → 429 above it.
• Lists: pageSize defaults to 50 and is clamped to 100. /vessels/in-bbox returns at most 1000 vessels.
• Track history: up to 168 hours (7 days) of sampled positions.
• Fleet changes need an active subscription and respect the plan's vessel limit; bulk adds take up to 200 ids.

Plans, credit packs and costs →

Endpoints

All routes live under https://marine.wingo.ro/api/public/v1, answer JSON and spend the credit cost shown (live values; the operator can change them, and every response tells you what it cost).

Vessels

Vessels are addressed by MMSI (9 digits) or IMO (7 digits) — never by name, because names are not unique.

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/vessels?search=maersk&category=cargo&pageSize=20"

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/vessels/211331640"

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/vessels/211331640/track?hours=48"

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/vessels/in-bbox?minLat=51.5&minLon=3.5&maxLat=52.2&maxLon=4.6"

Ports

Ports are addressed by UN/LOCODE (5 characters, e.g. ROCND).

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/ports?search=constanta"

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/ports/ROCND"

Fleets

Fleets are watch lists of vessels; the key sees only the fleets of its own account. Reads work on any key; changes need an active subscription.

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/fleets"

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/fleets/3"

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/fleets/3/vessels"

curl -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/fleets/3/positions"

curl -X POST -H "X-API-Key: $WINGO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"211331640","label":"Charter 12"}' \
  "https://marine.wingo.ro/api/public/v1/fleets/3/vessels"

curl -X POST -H "X-API-Key: $WINGO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["211331640","9450648"]}' \
  "https://marine.wingo.ro/api/public/v1/fleets/3/vessels/bulk"

curl -X PATCH -H "X-API-Key: $WINGO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Charter 12"}' \
  "https://marine.wingo.ro/api/public/v1/fleets/3/vessels/211331640"

curl -X DELETE -H "X-API-Key: $WINGO_KEY" \
  "https://marine.wingo.ro/api/public/v1/fleets/3/vessels/211331640"

Satellite position checks

Stored positions are as fresh as the last report our feeds received. When you need a ship's position now, add verify=true to GET /vessels/{id} or GET /fleets/{fleetId}/positions: the server asks an external tracking source for the vessel's latest position and applies it only if it is newer than the stored one. Each vessel actually checked adds 10 credits; a result from the last 5 minutes is served from cache for free.

• A vessel needs an MMSI, an IMO and a name to be checked (otherwise ineligible, free).
• Fleet batches check only vessels whose position is older than 15 minutes, at most 25 per request; batch.capApplied tells you when the cap cut the batch, and vessels your balance cannot cover come back skipped with reason: "no_credits".
• In the app, fleet vessels can also be checked automatically on a schedule (from every 15 minutes); the schedule switches itself off when credits run out.

Responses

Lists are paginated as { "items": [...], "total": N, "page": 1, "pageSize": 50 }. A vessel detail looks like this (list rows have the same fields without dimensions and with eta: null):

{
  "mmsi": 211331640,
  "imo": 9450648,
  "name": "EXAMPLE CARRIER",
  "callsign": "DHLB",
  "shipType": 70,
  "category": "cargo",
  "lat": 51.95,
  "lon": 4.13,
  "sog": 12.4,
  "cog": 88.1,
  "heading": 90,
  "navStatus": 0,
  "destination": "ROTTERDAM",
  "eta": "2026-10-20T06:00:00.000Z",
  "positionTs": "2026-10-19T09:12:00.000Z",
  "dimA": 200, "dimB": 199, "dimC": 16, "dimD": 16,
  "draught": 12.5,
  "unverified": false,
  "marineTrafficId": null
}

Vessel search and area filters

GET /vessels and GET /vessels/in-bbox accept the same filters:

Unverified vessels

Some vessels are known only by name, from a source that does not report an MMSI. They are excluded by default; includeUnverified=true returns them with mmsi: null and unverified: true. Do not use them as a stable identity — they disappear once merged with the real vessel.

Sampling in an area

AIS coverage is very uneven, so in-bbox never returns "the N freshest" (that would be almost only the busiest coasts). When the box holds more than 1000 vessels it is split into a grid and each cell gets a share proportional to its real number of vessels, larger ships first.

Tracks and ports

Track: [{ "lat", "lon", "sog", "cog", "ts" }], oldest first. Port: { "id", "locode", "name", "country", "lat", "lon", "updatedAt" }.

Errors

Body of a 402:

{ "statusCode": 402, "message": "Credite insuficiente", "required": 5, "remaining": 2 }

Webhooks

With a paid plan you register HTTPS endpoints in the Webhooks page of the app. Detectors watch every vessel in your fleets around the clock and POST a signed JSON event when something happens — optionally only for some fleets. Each endpoint has its own secret (shown once, rotatable), a test button and a delivery log.

POST /your/endpoint
Content-Type: application/json
X-AIS-Event: fleet.port_call
X-AIS-Timestamp: 1760865901000
X-AIS-Signature: 7f3c…e91a
Idempotency-Key: 81234
X-AIS-Delivery-Id: 81234
User-Agent: Wingo-Marine-Webhooks/2.0

{
  "event": "fleet.port_call",
  "phase": "enter",
  "port": { "id": 42, "name": "Constanța", "locode": "ROCND" },
  "vessel": { "mmsi": 244660920, "lat": 44.17, "lon": 28.65, "sog": 3.2,
    "cog": null, "heading": null, "navStatus": 0, "destination": null,
    "positionTs": "2026-10-19T12:05:00.000Z" },
  "fleets": [{ "id": 3, "name": "North Sea" }],
  "occurredAt": "2026-10-19T12:05:01.000Z"
}

Verify the signature

X-AIS-Signature is the hex HMAC-SHA256 of ${timestamp}.${rawBody} with the endpoint secret. Use Idempotency-Key to ignore retries of a delivery you already processed.

import { createHmac, timingSafeEqual } from 'crypto';

// rawBody: the request body exactly as received (a string, not re-serialised JSON)
export function verify(rawBody, headers, secret) {
  const ts = headers['x-ais-timestamp'];
  const expected = createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  const got = headers['x-ais-signature'] ?? '';
  return got.length === expected.length &&
    timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Answer with any 2xx. Anything else — redirects included — is retried after 30 s, 2 min, 8 min, 30 min, 2 h; after 20 consecutive failures the endpoint is switched off until you re-enable it.

OpenAPI and LLMs

Generate a client, import the API into Postman or point an AI assistant at it: