# Oil Tanker Tracking API - Cargo Flows, LNG, LPG, Fixtures (`nabeelbaghoor/oil-tanker-cargo-flows-api`) Actor

Oil tanker cargo tracking from the Vortexa API: crude oil, refined products, LNG and LPG cargo movements, export and import flow time series, top origin and destination breakdowns, tanker fixtures, plus port, product, vessel and charterer lookups. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/oil-tanker-cargo-flows-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $15.00 / 1,000 cargo movement returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Oil Tanker Tracking API - Cargo Flows, LNG, LPG, Fixtures

Pull crude oil, refined products, LNG and LPG tanker cargo movements, export and import flow time series, top origin and destination rankings, tanker fixtures and port, product, vessel and charterer reference data from the Vortexa REST API with your own API key, as one clean dataset row per record.

Vortexa tracks seaborne energy cargoes worldwide: which tanker loaded which crude grade or product where, where it is going, how much it carries, who chartered it, and whether it is sitting in floating storage. This actor wraps its read only search endpoints on api.vortexa.com, the same ones Vortexa's own Python SDK calls. Give a date range and filters such as origin, destination, product, vessel class or charterer and get deduplicated rows you can download as JSON, CSV or Excel, schedule, or feed into commodity trading models, freight desks, refinery and supply analytics, Google Sheets, BI dashboards and AI agents. Bring your own API key.

BYOK, not live-tested: every path, body field and enum comes from Vortexa's open source Python SDK (github.com/V0RT3X4/python-sdk, version 1.0.32), because the REST reference on docs.vortexa.com sits behind a login. The gateway was probed with an invalid key and answers 401 to every path before routing, so the probe could not confirm the routes themselves. The actor has not been run against a live Vortexa key.

### What it does

- **Cargo movements**: every tanker cargo matching the filters, with cargo ID, status, quantity in barrels, tonnes and cubic metres, product group, category and grade, origin and destination country, port and terminal, loading and unloading times, ship to ship transfer and floating storage flags, vessel name, IMO, MMSI, class and deadweight, and charterer.
- **Cargo movement by ID**: single cargoes by long or short ID, in barrels, tonnes or cubic metres.
- **Cargo flow time series**: daily, weekly, DOE weekly, monthly, quarterly or yearly totals of barrels, barrels per day, tonnes, tonnes per day or cargo counts, optionally split by origin, destination, product, vessel class, flag, storage location, shipper or consignee.
- **Origin and destination breakdowns**: the top exporting or importing countries, ports, terminals or shipping regions for the filters, ranked by volume or flow rate.
- **Tanker fixtures**: reported charter fixtures with vessel, fixing date, laycan, tonnes, route, product and charterer.
- **Reference search**: geographies (terminals, ports, countries, regions, waypoints, storage), products (crude, condensate, diesel, gasoline, naphtha, jet, fuel oil, LNG, LPG grades), vessels (IMO, MMSI, class, deadweight, capacity, flag, build year) and charterers, so you can find the IDs the flow modes filter on.
- **Real filters**: activity (loading, unloading, floating storage, in transit, oil on water, waypoints), 41 documented vessel classes from coastal tankers to VLCCs, VLGCs and Q-Max LNG carriers, waypoints such as canals, scrubber fitment and intra movement rules.
- **Pay only for results**: refused and empty lookups are recorded as a free row that says why, never charged.

Nothing is written to your Vortexa account.

### How to get an API key

Vortexa issues API keys to its subscribers; there is no self serve sign up. The key is a UUID of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, and the authentication page on docs.vortexa.com explains where to find it once you have access. Paste it into the API key field, or set the DATA_API_KEY secret. The key is sent only to api.vortexa.com, in the apikey parameter exactly as the official SDK sends it, and is removed from everything the actor logs. A key that is not a UUID ends the run before any request, as the SDK does.

### Input

| Field | Modes | Description |
| --- | --- | --- |
| `mode` | all | `cargoMovements` (default), `cargoMovementById`, `timeSeries`, `originBreakdown`, `destinationBreakdown`, `fixtures`, `geographies`, `products`, `vessels` or `charterers` |
| `dateFrom`, `dateTo` | flow modes | UTC dates or date-times; empty means the last 7 days |
| `activity` | cargo movements, time series, breakdowns | `loading_state` (default), `unloading_state`, `storing_state`, `transiting_state`, `oil_on_water_state`, `waypoint_start` and more |
| `originIds`, `destinationIds` | flow modes | Vortexa geography IDs |
| `productIds`, `vesselIds`, `chartererIds` | flow modes | Vortexa product, vessel and charterer IDs |
| `vesselClasses` | flow modes, vessels | Documented classes such as `oil_vlcc`, `oil_aframax_lr2`, `lpg_vlgc_vlec`, `lng` |
| `storageLocationIds`, `waypointIds`, `intraMovements` | cargo movements, time series, breakdowns | Floating storage, waypoint and intra movement filters |
| `vesselScrubbers` | cargo movements, breakdowns, fixtures, vessels | `disabled`, `inc` or `exc` |
| `quantityUnit` | cargo movements, by ID | `b`, `t`, or `cbm` for by ID |
| `cargoMovementIds` | cargo movement by ID | Up to 200 IDs |
| `timeseriesFrequency`, `timeseriesUnit`, `timeseriesSplit` | time series | Bucket size, metric and split |
| `breakdownGeography`, `breakdownUnit`, `breakdownSize` | breakdowns | Grouping level, metric and top N |
| `searchTerms` | reference modes | Names or parts of names |
| `referenceIds`, `productParentIds`, `geographyLayer`, `productLayer` | reference modes | Exact IDs, children of a product, layer filters |
| `maxResults` | all | Row ceiling for the run (default 100) |
| `requestsPerMinute` | all | Pacing, default 30 |
| `apiKey` | all | Your Vortexa API key (or the DATA_API_KEY secret) |

Example: find the geography ID of Rotterdam.

```json
{
    "mode": "geographies",
    "searchTerms": ["Rotterdam"],
    "geographyLayer": "port"
}
```

Example: monthly crude exports in barrels per day from one origin, split by destination country.

```json
{
    "mode": "timeSeries",
    "dateFrom": "2026-01-01",
    "dateTo": "2026-09-30",
    "activity": "loading_state",
    "originIds": ["<geography ID from the Geographies mode>"],
    "productIds": ["<crude product ID from the Products mode>"],
    "timeseriesFrequency": "month",
    "timeseriesUnit": "bpd",
    "timeseriesSplit": "destination_country"
}
```

### Example output

An illustrative cargo movement row, shaped like the SDK's documented record (values are an example, not real data). The full Vortexa record is kept under `record`.

```json
{
    "mode": "cargoMovements",
    "modeLabel": "Cargo movements",
    "recordType": "cargoMovement",
    "query": "2026-10-01 to 2026-10-07",
    "id": "a1b2c3d4e5f60718",
    "name": "ULSD (Ultra Low Sulphur Diesel)",
    "status": "unloaded_state",
    "quantity": 310000,
    "quantityUnit": "b",
    "productGroup": "Clean products",
    "productCategory": "Diesel/Gasoil",
    "productGrade": "ULSD (Ultra Low Sulphur Diesel)",
    "originCountry": "Example Country A",
    "originPort": "Example Port A",
    "loadingStart": "2026-10-01T04:00:00.000Z",
    "loadingEnd": "2026-10-02T11:00:00.000Z",
    "destinationCountry": "Example Country B",
    "destinationPort": "Example Port B",
    "unloadingStart": "2026-10-14T08:00:00.000Z",
    "shipToShip": false,
    "floatingStorage": false,
    "vesselName": "EXAMPLE SPIRIT",
    "vesselImo": 9000000,
    "vesselClass": "oil_handymax_mr2",
    "vesselCount": 1,
    "charterer": "Example Trading",
    "found": true,
    "retrievedAt": "2026-10-22T12:00:00.000Z",
    "note": null,
    "record": { "cargo_movement_id": "a1b2c3d4e5f60718", "events": ["..."], "vessels": ["..."] }
}
```

A time series row carries `period`, `value`, `count`, `unit`, `frequency` and an optional `breakdown` list. A breakdown row carries `name` (the geography), `layer`, `value`, `count` and `rank`. A fixture row carries `vesselName`, `fixingTimestamp`, `laycanFrom`, `laycanTo`, `tonnes`, `originName`, `destinationName`, `productName` and `charterer`. Reference rows carry `id`, `name` and `layer`, plus IMO, MMSI, class, deadweight, capacity, flag and build year for vessels.

### FAQ

#### What is the Vortexa API?

It is the REST API behind Vortexa's energy and freight analytics platform, which tracks crude oil, refined products, LNG, LPG and chemicals cargoes on tankers and gas carriers worldwide. It serves cargo movements, flow time series, breakdowns, fixtures, vessel availability, freight and reference data on api.vortexa.com, and Vortexa publishes an open source Python SDK for it.

#### Do I need my own Vortexa API key?

Yes. This is a bring-your-own-key actor: it calls Vortexa with your key, under your subscription and its terms. A missing, malformed or rejected key ends the run cleanly with a status message that explains what to change, and nothing is charged.

#### How do I track crude oil exports from a country?

Run Geographies with the country name to get its geography ID and Products with "Crude" to get the crude product ID. Then run Cargo flow time series with those IDs as origin and product, activity loading, and the frequency and unit you need, such as monthly barrels per day. Add a destination country split to see where the barrels went.

#### Can I see oil in floating storage?

Yes. Set the activity to floating storage in Cargo movements or Cargo flow time series to get cargoes stored on water during the date range, and use floating storage location IDs to focus on an area.

#### Does it cover LNG and LPG carriers?

Yes. Filter by LNG or LPG products, or by the LNG and LPG vessel classes such as Q-Max, Q-Flex, conventional LNG, VLGC and VLEC, in any flow mode.

#### How do I find the top importers of a product?

Run Destination breakdown with the product ID, the date range and activity unloading, choose country, port or terminal as the geography level, and set the top N.

#### How many API requests does a run use?

One per page of up to 500 records for searches, one per cargo movement ID, and one for each time series or breakdown. Max results stops paging early, and the run log reports the exact request count.

#### What do I pay?

Pay per result: 0.015 USD per cargo movement, 0.01 USD per fixture, time series bucket or breakdown row, and 0.005 USD per geography, product, vessel or charterer record. Refused and empty lookups are never charged. Your Vortexa subscription is billed separately by Vortexa.

### Pricing

| Event | Price | Charged for |
| --- | --- | --- |
| `cargo-movement` | 0.015 USD | Each cargo movement from a search or an ID lookup |
| `fixture-record` | 0.01 USD | Each tanker fixture |
| `aggregate-row` | 0.01 USD | Each time series bucket or origin or destination breakdown entry |
| `reference-record` | 0.005 USD | Each geography, product, vessel or charterer |

### Keyword map

Oil tanker tracking API, crude oil flows API, oil cargo tracking, tanker tracking data, LNG shipping data API, LPG flows, refined products flows, oil exports and imports data, floating storage data, seaborne crude data, commodity flows API, tanker fixtures API, freight market data, vessel class data, Vortexa API, Vortexa cargo movements, Vortexa SDK alternative, energy data API.

### Terms and data use

Vortexa's only public legal document for the platform is its Fair Use Policy, which asks users not to overload the service, probe its security or get around its access and storage restrictions; it does not forbid storing results or using them in another platform. Your subscription contract with Vortexa is private and governs how you may use, share and redistribute the data, and Vortexa content is typically licensed for internal use. Run this actor with your own key, keep the results for the uses your agreement allows, keep the request rate modest, and do not publish or resell the data without Vortexa's written permission. This actor is not affiliated with or endorsed by Vortexa.

# Actor input Schema

## `apiKey` (type: `string`):

Your own Vortexa API key, a UUID of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Vortexa issues API keys to its subscribers; the authentication page on docs.vortexa.com says where to find yours. Optional only when the DATA_API_KEY secret is set on the actor; otherwise the run ends with an explanation and nothing is charged.

## `mode` (type: `string`):

Cargo movements lists every tanker cargo matching the filters. Cargo flow time series sums volumes or counts per day, week, month, quarter or year. Origin and destination breakdowns rank the top loading or discharge geographies. Tanker fixtures lists reported charter fixtures. Geographies, products, vessels and charterers give the IDs the other modes filter on.

## `dateFrom` (type: `string`):

Cargo movements, time series, breakdowns and fixtures. First UTC date or date and time, such as 2026-10-01 or 2026-10-01 06:00. Leave both dates empty for the last 7 days.

## `dateTo` (type: `string`):

Last UTC date or date and time, such as 2026-10-31; a bare date includes the whole day. Empty means now.

## `activity` (type: `string`):

Cargo movements, time series and breakdowns. Which part of a voyage the date range applies to: loading, unloading, floating storage, transit and more. Unloaded and oil on water apply to cargo movements and time series only; any activity to cargo movements and breakdowns.

## `originIds` (type: `array`):

Cargo movements, time series, breakdowns and fixtures. Vortexa geography IDs of load countries, ports, terminals or regions, one per line, from the Geographies mode.

## `destinationIds` (type: `array`):

Vortexa geography IDs of discharge countries, ports, terminals or regions, from the Geographies mode.

## `productIds` (type: `array`):

Vortexa product IDs such as crude, diesel, gasoline, naphtha, fuel oil, LNG or LPG, from the Products mode. A parent product includes its grades.

## `vesselIds` (type: `array`):

Vortexa vessel IDs from the Vessels mode.

## `chartererIds` (type: `array`):

Vortexa charterer (corporation) IDs from the Charterers mode.

## `vesselClasses` (type: `array`):

Flow modes and Vessels. Tanker and gas carrier size classes, such as VLCC, Suezmax, Aframax, MR, VLGC or Q-Max.

## `storageLocationIds` (type: `array`):

Cargo movements, time series and breakdowns. Geography IDs of floating storage areas.

## `waypointIds` (type: `array`):

Cargo movements, time series and breakdowns. Geography IDs of waypoints such as the Suez Canal, Panama Canal or a strait the cargo passed.

## `intraMovements` (type: `string`):

Cargo movements, time series and breakdowns. Whether cargoes that leave and re-enter the same country or geography are counted.

## `vesselScrubbers` (type: `string`):

Cargo movements, breakdowns, fixtures and Vessels. Only vessels with scrubbers fitted, only vessels without, or no filter.

## `quantityUnit` (type: `string`):

Cargo movements (barrels or tonnes) and Cargo movement by ID (also cubic metres).

## `cargoMovementIds` (type: `array`):

Cargo movement by ID only. Long or short cargo movement IDs from the Cargo movements mode, one per line, up to 200.

## `timeseriesFrequency` (type: `string`):

Time series only. The size of each time bucket; DOE week follows the US EIA reporting week.

## `timeseriesUnit` (type: `string`):

Time series only. The metric summed in each bucket.

## `timeseriesSplit` (type: `string`):

Time series only. Splits each bucket by origin, destination, product, vessel class, flag, storage location, shipper or consignee; the split comes back in the breakdown column.

## `breakdownGeography` (type: `string`):

Breakdowns only. The geography level the ranking groups by, such as country, port, terminal or shipping region.

## `breakdownUnit` (type: `string`):

Breakdowns only. The metric each geography is ranked by.

## `breakdownSize` (type: `integer`):

Breakdowns only. How many top geographies to return.

## `searchTerms` (type: `array`):

Geographies, products, vessels and charterers. Names or parts of names, one per line, such as Rotterdam, China, Diesel, Crude or a tanker name. Matches similar names too.

## `referenceIds` (type: `array`):

Products and Vessels only. Look up these exact Vortexa IDs.

## `geographyLayer` (type: `string`):

Geographies only. Only geographies of this kind.

## `productLayer` (type: `string`):

Products only. Group (such as crude or clean products), group product, category or grade.

## `productParentIds` (type: `array`):

Products only. Returns the direct children of these product IDs.

## `maxResults` (type: `integer`):

The most rows this run returns across all lookups. Each row with data is charged once.

## `requestsPerMinute` (type: `integer`):

Pacing ceiling for calls to the Vortexa API. Lower it if your subscription has a tighter rate limit.

## Actor input object example

```json
{
  "mode": "cargoMovements",
  "activity": "loading_state",
  "intraMovements": "any",
  "vesselScrubbers": "disabled",
  "quantityUnit": "b",
  "timeseriesFrequency": "day",
  "timeseriesUnit": "b",
  "timeseriesSplit": "none",
  "breakdownGeography": "country",
  "breakdownUnit": "b",
  "breakdownSize": 20,
  "searchTerms": [
    "Rotterdam"
  ],
  "geographyLayer": "any",
  "productLayer": "any",
  "maxResults": 100,
  "requestsPerMinute": 30
}
```

# Actor output Schema

## `records` (type: `string`):

One row per record returned for the chosen mode.

# 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 = {
    "searchTerms": [
        "Rotterdam"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/oil-tanker-cargo-flows-api").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 = { "searchTerms": ["Rotterdam"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/oil-tanker-cargo-flows-api").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 '{
  "searchTerms": [
    "Rotterdam"
  ]
}' |
apify call nabeelbaghoor/oil-tanker-cargo-flows-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/oil-tanker-cargo-flows-api"
        }
    }
}
```

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/T4W3XAT0sBAvExo0d/builds/WGv2UaVgNqr4q93fz/openapi.json