# VesselFinder API

> VesselFinder returns vessel locations, voyage information, and ship details as a workflow and API.

Get vessel location returns public ship positions, voyage information, and vessel details. It requires a ship name, IMO, or MMSI; ship type and flag country are optional matching inputs.

- Page: https://fous.com/workflows/vesselfinder
- Handle: `@vesselfinder`
- Category: [Logistics](https://fous.com/workflows/category/logistics)
- Source website: https://vesselfinder.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with VesselFinder.

## Methods

### Get vessel location

Operation `get_vessel_location`, version 1. 1 credit per call.

Find a ship by name, IMO or MMSI and return its public position, voyage and vessel details. For very common names, alternatives are drawn from the first 8 matching search pages; coordinates may be rounded as displayed by VesselFinder, and paid-only details are null.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `ship_name` | string | yes | `"Ever Given"` | Ship name, IMO or MMSI, for example Ever Given or 9811000. |
| `ship_type` | string | no | `"passenger"` | Type to match when ships share a name, for example passenger. |
| `flag_country` | string | no | `"Bermuda"` | Flag country to match, for example Bermuda. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "ship_name"
  ],
  "properties": {
    "ship_name": {
      "type": "string",
      "description": "Ship name, IMO or MMSI, for example Ever Given or 9811000.",
      "examples": [
        "Ever Given",
        "Queen Mary 2",
        "9811000"
      ]
    },
    "ship_type": {
      "enum": [
        "any",
        "container",
        "tanker",
        "cargo",
        "passenger",
        "other"
      ],
      "type": "string",
      "default": "any",
      "description": "Type to match when ships share a name, for example passenger.",
      "examples": [
        "passenger"
      ]
    },
    "flag_country": {
      "type": "string",
      "description": "Flag country to match, for example Bermuda.",
      "examples": [
        "Bermuda"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "ship_name": "Ever Given"
    },
    {
      "ship_name": "Queen Mary 2",
      "ship_type": "passenger",
      "flag_country": "Bermuda"
    },
    {
      "ship_name": "9811000"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `imo` | string or null | `"9811000"` |  |
| `mmsi` | string or null | `"636026627"` |  |
| `latitude` | number or null | `26` |  |
| `last_port` | string or null | `"Hamburg, Germany"` |  |
| `longitude` | number or null | `-16` |  |
| `ship_name` | string or null | `"EVER GIVEN"` |  |
| `ship_type` | string or null | `"Container Ship"` |  |
| `photo_link` | string or null | `"https://static.vesselfinder.net/ship-photo/9811000-353136000-47a37bcd0d022df56c45b94d8db6b20d/1?v1"` |  |
| `year_built` | integer or null | `2018` |  |
| `speed_knots` | number or null | `18.4` |  |
| `flag_country` | string or null | `"Liberia"` |  |
| `width_meters` | number or null | `58.8` |  |
| `gross_tonnage` | number or null | `219079` |  |
| `length_meters` | number or null | `399.94` |  |
| `other_matches` | array |  |  |
| `other_matches[].ship_name` | string | `"TITANIC"` |  |
| `other_matches[].ship_type` | string or null | `"Yacht"` |  |
| `other_matches[].flag_country` | string or null | `"Unknown"` |  |
| `course_degrees` | number or null | `209.5` |  |
| `departure_time` | string or null | `"Sep 23, 19:02 UTC"` |  |
| `estimated_arrival` | string or null | `"Oct 23, 17:00"` |  |
| `navigation_status` | string or null | `"Under way"` |  |
| `position_received` | string or null | `"1 min ago"` |  |
| `vesselfinder_link` | string or null | `"https://www.vesselfinder.com/vessels/details/9811000"` |  |
| `reported_destination` | string or null | `"Singapore, Singapore"` |  |

**Example input**

```json
{
  "ship_name": "Ever Given"
}
```

**Example output**

```json
{
  "imo": "9811000",
  "mmsi": "636026627",
  "latitude": 26,
  "last_port": "Hamburg, Germany",
  "longitude": -16,
  "ship_name": "EVER GIVEN",
  "ship_type": "Container Ship",
  "photo_link": "https://static.vesselfinder.net/ship-photo/9811000-353136000-47a37bcd0d022df56c45b94d8db6b20d/1?v1",
  "year_built": 2018,
  "speed_knots": 18.4,
  "flag_country": "Liberia",
  "width_meters": 58.8,
  "gross_tonnage": 219079,
  "length_meters": 399.94,
  "other_matches": [],
  "course_degrees": 209.5,
  "departure_time": "Sep 23, 19:02 UTC",
  "estimated_arrival": "Oct 23, 17:00",
  "navigation_status": "Under way",
  "position_received": "1 min ago",
  "vesselfinder_link": "https://www.vesselfinder.com/vessels/details/9811000",
  "reported_destination": "Singapore, Singapore"
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@vesselfinder",
  "visibility": "public",
  "operation": "get_vessel_location",
  "version": 1,
  "input": {
    "ship_name": "Ever Given"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@vesselfinder\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_vessel_location\",\n  \"version\": 1,\n  \"input\": {\n    \"ship_name\": \"Ever Given\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@vesselfinder",
  "visibility": "public",
  "operation": "get_vessel_location",
  "version": 1,
  "input": {
    "ship_name": "Ever Given"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@vesselfinder","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Track a ship's reported position and speed.
- Check a ship's reported destination and estimated arrival.
- Review a ship's type, flag, and dimensions.
- Identify alternative ships when names match.

## FAQ

### Is Fous affiliated with VesselFinder?

No. Fous is not affiliated with VesselFinder. This workflow reads the public vesselfinder.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a VesselFinder account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from vesselfinder.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 29, 2026.

### Where is a ship?

Get vessel location returns its public position, including latitude and longitude.

### What is a ship's destination or estimated arrival?

Get vessel location returns its reported destination and estimated arrival.

### What are a ship's type and dimensions?

Get vessel location returns its ship type, length, and width.

## Related

- [Maersk API](https://fous.com/workflows/maersk.md): Ocean shipping and logistics tracking.
- [Vivino API](https://fous.com/workflows/vivino.md): Vivino helps find wines, ratings, and prices, with up to 25 relevant matches and top-rated wine picks by type and budget from US offers.
- [Vinted API](https://fous.com/workflows/vinted.md): Search public second-hand listings on Vinted country sites.
- [Parcels API](https://fous.com/workflows/parcels.md): Worldwide package tracking with automatic carrier detection.
- [Freightos API](https://fous.com/workflows/freightos.md): Ocean container freight rates by global index and trade lane.
- [Finviz API](https://fous.com/workflows/finviz.md): Finviz provides delayed US stock snapshots, screening by company and trading criteria, and up to 200 recent public executive and director Form 4 trades.
- [Flightradar24 API](https://fous.com/workflows/flightradar24.md): Flightradar24 provides live flight tracking, recent history, flight status and times, plus upcoming airport departures and arrivals; history and schedules are limited to recent and upcoming flights.
- [FlightAware API](https://fous.com/workflows/flightaware.md): FlightAware provides public flight status and dated flight details, airport arrivals and departures limited to displayed history and 20 flights per direction, plus today’s delays and cancellations when shown.
- [All Logistics workflows](https://fous.com/workflows/category/logistics)