# Marinetraffic — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Track maritime vessels in real-time by searching for ships by name, MMSI, or IMO number, viewing their current positions and navigational status, and accessing detailed specifications and photos. Filter vessels by type to get the maritime intelligence you need for shipping, logistics, or maritime awareness.

**Category:** Maps & Geospatial | **Website:** [marinetraffic.com/](https://marinetraffic.com/) | **Docs:** [parse.bot/marketplace/dce3e9ae-92b7-4348-afbf-52e074d8092c/marinetraffic-com-api](https://parse.bot/marketplace/dce3e9ae-92b7-4348-afbf-52e074d8092c/marinetraffic-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/marinetraffic/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get sailboat underway data

Get current status and location for multiple vessels by ship ID, filtered to only those currently 'Underway by Sail'. Makes one lookup per ID and returns only vessels matching the sailing status. Vessels not found or not currently sailing are excluded from results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ship_ids` | string | Yes | Comma-separated MarineTraffic ship IDs (e.g. '282498,5147083') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/marinetraffic/get-sailboat-underway-data \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ship_ids":"<string>"}'
```

### Get vessel current position

Retrieve the current position and navigational status of a specific vessel. Returns a focused subset of vessel data: coordinates, speed, course, and last update timestamp. Requires a MarineTraffic ship ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ship_id` | string | Yes | MarineTraffic ship ID (numeric string, obtainable from search_vessels results[*].id) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/marinetraffic/get-vessel-current-position \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ship_id":"<string>"}'
```

### Get vessel details

Retrieve full vessel details including technical specs (IMO, MMSI, length, type), current position (lat, lon, speed, course), voyage information (destination, departure/arrival ports), and photo metadata. Requires a MarineTraffic ship ID obtainable from search_vessels.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ship_id` | string | Yes | MarineTraffic ship ID (numeric string, obtainable from search_vessels results[*].id) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/marinetraffic/get-vessel-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ship_id":"<string>"}'
```

### Get vessel photos

Retrieve photo metadata and URLs for a given vessel. Returns up to 20 photos ordered by upload date, including photographer credit, location, and date taken. Each photo URL points to the full-resolution image on MarineTraffic's CDN.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ship_id` | string | Yes | MarineTraffic ship ID (numeric string, obtainable from search_vessels results[*].id) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/marinetraffic/get-vessel-photos \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ship_id":"<string>"}'
```

### Get vessels by type

Search for vessels of a specific type by name. Uses the same search engine as search_vessels but with a vessel type name as the query term. Returns vessels whose type description matches the search term.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `vessel_type` | string | Yes | Vessel type name to search for (e.g. 'Container Ship', 'LNG Tanker', 'Sailing Vessel', 'Bulk Carrier', 'Passenger Ship') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/marinetraffic/get-vessels-by-type \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"vessel_type":"<string>"}'
```

### Search vessels

Search for vessels by name, MMSI, or IMO number. Returns up to 12 matching vessels with basic metadata including ship ID, name, type description, and flag. The search is global and matches partial names.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (vessel name, MMSI, or IMO number) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/marinetraffic/search-vessels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.