# VesselFinder Vessel Tracker Scraper (`automation-lab/vesselfinder-vessel-tracker-scraper`) Actor

Search VesselFinder by vessel name, IMO, MMSI, or detail URL and export public vessel identity, voyage, destination, status, position, course, speed, timestamp, and source URL.

- **URL**: https://apify.com/automation-lab/vesselfinder-vessel-tracker-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.24 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## VesselFinder Vessel Tracker Scraper

Search **VesselFinder** by vessel name, IMO number, MMSI number, or a public vessel detail URL.
Export one typed record per vessel with public identity, voyage, destination, AIS status, surfaced coordinates, course, speed, position timestamp, and canonical source URL.

The Actor turns repeat vessel lookups into a dataset that works with spreadsheets, databases, dashboards, webhooks, and scheduled Apify Tasks.
It does not require a VesselFinder account or a separate VesselFinder API subscription.

### What does this VesselFinder scraper do?

1. Accepts vessel names, IMO numbers, MMSI numbers, and canonical VesselFinder detail URLs.
2. Resolves each query against VesselFinder's public vessel search.
3. Fetches the matching public detail record.
4. Normalizes identity, dimensions, voyage, motion, and position fields.
5. Deduplicates matches by IMO or MMSI.
6. Saves valid vessels to the default Apify dataset.

A name can resolve more than one vessel.
Use `maxItems` to bound the total number of unique output records.

### Who is it for?

- Fleet teams enriching internal IMO or MMSI lists.
- Maritime analysts checking public voyage and AIS context.
- Port and logistics teams reviewing destinations and vessel movement.
- Risk and due-diligence teams collecting source-linked vessel snapshots.
- Travel and cruise researchers resolving passenger vessels.
- Developers who need structured VesselFinder output without maintaining a scraper.

### Why use this Actor?

- Search and exact-identifier inputs share one output contract.
- Canonical source URLs make every row auditable.
- Position timestamps distinguish fresh and older AIS reports.
- Missing upstream fields remain `null` instead of becoming guessed values.
- Duplicate inputs do not create duplicate dataset rows.
- Empty searches finish normally, while blocked detail extraction fails visibly.
- A lightweight HTTP implementation avoids unnecessary browser runtime.

### What VesselFinder data can I extract?

| Group | Fields |
| --- | --- |
| Identity | `name`, `imo`, `mmsi`, `callsign`, `vesselType`, `aisType` |
| Registration | `flag`, `flagCode`, `builtYear` |
| Dimensions | `lengthMeters`, `beamMeters`, `grossTonnage`, `deadweightTons`, `draughtMeters` |
| Voyage | `destination`, `eta`, `lastPort`, `navigationStatus` |
| Position | `latitude`, `longitude`, `courseDegrees`, `speedKnots` |
| Freshness | `positionReceivedAt`, `positionAge`, `positionRegion` |
| Provenance | `sourceUrl`, `query`, `scrapedAt` |

VesselFinder may round coordinates on the public detail page.
The Actor exports the coordinates the source actually surfaces and does not imply precision that is not available.
AIS values can be delayed, incomplete, or entered manually by a vessel operator.

### How to search for a vessel

#### By name

```json
{
  "queries": ["EVER GIVEN"],
  "maxItems": 5
}
```

#### By IMO

```json
{
  "queries": ["9811000"],
  "maxItems": 1
}
```

#### By MMSI

```json
{
  "queries": ["353136000"],
  "maxItems": 1
}
```

#### By VesselFinder URL

```json
{
  "startUrls": [
    { "url": "https://www.vesselfinder.com/vessels/details/9241061" }
  ],
  "maxItems": 1
}
```

### Input parameters

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `queries` | string array | Conditional | none | Vessel names, 7-digit IMO numbers, or 9-digit MMSI numbers. |
| `startUrls` | request-list array | Conditional | none | Public `vesselfinder.com/vessels/details/<id>` URLs. |
| `maxItems` | integer | No | `25` | Maximum unique vessel records, from 1 to 500. |

Provide at least one value in `queries` or `startUrls`.
Only VesselFinder detail URLs are accepted in `startUrls`.

### Output example

The exact values change as public AIS data changes.
This abbreviated record shows the current output shape:

```json
{
  "name": "EVER GIVEN",
  "imo": 9811000,
  "mmsi": 353136000,
  "callsign": "H3RC",
  "vesselType": "Container Ship",
  "aisType": "Cargo ship (HAZ-A)",
  "flag": "Panama",
  "builtYear": 2018,
  "lengthMeters": 400,
  "beamMeters": 59,
  "destination": "GB FLX",
  "navigationStatus": null,
  "latitude": -31,
  "longitude": 35,
  "courseDegrees": 241.9,
  "speedKnots": 18.4,
  "draughtMeters": 15.4,
  "positionReceivedAt": "2026-08-22T14:31:27.000Z",
  "positionAge": "21 hours ago",
  "positionRegion": "South Africa",
  "sourceUrl": "https://www.vesselfinder.com/vessels/details/9811000",
  "query": "EVER GIVEN",
  "scrapedAt": "2026-08-23T11:39:03.159Z"
}
```

### Understanding null values and timestamps

A `null` value means VesselFinder did not expose that field for that vessel at collection time.
It does not mean zero, unknown forever, or extraction success from another source.

`positionReceivedAt` is the source position timestamp when available.
`scrapedAt` is when this Actor collected the record.
Compare them before treating a position as current.
`positionAge` preserves VesselFinder's human-readable freshness text.

### How much does it cost to track VesselFinder vessels?

The Actor uses pay-per-event pricing:

- `start`: **$0.005** once per run.
- `item`: one event for each valid vessel saved to the dataset.
- No item event is charged for duplicates, no-result queries, or failed records.

Current item tiers are:

| Plan tier | Price per vessel |
| --- | ---: |
| FREE | $0.015792 |
| BRONZE | $0.013732 |
| SILVER | $0.010711 |
| GOLD | $0.0082392 |
| PLATINUM | $0.0054928 |
| DIAMOND | $0.003845 |

At the FREE item tier, a run returning 1 vessel costs about **$0.0208**, 10 vessels about **$0.1629**, and 100 vessels about **$1.5842**.
The calculation is the $0.005 run event plus the number of saved vessels multiplied by $0.015792.
Your active Apify tier determines the item rate shown before a run.

### Getting started

1. Open the Actor in Apify Console.
2. Add one or more names, IMO numbers, or MMSI numbers.
3. Optionally add exact VesselFinder detail URLs.
4. Set `maxItems` to a sensible upper bound.
5. Click **Start**.
6. Open the **Dataset** tab to inspect vessel rows.
7. Export JSON, CSV, Excel, XML, or RSS from the dataset controls.

Start with one known identifier when validating a workflow.
Then expand to a fleet list after checking the returned fields and timestamp freshness.

### Fleet enrichment workflow

Use stable IMO numbers when possible:

```json
{
  "queries": ["9811000", "9241061", "9776171"],
  "maxItems": 3
}
```

Schedule the Task and send results to your own database.
Join rows on `imo`, fall back to `mmsi`, and preserve `sourceUrl` for auditability.
Compare new rows with the previous dataset in your downstream system to detect changed destinations, speed, or position timestamps.
The Actor returns snapshots; it does not itself store history or send alerts.

### Scheduling and monitoring

Apify Tasks can run this Actor hourly, daily, or on a custom cron schedule.
For responsible monitoring:

- Keep query lists bounded.
- Prefer IMO or MMSI over ambiguous names.
- Compare `positionReceivedAt`, not only `scrapedAt`.
- Treat a changed vessel name or MMSI as source data that needs review.
- Configure webhooks for succeeded and failed runs.
- Store historical comparisons in your own dataset or database.

### API access with cURL

Start a run and wait for results:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~vesselfinder-vessel-tracker-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["9811000"],"maxItems":1}'
```

Do not commit an Apify token to source control.
Use environment variables or a secret manager.

### JavaScript API example

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/vesselfinder-vessel-tracker-scraper').call({
  queries: ['9811000', '9241061'],
  maxItems: 2,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

Install the client with `npm install apify-client`.

### Python API example

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/vesselfinder-vessel-tracker-scraper').call(
    run_input={'queries': ['353136000'], 'maxItems': 1}
)
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

Install it with `pip install apify-client`.

### Use with MCP and AI assistants

Add the Apify MCP server to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/vesselfinder-vessel-tracker-scraper"
```

Use this same configuration in **Claude Desktop**, **Cursor**, or **VS Code**:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/vesselfinder-vessel-tracker-scraper"
    }
  }
}
```

- **Claude Desktop:** add the `apify` entry to the desktop MCP configuration and restart Claude Desktop.
- **Cursor:** add the server URL in Cursor's MCP settings.
- **VS Code:** add the HTTP MCP server through the MCP extension or workspace MCP settings.

Example prompts:

- "Resolve IMO 9811000 and summarize its public VesselFinder voyage record."
- "Enrich these three IMO numbers and return name, flag, destination, speed, and position timestamp."
- "Extract the Queen Mary 2 VesselFinder record from its detail URL."

Always review source timestamps before using AI-generated conclusions.

### Integrations

Typical destinations include:

- Google Sheets for a shared fleet snapshot.
- Airtable for maritime research lists.
- PostgreSQL or BigQuery for historical comparisons.
- Zapier or Make for routing completed datasets.
- Webhooks for downstream processing.
- Python, JavaScript, or BI notebooks for analysis.

Use `imo` as the preferred stable join key.
Keep both `query` and `sourceUrl` when investigating mismatches.

### Legality and responsible use

This Actor extracts public VesselFinder pages and endpoints.
It does not provide satellite AIS, historical tracks, paid VesselFinder features, guaranteed real-time positions, collision risk, sanctions conclusions, ownership verification, or navigation advice.

Source fields can be stale or incomplete.
Coordinates may be rounded.
Destinations and navigation status can be manually entered AIS values.
Do not use this output for navigation, safety-of-life decisions, surveillance, or unlawful tracking.
Review VesselFinder's terms and the laws that apply to your use case.

### Troubleshooting

#### Why did my name search return no rows?

Check spelling and try an IMO or MMSI number.
A name may be too broad, changed, or absent from the current public index.
A genuine no-result search completes with an empty dataset.

#### Why is the position old?

The vessel may be outside terrestrial AIS coverage, switched off, delayed, or available only through a paid satellite service.
Inspect `positionReceivedAt` and `positionAge`.
The Actor does not fabricate a newer position.

#### Why are latitude and longitude rounded?

The public VesselFinder detail page may expose rounded coordinates.
The Actor preserves that public precision instead of claiming exact coordinates.

#### Why did the run fail after resolving vessels?

VesselFinder may have challenged or changed its public detail response.
The Actor fails visibly when every resolved detail record fails, so automation does not mistake an upstream block for an empty result.
Retry later and inspect the run log.

### FAQ

#### Can I search by vessel name, IMO, and MMSI in one run?

Yes.
Put all values in `queries`; duplicates are removed from the output.

#### Can I pass VesselFinder URLs?

Yes, for canonical `/vessels/details/<IMO-or-MMSI>` URLs on `vesselfinder.com`.
Other domains and unrelated VesselFinder pages are rejected.

#### Does it include historical tracks?

No.
Each row is a snapshot of currently public detail data.
Schedule runs and retain prior datasets if your workflow needs comparisons.

#### Does it require a proxy or login?

No login or user-supplied proxy setting is required by the current implementation.
The Actor uses a bounded public HTTP session and conservative request volume.

#### Is every input charged?

No.
The item event is emitted only after a valid, unique vessel record is saved.
The one-time start event applies once per run.

### Related automation-lab Actors

This Actor is intentionally focused on VesselFinder vessel identity, voyage, and latest public position snapshots.
Browse the [automation-lab Apify profile](https://apify.com/automation-lab) for other source-specific travel, transport, and structured-data Actors that can complement a broader workflow.

### Support

For reproducible problems, include:

- The input with any private business data removed.
- The Actor run URL.
- The expected vessel or field.
- Whether the issue affects a name, IMO, MMSI, or detail URL.
- The approximate time of the run.

Do not include Apify tokens, private credentials, or sensitive fleet notes.

# Actor input Schema

## `queries` (type: `array`):

Enter one or more vessel names, 7-digit IMO numbers, or 9-digit MMSI numbers. Each query may resolve one or more public VesselFinder matches.

## `startUrls` (type: `array`):

Optional public VesselFinder URLs in the form https://www.vesselfinder.com/vessels/details/9811000.

## `maxItems` (type: `integer`):

Stop after saving this many unique vessels across all queries and URLs.

## Actor input object example

```json
{
  "queries": [
    "EVER GIVEN",
    "9811000",
    "353136000"
  ],
  "startUrls": [
    {
      "url": "https://www.vesselfinder.com/vessels/details/9811000"
    }
  ],
  "maxItems": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset containing all unique vessels extracted during this run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "EVER GIVEN",
        "9811000",
        "353136000"
    ],
    "startUrls": [
        {
            "url": "https://www.vesselfinder.com/vessels/details/9811000"
        }
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/vesselfinder-vessel-tracker-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "queries": [
        "EVER GIVEN",
        "9811000",
        "353136000",
    ],
    "startUrls": [{ "url": "https://www.vesselfinder.com/vessels/details/9811000" }],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/vesselfinder-vessel-tracker-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "EVER GIVEN",
    "9811000",
    "353136000"
  ],
  "startUrls": [
    {
      "url": "https://www.vesselfinder.com/vessels/details/9811000"
    }
  ],
  "maxItems": 10
}' |
apify call automation-lab/vesselfinder-vessel-tracker-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/vesselfinder-vessel-tracker-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Q8VnqGAyzJoG9RkXb/builds/SSE0f1ZnSVwsNb57M/openapi.json