# 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/tools/vesselfinder
- Handle: `@vesselfinder`
- Category: [Logistics](https://fous.com/tools/category/logistics)
- Source website: https://vesselfinder.com
- Last verified: Sep 29, 2026

## Methods

### Get vessel location

Operation `get_vessel_location`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

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

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_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.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

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=180) 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.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_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);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/vesselfinder`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_vessel_location`: Get vessel location. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-vesselfinder https://api.fous.com/mcp/tools/vesselfinder --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

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

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this VesselFinder tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. 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. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified 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/tools/maersk.md): Ocean shipping and logistics tracking.
- [Vivino API](https://fous.com/tools/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/tools/vinted.md): Search public second-hand listings on Vinted country sites.
- [Parcels API](https://fous.com/tools/parcels.md): Worldwide package tracking with automatic carrier detection.
- [Freightos API](https://fous.com/tools/freightos.md): Ocean container freight rates by global index and trade lane.
- [Finviz API](https://fous.com/tools/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/tools/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/tools/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 tools](https://fous.com/tools/category/logistics)