# Wingo Marine

> Wingo Marine is a live maritime intelligence platform: a global AIS ship-tracking map, a public ship and port directory covering 261,755 identified vessels, fleet watch lists with signed webhook alerts, on-demand satellite position checks and a credit-metered REST API (OpenAPI 3.1). Built by Freevox (Romania) as part of the Wingo product suite.

- Data: vessels broadcast identity and position over AIS; Wingo Marine ingests a global terrestrial AIS stream in real time (about 155 messages per second), adds receiver stations and extra map sources where that stream is thin, and can ask an external tracking source for one vessel's latest position on demand ("satellite check"). Positions from secondary sources pass a plausibility check: physically impossible jumps are rejected.
- Size (as of 2026-10-19): 261,755 vessels in the public directory; 36,488 reported a position in the last hour; 12,256 ports.
- Coverage is uneven, as with any terrestrial AIS network: dense near the coasts of Europe and North America, sparser in parts of Asia, Africa and on the open ocean. Every vessel page shows when its last position was received; an old timestamp means the ship has been out of receiver range since then.
- Identifiers: MMSI (9 digits) is the primary key of a vessel; IMO (7 digits, with a check digit) is shown only when valid. Vessel names are not unique. Ports are identified by UN/LOCODE.
- History is sampled (not every raw AIS message is stored); API track history covers up to the last 7 days.
- Languages: the website is in English and Romanian (switched client-side on the same URL); the ship directory and API are in English.

## Main pages

- [Home](https://marine.wingo.ro/): what the platform does — live map, fleets, alerts, satellite checks and the API
- [Pricing](https://marine.wingo.ro/pricing): free account, monthly plans, credit packs and the credit cost of every API call
- [Ship directory](https://marine.wingo.ro/ships): search any vessel by name, MMSI or IMO; one page per ship with last position, destination, ETA and particulars
- [Ships by flag](https://marine.wingo.ro/ships/flags): vessels grouped by flag state
- [Port directory](https://marine.wingo.ro/ships/ports): ports by country with vessels in port, nearby and expected arrivals
- [API reference](https://marine.wingo.ro/docs/api): the public REST API — endpoints, live credit costs, rate limits, satellite checks and webhooks

## Features (free vs paid)

- Live global map (free account): positions stream in as ships report; filter by category, AIS ship type, flag, speed, navigational status and destination; search by name, MMSI or IMO; port layer. Exact coordinates and the 7-day track in the vessel panel need a paid plan.
- Ship and port directory (public, no account): one page per identified vessel with its last position relative to the nearest port or sea area, decoded destination, ETA, flag, type and dimensions; lists by category and by flag; port pages with vessels in port, nearby and expected arrivals.
- Fleets (paid plans): watch lists of vessels by MMSI or IMO, bulk paste of up to 200 ids, labels, the fleet highlighted on the map with hours since each ship last reported, CSV export. A plan limits the number of unique vessels across fleets.
- Fleet alerts (paid plans): detectors watch every fleet vessel around the clock — port call (3 km around the port), gone silent (default threshold 6 h), destination changed and sampled position (every 5 min) — and POST signed webhooks (HMAC-SHA256, automatic retries, optional per-fleet filter, test event, delivery log, rotatable secret).
- Satellite position checks (credits per vessel checked): ask for a vessel's position now from an external tracking source; applied only if newer than the stored one. Available on the public API with `verify=true` (any key with credits), on the fleet page, and on a per-vessel schedule for fleet ships (from every 15 minutes, paid plans).
- Public REST API (any account, credits): vessels by MMSI or IMO, search with filters, 7-day tracks, vessels in a bounding box, ports by UN/LOCODE, fleet read/write. Up to 10 active keys per account, daily usage chart in the Developer page, 10 requests/second per key.
- Not offered today: native mobile apps, vessel photos, position history older than 7 days, raw AIS data feeds.

## Ship categories

- [Cargo vessels](https://marine.wingo.ro/ships/type/cargo): Container ships, bulk carriers, general cargo and ro-ro vessels. (35,075 vessels)
- [Tankers](https://marine.wingo.ro/ships/type/tanker): Crude, product, chemical and gas carriers. (14,595 vessels)
- [Passenger vessels](https://marine.wingo.ro/ships/type/passenger): Cruise ships, ferries and passenger ro-ro vessels. (9,311 vessels)
- [High-speed craft](https://marine.wingo.ro/ships/type/high-speed): Fast ferries, hydrofoils and other high-speed craft. (1,626 vessels)
- [Fishing vessels](https://marine.wingo.ro/ships/type/fishing): Trawlers, longliners and other fishing vessels. (17,677 vessels)
- [Tugs & towing vessels](https://marine.wingo.ro/ships/type/tug): Harbour tugs, towing and pushing vessels. (11,607 vessels)
- [Yachts & pleasure craft](https://marine.wingo.ro/ships/type/pleasure): Motor yachts, superyachts and leisure boats. (66,787 vessels)
- [Sailing vessels](https://marine.wingo.ro/ships/type/sailing): Sailing yachts, tall ships and sail training vessels. (59,413 vessels)
- [Military & naval vessels](https://marine.wingo.ro/ships/type/military): Naval and military vessels that broadcast AIS. (1,037 vessels)
- [Special-purpose vessels](https://marine.wingo.ro/ships/type/special): Pilot boats, search & rescue, dredgers, law enforcement and more. (10,340 vessels)
- [Other vessels](https://marine.wingo.ro/ships/type/other): Vessels of other or unspecified types. (34,282 vessels)

## Developers

- [API reference](https://marine.wingo.ro/docs/api): human-readable documentation of the public API
- [OpenAPI 3.1 spec](https://marine.wingo.ro/openapi.json): machine-readable description of every endpoint, parameter, response and webhook payload, with live credit costs
- [Full reference for LLMs](https://marine.wingo.ro/llms-full.txt): this file plus the complete public API reference, pricing and webhook events
- [Integration skill](https://marine.wingo.ro/skills/wingo-marine/SKILL.md): how an AI agent or an app connects to the public API and webhooks
- Public REST API base URL: `https://marine.wingo.ro/api/public/v1` — authenticate with the `X-API-Key` header (keys are created after sign-up in the Developer page); every call costs published credits; default rate limit 10 requests/second per key.

## Pricing

- Free account (no card): live global map with filters and the port layer, ship and port search, the public directory, API keys and the whole public API paid per call in credits (including vessel tracks and satellite checks with `verify=true`). New accounts receive 200 free API credits once their email is verified. Without a plan you cannot create fleets or webhook endpoints, and the map's vessel panel hides exact coordinates and track history.
- Starter: €9.99/month — 10,000 API credits per month, up to 10 vessels across fleets, 1 webhook endpoint, fleet alerts, exact coordinates and 7-day track history on the map, scheduled satellite checks for fleet vessels.
- Pro: €29.99/month — 50,000 API credits per month, up to 50 vessels across fleets, 3 webhook endpoints, fleet alerts, exact coordinates and 7-day track history on the map, scheduled satellite checks for fleet vessels.
- Business: €99.99/month — 250,000 API credits per month, up to 250 vessels across fleets, 10 webhook endpoints, fleet alerts, exact coordinates and 7-day track history on the map, scheduled satellite checks for fleet vessels.
- One-time credit packs (never expire): 5,000 credits for €5, 15,000 credits for €12, 50,000 credits for €35.
- Monthly plan credits reset at each renewal; top-up credits are permanent. When both are empty the API answers HTTP 402 — there are no overage charges. Payments are handled by Stripe; plans can be changed or cancelled at any time.
- Prices are in EUR and may change; the Pricing page and GET /api/v1/billing/plans are authoritative.

## Optional

- [Sitemap](https://marine.wingo.ro/sitemap.xml): every indexable ship, port and directory page
- [Freevox](https://freevox.ro): the company that builds Wingo Marine
- [Wingo](https://wingo.ro): the product suite it belongs to
- Contact: office@freevox.ro

---

# Wingo Marine public API reference (v1)

Generated 2026-10-19T03:21:28.087Z from the live configuration. Costs and limits can be changed by the operator; the response headers always tell you what a call cost.

## Base URL and authentication

- Base URL: `https://marine.wingo.ro/api/public/v1`
- Every request carries `X-API-Key: <your key>`. Keys are created and revoked in the Developer page after signing in; a key is shown once. Keep it server-side — never ship it in a browser app.
- 401 = missing or invalid key; 403 = disabled account, or a fleet change without an active subscription.
- Vessels are addressed by MMSI (9 digits) or IMO (7 digits); ports by UN/LOCODE (5 characters). An invalid identifier returns 400.

```bash
curl -H "X-API-Key: $WINGO_MARINE_API_KEY" "https://marine.wingo.ro/api/public/v1/vessels?search=maersk"
```

## Endpoints and credit costs

| Method & path | What it returns | Cost |
| --- | --- | --- |
| `GET /vessels?search=&page=&pageSize=` | Search vessels by name, MMSI or IMO (paginated, pageSize ≤ 100) | 2 credits |
| `GET /vessels/{mmsi\|imo}` | Vessel details and last position (`?verify=true` adds a live satellite check) | 1 credit |
| `GET /vessels/{mmsi\|imo}/track?hours=` | Recent track, sampled positions (hours ≤ 168) | 5 credits |
| `GET /vessels/in-bbox?minLat=&minLon=&maxLat=&maxLon=` | Vessels in a bounding box (≤ 1000, grid-sampled by real density) | 5 credits |
| `GET /ports?search=&country=&page=` | Search ports (paginated) | 1 credit |
| `GET /ports/{locode}` | Port details by UN/LOCODE | 1 credit |
| `GET /fleets` | The key owner's fleets with vessel counts | 1 credit |
| `GET /fleets/{id}` | One fleet with its vessels | 1 credit |
| `GET /fleets/{id}/vessels` | Fleet memberships only | 1 credit |
| `GET /fleets/{id}/positions` | Positions of the whole fleet in one call (`?verify=true` supported) | 2 credits |
| `POST /fleets/{id}/vessels` | Add a vessel `{ "id", "label?" }` (active subscription required) | 2 credits |
| `POST /fleets/{id}/vessels/bulk` | Add up to 200 vessels `{ "ids": [...] }` | 2 credits |
| `PATCH /fleets/{id}/vessels/{mmsi}` | Update a label `{ "label" }` | 1 credit |
| `DELETE /fleets/{id}/vessels/{mmsi}` | Remove a vessel from a fleet | 1 credit |

Satellite check: `verify=true` on `GET /vessels/{id}` or `GET /fleets/{id}/positions` adds 10 credits per vessel actually checked. A result served from the 5-minute cache, or a vessel the batch skipped, costs nothing. The vessel needs an MMSI, an IMO and a name. Each payload gets a `verification` object with `status` (ok, cached, queued, skipped, ineligible, failed), `verifiedAt`, `positionTs`, `source` and `reason`. Fleet batches check only vessels whose position is older than 15 minutes, at most 25 per request, and report `batch.capApplied`.

Fleets are visible only to the key that owns them. Fleet changes require an active subscription and respect the plan's unique-vessel limit (the same vessel in two fleets uses one slot).

## Responses

- Lists: `{ "items": [...], "total": N, "page": 1, "pageSize": 50 }` (default pageSize 50, clamped to 100).
- Vessel: `mmsi, imo, name, callsign, shipType, category, lat, lon, sog, cog, heading, navStatus, destination, eta, positionTs, dimA, dimB, dimC, dimD, draught, unverified` (dimensions and ETA on the detail route only).
- Filters on `GET /vessels` and `GET /vessels/in-bbox`: `category`, `shipType`, `navStatus`, `minSpeed`, `flag`, `destination`, `signalAgeMaxMin`, `minLength`, `maxLength`, `includeUnverified` (lists comma-separated).
- Vessels known only by name from a source without MMSI are excluded by default; `includeUnverified=true` returns them with `mmsi: null` and `unverified: true` (not a stable identity).
- Track: `[{ "lat", "lon", "sog", "cog", "ts" }]`. Port: `id, locode, name, country, lat, lon, updatedAt`.
- Every successful response carries `X-Credits-Cost` and `X-Credits-Remaining`.

## Errors and limits

| Code | Meaning |
| --- | --- |
| 400 | Invalid parameter (MMSI/IMO/LOCODE, bbox, pagination, bulk) |
| 401 | Missing or invalid API key |
| 402 | Not enough credits — body `{ "statusCode": 402, "required": N, "remaining": M }` |
| 403 | Disabled account, or subscription required for fleet changes |
| 404 | Vessel, port or fleet not found |
| 409 | Vessel already in the fleet |
| 429 | Rate limit exceeded (default 10 requests/second per key) |

## Webhooks

Endpoints are managed in the Webhooks page (paid plans) and deliver events for the vessels in your fleets, optionally filtered to some fleets. Each endpoint has a test button, a delivery log and a rotatable secret:

- `fleet.position` — Sampled position of a watched vessel.
- `fleet.port_call` — A vessel entered or left a port geofence (`phase: enter|exit`).
- `fleet.gone_silent` — A vessel stopped reporting for longer than the silence threshold.
- `fleet.destination_changed` — The AIS destination of a vessel changed.

Each delivery is a JSON POST with `X-AIS-Event`, `X-AIS-Timestamp` (ms), `X-AIS-Signature` and `Idempotency-Key`. The signature is hex HMAC-SHA256 of `${timestamp}.${rawBody}` with the endpoint secret (shown once). Any non-2xx answer (redirects included) is retried after 30 s, 2 min, 8 min, 30 min, 2 h; after 20 consecutive failures the endpoint is disabled.

```js
import { createHmac, timingSafeEqual } from 'crypto';
function verify(rawBody, headers, secret) {
  const expected = createHmac('sha256', secret).update(`${headers['x-ais-timestamp']}.${rawBody}`).digest('hex');
  const got = headers['x-ais-signature'] ?? '';
  return got.length === expected.length && timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
```

Full payload schemas: the `webhooks` section of https://marine.wingo.ro/openapi.json; human-readable reference: https://marine.wingo.ro/docs/api.

## Public directory URLs

- Vessel: `https://marine.wingo.ro/ship/{name-slug}-{mmsi}` (a wrong slug redirects to the canonical one)
- Port: `https://marine.wingo.ro/port/{name-slug}-{id}`
- Category: `https://marine.wingo.ro/ships/type/{slug}`; flag: `https://marine.wingo.ro/ships/flag/{iso2}`; ports by country: `https://marine.wingo.ro/ships/ports/{iso2}`
- Search: `https://marine.wingo.ro/ships?q={name, MMSI or IMO}`