vortexa-claude-skills 1.0.0

package/context/cargo-movements.md

@@ -0,0 +1,738 @@
+# Cargo Movements & CargoTimeSeries
+
+> Endpoint documentation for querying cargo flows, timeseries, and individual movements.
+> For date/unit rules, see `date-units.md` (pre-loaded). For common error patterns, see `guardrails.md` (pre-loaded).
+
+---
+
+## When to Use This Endpoint
+
+**NEVER** use CargoMovements search to answer volume/flow questions -- it returns individual records that must be summed manually. CargoTimeSeries pre-aggregates and handles splits/double-counting correctly.
+
+**ALWAYS** use CargoTimeSeries for aggregate volume questions and CargoMovements search for individual cargo details.
+
+| User Wants | Endpoint | Signal Words |
+|---|---|---|
+| Aggregate volumes, flows, trends | CargoTimeSeries | "how much", "total", "trend", "monthly", "weekly", "barrels per day", "chart" |
+| Breakdown by dimension | CargoTimeSeries + `timeseries_property` | "by origin", "by product", "by vessel class", "breakdown" |
+| Individual cargo records | CargoMovements search | "list cargoes", "which shipments", "specific vessel", "cargo details", "show me the movements" |
+| Single cargo lookup | CargoMovements record | "cargo ID", "look up this movement" |
+
+---
+
+## CRITICAL: Activity Filter Rules
+
+**NEVER** use `loading_state` when the user says "exports" -- this is the #1 most common mistake.
+**NEVER** use `unloading_state` when the user says "imports".
+**NEVER** use `oil_on_water_state` -- it is DEPRECATED. Always use `cargo_on_water_state`.
+**ALWAYS** set `intra_movements="exclude_intra_country"` for exports/imports queries.
+**ALWAYS** set `filter_activity` explicitly -- never rely on the default (`any_activity`).
+
+### Activity Selection Table
+
+| User Says | CORRECT filter_activity | WRONG Choice | Why Wrong |
+|---|---|---|---|
+| "exports", "shipped out", "departures" | `loading_end` | `loading_state` | `loading_state` = currently loading at berth, not departed. Volumes will be far too low. |
+| "imports", "arrivals", "received" | `unloading_start` | `unloading_state` | `unloading_state` = currently discharging, not arrived. Misses completed discharges. |
+| "loadings", "loading at port" | `loading_state` | `loading_end` | `loading_end` = already departed, not actively loading. |
+| "discharged" | `unloading_state` | `unloading_start` | `unloading_start` = arrived, not yet discharged. |
+| "on the water", "afloat", "in transit" | `cargo_on_water_state` | `oil_on_water_state` | `oil_on_water_state` is DEPRECATED. |
+| "floating storage", "stored at sea" | `storing_state` | `cargo_on_water_state` | `cargo_on_water_state` includes all transit, not just storage. |
+| "everything", "all activity" | `any_activity` | omitting the parameter | Omitting defaults to `any_activity` but should always be explicit. |
+
+### Activity + Geography Logic
+
+**CRITICAL:** "exports" vs "imports" determines both the activity filter AND which geography filter to use.
+
+| Query Pattern | filter_activity | Geography Filter | intra_movements |
+|---|---|---|---|
+| "Saudi exports" | `loading_end` | `filter_origins=[saudi_id]` | `exclude_intra_country` |
+| "China imports" | `unloading_start` | `filter_destinations=[china_id]` | `exclude_intra_country` |
+| "Saudi exports to China" | `loading_end` | `filter_origins=[saudi_id]` + `filter_destinations=[china_id]` | `exclude_intra_country` |
+| "crude on the water" | `cargo_on_water_state` | (none or `filter_storage_locations`) | `all` |
+| "floating storage in MEG" | `storing_state` | `filter_storage_locations=[meg_id]` | `all` |
+
+### timeseries_activity vs filter_activity
+
+These are two distinct parameters that serve different purposes:
+
+| Parameter | Purpose | Default |
+|---|---|---|
+| `filter_activity` | **WHICH** cargoes to include -- filters the dataset to only cargoes in this state during the time window | Required (defaults to `any_activity`) |
+| `timeseries_activity` | **WHEN** to count each cargo -- determines which timestamp to aggregate on | Same as `filter_activity` |
+
+**When they match (99% of cases):** Filter on loadings, count at loading time. Filter on exports, count at export time.
+
+**When they differ (advanced):** Filter cargoes that *loaded* in 2025, but aggregate by their *unloading* dates to see when those specific cargoes arrived:
+- `filter_activity="loading_end"` + `filter_time_min/max` = 2025
+- `timeseries_activity="unloading_start"` = plot arrival dates of those cargoes
+
+**ALWAYS** set both explicitly when they should differ. If only `filter_activity` is set, `timeseries_activity` defaults to match it.
+
+---
+
+## Natural Language to API Mapping
+
+### Vocabulary Reference: Activity / State
+
+See the Activity Selection Table above for the complete mapping.
+
+### Vocabulary Reference: Products
+
+| User Says | Product Level | Vortexa Label |
+|---|---|---|
+| "crude", "crude oil" | group | Crude & Condensates |
+| "condensate" | group_product | Condensate |
+| "clean products", "CPP" | group | Clean Petroleum Products |
+| "dirty products", "DPP" | group | Dirty Petroleum Products |
+| "fuel oil", "HSFO", "VLSFO", "bunkers" | group_product | Fuel Oil |
+| "naphtha" | group_product | Naphtha |
+| "gasoline", "mogas", "motor gasoline" | group_product | Gasoline / Mogas |
+| "jet fuel", "jet", "kerosene" | group_product | Jet/Kero |
+| "gasoil", "diesel", "AGO" | group_product | Gasoil/Diesel |
+| "LPG" | group | LPG |
+| "LNG", "natural gas" (shipping context) | group | LNG |
+| "VGO" | group_product | VGO |
+
+### Vocabulary Reference: Geography
+
+| User Says | Vortexa Geography | Layer |
+|---|---|---|
+| "Middle East", "MEG", "AG", "Arabian Gulf", "Persian Gulf" | Middle East/North Africa or Arabian/Persian Gulf | region or shipping_region_v2 |
+| "USG", "US Gulf", "Gulf Coast" | US Gulf Coast | shipping_region_v2 |
+| "PADD I", "East Coast" (US) | US Atlantic Coast | shipping_region_v2 |
+| "ARA", "Amsterdam-Rotterdam-Antwerp" | Specific ports (Amsterdam, Rotterdam, Antwerp) | port |
+| "WAF", "West Africa" | West Africa | shipping_region_v2 |
+| "Med", "Mediterranean" | Mediterranean | shipping_region_v2 |
+| "NEA", "Northeast Asia" | Northeast Asia | shipping_region_v2 |
+| "SEA", "Southeast Asia" | Southeast Asia | shipping_region_v2 |
+
+### Vocabulary Reference: Vessel Classes
+
+| User Says | API Value |
+|---|---|
+| "VLCC", "supertanker" | `oil_vlcc` |
+| "Suezmax" | `oil_suezmax` or `oil_suezmax_lr3` |
+| "Aframax", "LR2" (same vessel size) | `oil_aframax` or `oil_aframax_lr2` |
+| "Panamax", "LR1" | `oil_panamax` or `oil_panamax_lr1` |
+| "MR", "MR2", "medium range" | `oil_mr2` or `oil_handymax_mr2` |
+| "Handysize", "MR1" | `oil_handysize` or `oil_handysize_mr1` |
+| "all oil tankers" | `oil` |
+| "VLGC" | `lpg_vlgc` or `lpg_vlgc_vlec` |
+| "LGC" | `lpg_lgc` |
+| "MGC" | `lpg_mgc` |
+| "all LPG carriers" | `lpg` |
+| "Q-Max" | `lng_q_max` |
+| "Q-Flex" | `lng_q_flex` |
+| "Q-fleet" | `lng_q_fleet` |
+| "two-stroke LNG" | `lng_two_stroke` |
+| "TFDE", "DFDE" | `lng_tfde_dfde` |
+| "steam turbine LNG" | `lng_steam` |
+| "conventional LNG" | `lng_conventional_lng` |
+| "all LNG carriers" | `lng` |
+
+### Vocabulary Reference: Units and Frequency
+
+See `date-units.md` for the complete unit defaults, frequency selection, and date parsing reference.
+
+**Quick defaults when user does not specify:**
+- Oil questions: `bpd` (barrels per day)
+- LNG questions: `t` (tonnes)
+- LPG questions: `t` (tonnes)
+- Counting questions: `c` (count)
+
+### Vocabulary Reference: Time Ranges
+
+See `date-units.md` for the complete date parsing convention (calendar vs trailing periods).
+
+**CRITICAL:** Always specify `filter_time_max` with hour, minute, and second components (e.g., `datetime(2025, 12, 31, 23, 59, 59)`) to ensure the final day's data is included. Without the time component, `datetime(2025, 12, 31)` defaults to midnight (00:00:00) and excludes all data from that day.
+
+---
+
+## Entity ID Resolution
+
+**NEVER** use entity names directly in API calls -- all filters require 64-character hex Vortexa IDs.
+
+**ALWAYS** specify `filter_layer` when searching geographies. Without it, "China" returns ports, regions, and the country.
+
+**ALWAYS** handle multiple search matches with disambiguation -- present top matches to the user and confirm.
+
+```python
+from vortexasdk import Products, Geographies, Vessels, Corporations
+
+# Products: use filter_layer to get the right hierarchy level
+Products().search(term="crude", exact_term_match=False).to_df()
+# Pick the row where name == "Crude & Condensates" and layer == "group"
+
+# Geographies: use filter_layer to disambiguate
+Geographies().search(term="Rotterdam", filter_layer="port").to_df()
+
+# Vessels: search by name, IMO, or vessel class
+Vessels().search(term="Olympic Pride").to_df()
+Vessels().search(vessel_classes="oil_vlcc").to_df()
+
+# Corporations: search by name
+Corporations().search(term="Shell").to_df()
+```
+
+See `guardrails.md` for the full entity resolution rules and common mistakes.
+
+---
+
+## Parameter Reference: CargoTimeSeries
+
+**Endpoint:** `POST /v5/cargo/time-series`
+**SDK:** `CargoTimeSeries().search(...)`
+**Purpose:** Aggregate cargo flow volumes over time with optional breakdowns.
+
+### Required Parameters
+
+| Parameter | Type | Description | CRITICAL Notes |
+|---|---|---|---|
+| `filter_activity` | string | Which cargo state to filter on | See Activity Selection Table. NEVER rely on default. |
+| `filter_time_min` | datetime | Start of time range (UTC) | ALWAYS specify explicitly. |
+| `filter_time_max` | datetime | End of time range (UTC) | **MUST include time component** `datetime(Y, M, D, 23, 59, 59)` to capture final day. |
+
+### Key Optional Parameters
+
+| Parameter | Type | Default | Description | CRITICAL Notes |
+|---|---|---|---|---|
+| `timeseries_frequency` | enum | `day` | Time bucket: `day`, `week`, `doe_week`, `month`, `quarter`, `year` | See `date-units.md` for selection guidance. |
+| `timeseries_unit` | enum | `b` | Output unit: `b`, `bpd`, `t`, `tpd`, `cbm`, `c`, `cpd`, `mpd`, `bpa`, `tpa`, `mpa` | Match to commodity. See `date-units.md`. |
+| `timeseries_property` | enum | `quantity` | Split/breakdown dimension. `quantity` = no breakdown. | See Breakdown Properties below. |
+| `timeseries_activity` | enum | same as `filter_activity` | Which activity timestamp to aggregate on | Only set differently for advanced use. See timeseries_activity vs filter_activity. |
+| `filter_products` | string[] | none | Vortexa product IDs | Resolve via Products().search() first. |
+| `filter_origins` | string[] | none | Vortexa geography IDs for origin | Use with `loading_end` for exports. |
+| `filter_destinations` | string[] | none | Vortexa geography IDs for destination | Use with `unloading_start` for imports. |
+| `filter_vessel_classes` | enum[] | none | Vessel class codes | See Vessel Classes table. |
+| `filter_charterers` | string[] | none | Vortexa corporation IDs | |
+| `filter_effective_controllers` | string[] | none | Vortexa corporation IDs | |
+| `filter_vessel_owners` | string[] | none | Vortexa corporation IDs | |
+| `filter_time_charterers` | string[] | none | Vortexa corporation IDs | |
+| `filter_vessels` | string[] | none | Vortexa vessel IDs | |
+| `filter_waypoints` | string[] | none | Geography IDs for waypoint (e.g., Suez Canal) | |
+| `filter_storage_locations` | string[] | none | Geography IDs for floating storage location | Use with `storing_state`. |
+| `filter_ship_to_ship_locations` | string[] | none | Geography IDs for STS location | |
+| `filter_vessel_age_min` | number | none | Minimum vessel age in years | |
+| `filter_vessel_age_max` | number | none | Maximum vessel age in years | |
+| `filter_vessel_scrubbers` | enum | `disabled` | `disabled`, `inc` (with scrubbers), `exc` (without) | |
+| `filter_vessel_flags` | string[] | none | Geography IDs for vessel flag state | |
+| `filter_buyer` | string[] | none | Buyer corporation IDs | |
+| `filter_seller` | string[] | none | Seller corporation IDs | |
+| `filter_contract_type` | enum[] | none | `spot`, `term` | |
+| `filter_delivery_method` | enum[] | none | `FOB`, `DES`, `CFR`, `CIF` | |
+| `filter_shipper` | string[] | none | Shipper corporation IDs | |
+| `filter_consignee` | string[] | none | Consignee corporation IDs | |
+| `filter_hard_data` | enum[] | none | Data source confidence: `external`, `model`, `bol`, `port`, `fixture`, `market_analyst` | |
+| `filter_confidence` | enum | `low` | Minimum confidence level. `low` = all data included. | Set higher for high-confidence analysis only. |
+| `intra_movements` | enum | `all` | `all`, `exclude_intra_country`, `exclude_intra_geography` | ALWAYS set `exclude_intra_country` for exports/imports. |
+| `quantity_at_time_of` | enum | `load` | `load` or `unload`. Controls loaded vs discharged volume. | Use `unload` for LNG discharged volumes (boil-off). |
+| `timeseries_activity_time_span_min` | number | none | Minimum activity duration in milliseconds | For long-term storage: e.g., >14 days = `1000*60*60*24*14`. |
+| `timeseries_activity_time_span_max` | number | none | Maximum activity duration in milliseconds | For short-term storage filtering. |
+| `exclude_ship_to_ship` | boolean | false | Exclude all STS movements from results | Set `true` to remove STS transfers entirely. |
+
+**Exclusion filters:** Most filter parameters have `exclude_` counterparts (e.g., `exclude_origins`, `exclude_products`, `exclude_vessels`, `exclude_vessel_classes`, `exclude_charterers`, `exclude_effective_controllers`, `exclude_vessel_flags`, `exclude_waypoints`, `exclude_destinations`, `exclude_owners`, `exclude_vessel_owners`, `exclude_time_charterers`, `exclude_ship_to_ship_locations`, `exclude_storage_locations`).
+
+### Activity Filter Values
+
+**Timestamps** (event occurred within the time window):
+
+| Value | Meaning |
+|---|---|
+| `identified_for_loading_at` | When algorithms first detect a future movement |
+| `loading_start` | When cargo begins loading onto vessel |
+| `loading_end` | When vessel departs port of origin |
+| `storing_start` | When vessel enters floating storage |
+| `storing_end` | When floating storage period ends |
+| `unloading_start` | When vessel arrives at destination port |
+| `unloading_end` | When vessel is fully discharged |
+| `ship_to_ship_start` | When STS transfer begins |
+| `ship_to_ship_end` | When STS transfer ends |
+| `waypoint_start` | When ship enters a waypoint |
+| `waypoint_end` | When ship exits a waypoint |
+
+**States** (movement was in this state at any point during the time window):
+
+| Value | Meaning | Common User Term |
+|---|---|---|
+| `loading_state` | Cargo is being loaded | "loadings" |
+| `unloading_state` | Cargo is being unloaded | "discharged" |
+| `transiting_state` | Vessel is en route | "in transit" |
+| `storing_state` | Movement is in floating storage | "floating storage" |
+| `cargo_on_water_state` | Between departing origin and arriving destination | "on the water", "afloat" |
+| `identified_for_loading_state` | Between detection and loading start | "identified for loading" |
+| `unloaded_state` | After full discharge | "completed" |
+| `any_activity` | Any state during the time period | "everything" |
+
+**Note:** `oil_on_water_state` is DEPRECATED -- always use `cargo_on_water_state`.
+
+### Breakdown Properties (timeseries_property / split_property)
+
+Set `timeseries_property` (also referred to as the "split property" or breakdown dimension) to split aggregate results into sub-categories.
+
+**Geographic breakdowns:**
+
+| Value | Splits By | Example Use |
+|---|---|---|
+| `origin_country` | Origin country | "exports by source country" |
+| `origin_port` | Origin port | "exports by loading port" |
+| `origin_terminal` | Origin terminal | "terminal-level loading detail" |
+| `origin_region` | Origin region | "exports by origin region" |
+| `origin_shipping_region_v2` | Origin shipping region v2 | "exports by shipping region" |
+| `origin_wider_shipping_region` | Origin wider shipping region | "broad origin grouping" |
+| `origin_trading_region` | Origin trading region | "by trading region" |
+| `origin_trading_sub_region` | Origin trading sub-region | "by trading sub-region" |
+| `origin_basin` | Origin basin | "by origin basin" |
+| `origin_country_zone` | Origin country zone | "by country zone" |
+| `origin_state_or_province` | Origin state or province | "by US state" |
+| `destination_country` | Destination country | "imports by receiving country" |
+| `destination_port` | Destination port | "imports by discharge port" |
+| `destination_terminal` | Destination terminal | "terminal-level discharge detail" |
+| `destination_region` | Destination region | "imports by destination region" |
+| `destination_shipping_region_v2` | Destination shipping region v2 | "imports by shipping region" |
+| `destination_wider_shipping_region` | Destination wider shipping region | "broad destination grouping" |
+| `destination_trading_region` | Destination trading region | "by destination trading region" |
+| `destination_trading_sub_region` | Destination trading sub-region | "by destination trading sub-region" |
+| `destination_basin` | Destination basin | "by destination basin" |
+| `destination_country_zone` | Destination country zone | "by destination country zone" |
+| `destination_state_or_province` | Destination state or province | "by destination state" |
+| `storage_location_country` | Storage country | "floating storage by country" |
+| `storage_location_region` | Storage region | "floating storage by region" |
+| `storage_location_shipping_region_v2` | Storage shipping region v2 | "floating storage by shipping region" |
+| `storage_location_trading_sub_region` | Storage trading sub-region | "storage by trading sub-region" |
+| `waypoint_selected` | Waypoint | "by transit waypoint" |
+
+**Product breakdowns:**
+
+| Value | Splits By | Example Use |
+|---|---|---|
+| `product_group` | Major product group (Crude, CPP, DPP, LPG, LNG) | "by product type" |
+| `product_group_product` | Sub-group product | "by product sub-group" |
+| `product_category` | Product category | "by product category" |
+| `product_grade` | Specific grade (e.g., Arab Light) | "by crude grade" |
+
+**Vessel breakdowns:**
+
+| Value | Splits By | Example Use |
+|---|---|---|
+| `vessel_class_group` | Top-level vessel type (oil, lpg, lng) | "by vessel type" |
+| `vessel_class_coarse` | Coarse vessel class | "by vessel class (coarse)" |
+| `vessel_class_granular` | Granular vessel class (most detailed) | "by vessel class (detailed)" |
+| `vessel_flag` | Vessel flag state | "by flag state" |
+
+**Commercial breakdowns:**
+
+| Value | Splits By | Example Use |
+|---|---|---|
+| `shipper` | Shipper | "by shipper" |
+| `consignee` | Consignee | "by consignee" |
+| `load_buyer` | Buyer at load | "by buyer" |
+| `discharge_buyer` | Buyer at discharge | "by discharge buyer" |
+| `load_seller` | Seller at load | "by seller" |
+| `discharge_seller` | Seller at discharge | "by discharge seller" |
+| `contract_type` | Spot vs Term | "by contract type" |
+| `delivery_method` | FOB, DES, CFR, CIF | "by delivery method" |
+
+### Response Format
+
+**Without breakdown** (`timeseries_property="quantity"` or omitted):
+```json
+{
+  "data": [
+    {"key": "2025-01-01T00:00:00.000Z", "value": 458665.0, "count": 12},
+    {"key": "2025-02-01T00:00:00.000Z", "value": 445024.0, "count": 11}
+  ]
+}
+```
+- `key`: timestamp for the time bucket
+- `value`: aggregate volume in the requested unit
+- `count`: number of cargo movements contributing
+
+**With breakdown** (any `timeseries_property` other than `quantity`):
+```json
+{
+  "data": [
+    {
+      "key": "2025-01-01T00:00:00.000Z",
+      "value": 458665.0,
+      "count": 12,
+      "breakdown": [
+        {"label": "China", "value": 250000.0},
+        {"label": "Japan", "value": 120000.0},
+        {"label": "South Korea", "value": 88665.0}
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Parameter Reference: CargoMovements Search
+
+**Endpoint:** `POST /v5/cargo/search`
+**SDK:** `CargoMovements().search(...)`
+**Purpose:** Retrieve individual cargo movement records with full event, vessel, product, and corporate entity detail.
+
+**NEVER** rely on the default `size=1` -- always set `size=500` for batch retrieval.
+
+### Additional Parameters (beyond CargoTimeSeries filters)
+
+| Parameter | Type | Default | Description | CRITICAL Notes |
+|---|---|---|---|---|
+| `cm_unit` | enum | `b` | Unit for quantity fields: `b`, `t`, `cbm` | Only absolute units (no rate units like `bpd`). |
+| `size` | integer | `1` | Records per page (0-500) | **Default is 1 -- ALWAYS set higher.** |
+| `order` | enum | `_id` | Sort field: `_id`, `loading_start`, `loading_end`, `unloading_start`, `unloading_end`, `vessel_name`, `quantity`, `charterer`, `product`, `origin`, `destination`, `grade`, `shipper`, `consignee` | |
+| `order_direction` | enum | `asc` | `asc` or `desc` | |
+| `search_after` | object | none | Pagination cursor from previous response's `next_request` | Not offset-based -- use `next_request` from response. |
+
+### DataFrame Column Naming Convention
+
+The SDK flattens nested cargo movement structures using dot notation with zero-based indexes.
+
+**Cargo-level fields:**
+- `cargo_movement_id`, `quantity`, `discharge_quantity`, `status`
+
+**Product hierarchy:**
+- `product.group.label`, `product.group_product.label`, `product.category.label`, `product.grade.label`
+- Each also has `.id`, `.layer`, `.probability`, `.source`
+
+**Load event location:**
+- `events.cargo_port_load_event.0.location.{terminal|port|country|region|shipping_region_v2|trading_region|trading_subregion}.label`
+- `events.cargo_port_load_event.0.{start_timestamp|end_timestamp}`
+
+**Unload event location:**
+- `events.cargo_port_unload_event.0.location.{terminal|port|country|region|shipping_region_v2|trading_region|trading_subregion}.label`
+- `events.cargo_port_unload_event.0.{start_timestamp|end_timestamp}`
+
+**Vessel info (first vessel):**
+- `vessels.0.{name|imo|mmsi|vessel_class|dwt|cubic_capacity|status}`
+- For STS movements, subsequent vessels use `vessels.1.*`, `vessels.2.*`, etc.
+
+**Corporate entities (at vessel level, NOT cargo level):**
+- `vessels.0.corporate_entities.charterer.label`
+- `vessels.0.corporate_entities.effective_controller.label`
+- `vessels.0.corporate_entities.time_charterer.label`
+
+**STS events:**
+- `events.cargo_sts_event.0.location.{country|port|region|shipping_region_v2}.label`
+- `events.cargo_sts_event.0.{from_vessel_name|to_vessel_name|start_timestamp|end_timestamp}`
+
+**Storage events:**
+- `events.cargo_storage_event.0.{start_timestamp|end_timestamp|vessel_id}`
+
+**FSO load/unload events:**
+- `events.cargo_fso_load_event.0.location.*`, `events.cargo_fso_unload_event.0.location.*`
+
+**Parent IDs (genealogy):**
+- `parent_ids.0.id`, `parent_ids.0.splinter_timestamp`
+
+**Default columns** (when `columns=None`):
+```python
+[
+    'events.cargo_port_load_event.0.location.port.label',
+    'events.cargo_port_unload_event.0.location.port.label',
+    'product.group.label',
+    'product.grade.label',
+    'quantity',
+    'discharge_quantity',
+    'vessels.0.name',
+    'events.cargo_port_load_event.0.end_timestamp',
+    'events.cargo_port_unload_event.0.start_timestamp',
+]
+```
+
+Use `columns='all'` for the full flattened view. Use a specific column list for targeted analysis.
+
+**Common column map for renaming:**
+```python
+column_map = {
+    'cargo_movement_id': 'cargo_id',
+    'quantity': 'quantity',
+    'discharge_quantity': 'discharge_quantity',
+    'status': 'status',
+    'product.group.label': 'product_group',
+    'product.grade.label': 'product_grade',
+    'events.cargo_port_load_event.0.location.port.label': 'load_port',
+    'events.cargo_port_load_event.0.location.country.label': 'load_country',
+    'events.cargo_port_load_event.0.location.shipping_region_v2.label': 'load_shipping_region',
+    'events.cargo_port_unload_event.0.location.port.label': 'unload_port',
+    'events.cargo_port_unload_event.0.location.country.label': 'unload_country',
+    'events.cargo_port_unload_event.0.location.shipping_region_v2.label': 'unload_shipping_region',
+    'vessels.0.name': 'vessel_name',
+    'vessels.0.imo': 'vessel_imo',
+    'vessels.0.vessel_class': 'vessel_class',
+    'vessels.0.corporate_entities.charterer.label': 'charterer',
+    'vessels.0.corporate_entities.effective_controller.label': 'effective_controller',
+}
+```
+
+---
+
+## Parameter Reference: CargoMovements Record
+
+**Endpoint:** `GET /v5/cargo/{id}`
+**SDK:** `CargoMovements().record(id, params={'unit': 'b'})`
+**Purpose:** Look up a single cargo movement by its ID.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `id` | string | Cargo movement ID (long or short format) |
+| `unit` | enum | `b`, `t`, or `cbm` |
+
+---
+
+## What is a Cargo Movement
+
+A cargo movement represents a **journey of a quantity of product between places**. It is the base data unit of the Vortexa API. Each movement has:
+
+- **Events**: loading, unloading, STS transfers, storage, waypoints -- each with location and timestamps
+- **Vessels**: one or more vessels that carried the cargo, each with corporate entities (charterer, effective controller, time charterer, owner)
+- **Product**: hierarchical classification (group -> group_product -> category -> grade)
+- **Quantity**: volume in the selected unit; `discharge_quantity` may differ from `quantity` for LNG due to boil-off gas
+
+### Ship-to-Ship Transfers (STS)
+
+A single cargo movement tracks from origin to final destination even if STS transfers occur mid-journey. The STS events are recorded in the `events` array. The movement retains one ID throughout.
+
+Use `exclude_ship_to_ship=true` to remove all STS movements from results when analysing direct port-to-port flows only.
+
+### Cargo Splits (Co-loads / Co-discharges / Genealogy)
+
+When cargo splits (partial STS discharge, partial port discharge), new cargo movement IDs are created. The relationship is captured in `parent_ids`:
+
+- `parent_ids` lists ancestors in genealogical order: immediate parent first, root last
+- `splinter_timestamp` records when the split occurred
+- Co-loaded parcels (multiple grades on same vessel) are distinct movements from the start
+
+**CRITICAL for analysis:**
+- When summing cargo movements manually, be aware of parent-child relationships to avoid double-counting
+- **CargoTimeSeries handles this automatically** -- ALWAYS prefer it for aggregate volume questions
+
+### Data Revisions
+
+Vortexa continuously updates cargo data. Revisions include:
+- New movements appearing (vessel starts loading)
+- Movements being dropped (false positive corrected)
+- Property updates without ID change (product, timestamps within same week, corporate entities)
+- ID changes when the start of movement shifts to a different calendar week (old ID dropped, new one created)
+
+Dropped IDs are no longer available. There is no changelog -- `parent_ids` reflects the latest view, not historical state.
+
+### Boil-Off Gas (LNG)
+
+LNG evaporates during transit (~0.1-0.2% per day). This means:
+- `discharge_quantity` < `quantity` for LNG movements
+- Use `quantity_at_time_of="load"` for loaded volume or `"unload"` for discharged volume
+- Default is `"load"`
+- For non-LNG, `discharge_quantity` equals `quantity`
+
+---
+
+## Intra-Movements (Domestic Flow Control)
+
+| Value | Behavior | Use When |
+|---|---|---|
+| `all` | Include all movements including domestic | Total volumes regardless of destination |
+| `exclude_intra_country` | Exclude same-country origin/destination | International trade (most common for exports/imports) |
+| `exclude_intra_geography` | Exclude same-region origin/destination | Cross-regional analysis |
+
+**Example:** Russia as origin, West of Suez as destination:
+- `all`: shows everything including Russia-to-Russia
+- `exclude_intra_country`: Russia to West of Suez, excluding Russia-to-Russia
+- `exclude_intra_geography`: excludes both Russia-to-Russia AND West of Suez-to-West of Suez internal flows
+
+---
+
+## Worked Examples
+
+### Example 1: Simple Export Volume Trend
+
+**User:** "Show me monthly crude exports from Saudi Arabia in 2025"
+
+**Analysis:**
+- "monthly" -> `timeseries_frequency="month"`
+- "crude" -> resolve "Crude & Condensates" group ID
+- "exports" -> `filter_activity="loading_end"` + `intra_movements="exclude_intra_country"`
+- "from Saudi Arabia" -> resolve Saudi Arabia country ID -> `filter_origins`
+- "in 2025" -> `filter_time_min=datetime(2025,1,1)`, `filter_time_max=datetime(2025,12,31,23,59,59)`
+- No unit specified + oil -> default to `bpd`
+- Aggregate volume question -> **CargoTimeSeries**
+
+```python
+from vortexasdk import CargoTimeSeries, Geographies, Products
+from datetime import datetime
+
+saudi = [g.id for g in Geographies().search("Saudi Arabia", filter_layer="country").to_list()]
+crude = [p.id for p in Products().search("crude").to_list() if p.name == "Crude & Condensates"]
+
+df = CargoTimeSeries().search(
+    filter_activity="loading_end",
+    filter_time_min=datetime(2025, 1, 1),
+    filter_time_max=datetime(2025, 12, 31, 23, 59, 59),
+    filter_origins=saudi,
+    filter_products=crude,
+    intra_movements="exclude_intra_country",
+    timeseries_frequency="month",
+    timeseries_unit="bpd"
+).to_df()
+```
+
+### Example 2: Flow with Breakdown
+
+**User:** "How much crude does the Middle East export to Asia by destination country, weekly, in barrels per day?"
+
+**Analysis:**
+- "how much" + "weekly" -> CargoTimeSeries with `timeseries_frequency="week"`
+- "crude" -> Crude & Condensates product group ID
+- "export" -> `filter_activity="loading_end"` + `intra_movements="exclude_intra_country"`
+- "from the Middle East" -> resolve MEG region ID -> `filter_origins`
+- "to Asia" -> resolve Asia region ID -> `filter_destinations`
+- "by destination country" -> `timeseries_property="destination_country"`
+- "barrels per day" -> `timeseries_unit="bpd"`
+
+```python
+df = CargoTimeSeries().search(
+    filter_activity="loading_end",
+    filter_time_min=datetime(2025, 1, 1),
+    filter_time_max=datetime(2025, 6, 30, 23, 59, 59),
+    filter_origins=meg_ids,
+    filter_destinations=asia_ids,
+    filter_products=crude_ids,
+    intra_movements="exclude_intra_country",
+    timeseries_frequency="week",
+    timeseries_unit="bpd",
+    timeseries_property="destination_country"
+).to_df()
+```
+
+**Response format with breakdown:** Each row has `key` (timestamp), `value` (total), `count`, and a `breakdown` array of `{label, value}` pairs for each destination country.
+
+### Example 3: Individual Cargo Records
+
+**User:** "List all VLCC crude cargoes that loaded from the US Gulf in January 2025"
+
+**Analysis:**
+- "list" + "cargoes" -> **CargoMovements search** (not TimeSeries)
+- "VLCC" -> `filter_vessel_classes=["oil_vlcc"]`
+- "crude" -> Crude product group ID -> `filter_products`
+- "loaded" -> `filter_activity="loading_state"`
+- "from the US Gulf" -> USG geography ID -> `filter_origins`
+- "January 2025" -> `filter_time_min=datetime(2025,1,1)`, `filter_time_max=datetime(2025,1,31,23,59,59)`
+
+```python
+from vortexasdk import CargoMovements
+
+df = CargoMovements().search(
+    filter_activity="loading_state",
+    filter_time_min=datetime(2025, 1, 1),
+    filter_time_max=datetime(2025, 1, 31, 23, 59, 59),
+    filter_origins=usg_ids,
+    filter_products=crude_ids,
+    filter_vessel_classes=["oil_vlcc"],
+    cm_unit="b",
+    size=500
+).to_df(columns="all")
+```
+
+### Example 4: Floating Storage
+
+**User:** "What are the current floating storage levels for crude in the Middle East?"
+
+**Analysis:**
+- "floating storage" -> `filter_activity="storing_state"`
+- "current" -> recent time window (last 7 days)
+- "crude" -> Crude product group ID
+- "in the Middle East" -> `filter_storage_locations=[meg_id]`
+- Aggregate question -> **CargoTimeSeries**
+
+```python
+df = CargoTimeSeries().search(
+    filter_activity="storing_state",
+    filter_time_min=datetime(2025, 6, 1),
+    filter_time_max=datetime(2025, 6, 7, 23, 59, 59),
+    filter_products=crude_ids,
+    filter_storage_locations=meg_ids,
+    timeseries_frequency="day",
+    timeseries_unit="b"
+).to_df()
+```
+
+### Example 5: Excluding Domestic Flows
+
+**User:** "Show me Russian crude exports, excluding domestic movements"
+
+**Analysis:**
+- "exports" -> `filter_activity="loading_end"` + `intra_movements="exclude_intra_country"`
+- "excluding domestic" is already implied by `exclude_intra_country`, but explicitly stated here for clarity
+- "Russian" -> resolve Russia country ID -> `filter_origins`
+- "crude" -> resolve Crude & Condensates group ID -> `filter_products`
+
+```python
+df = CargoTimeSeries().search(
+    filter_activity="loading_end",
+    filter_origins=russia_ids,
+    filter_products=crude_ids,
+    intra_movements="exclude_intra_country",
+    timeseries_frequency="month",
+    timeseries_unit="bpd",
+    filter_time_min=datetime(2025, 1, 1),
+    filter_time_max=datetime(2025, 12, 31, 23, 59, 59)
+).to_df()
+```
+
+---
+
+## Defaults When Omitted
+
+| Parameter | Default | Risk | Recommendation |
+|---|---|---|---|
+| `filter_activity` | `any_activity` | Matches ALL cargo states -- misleading aggregates | ALWAYS specify explicitly |
+| `filter_time_min/max` | Current timestamp | Non-reproducible results | ALWAYS specify explicitly |
+| `timeseries_frequency` | `day` | Too granular for long ranges | Match to date range (see `date-units.md`) |
+| `timeseries_unit` | `b` (barrels) | Wrong for LNG (`t`) and rate queries (`bpd`) | Match to commodity and query type |
+| `timeseries_property` | `quantity` | No breakdown applied | Set when user asks "by X" |
+| `timeseries_activity` | same as `filter_activity` | Unexpected if user wants different aggregation | Only set differently for advanced use |
+| `cm_unit` | `b` (search), `t` (REST) | Inconsistent between SDK and REST | Specify explicitly |
+| `intra_movements` | `all` | Includes domestic flows, inflating export/import volumes | Set `exclude_intra_country` for international trade |
+| `quantity_at_time_of` | `load` | For LNG, loaded != discharged due to boil-off | Use `unload` for delivered volumes |
+| `size` (search only) | `1` | Returns only 1 record | ALWAYS set to 500 for batch retrieval |
+| `filter_vessel_scrubbers` | `disabled` | No scrubber filter | Usually fine |
+| `filter_confidence` | `low` | Includes all confidence levels | Set higher for high-confidence-only analysis |
+
+---
+
+## Error Recovery
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| Empty results | Wrong entity IDs | Re-run entity search, verify names resolved to correct IDs |
+| Empty results | Time range too narrow | Widen the time window to confirm data exists |
+| Empty results | Wrong `filter_activity` | "exports" = `loading_end`, "imports" = `unloading_start` |
+| Empty results | `intra_movements` excluding data | Try `all` first to confirm data exists, then re-add exclusion |
+| Empty results | Over-filtering | Remove filters one at a time to isolate the issue |
+| Only 1 record | `size` still at default | Set `size=500` for CargoMovements search |
+| Volumes too low | Used `loading_state` instead of `loading_end` for exports | Change to `loading_end` |
+| Volumes too high | `intra_movements="all"` including domestic | Set to `exclude_intra_country` |
+| Unexpected volumes | LNG boil-off | Check `quantity_at_time_of` -- `load` vs `unload` differ for LNG |
+| Unexpected volumes | Wrong product hierarchy level | `group` captures everything under it; `grade` is very specific |
+| Unexpected volumes | `timeseries_activity` differs from `filter_activity` | Ensure they match unless intentionally different |
+| Double-counting | Manual sum of split cargoes | Use CargoTimeSeries (handles splits automatically) or check `parent_ids` |
+| Missing final day data | `filter_time_max` at midnight | Add time component: `datetime(Y, M, D, 23, 59, 59)` |
+
+---
+
+## Validation Checklist
+
+Run through these before every API call:
+
+1. `filter_time_min` is before `filter_time_max`
+2. `filter_time_max` includes time component `(23, 59, 59)` for historical end dates
+3. Time range does not exceed ~4 years per request (performance)
+4. `size` is set to 500 for CargoMovements search (not default 1)
+5. All ID-based filters use valid 64-character hex Vortexa IDs
+6. `timeseries_unit` matches commodity: `b`/`bpd` for oil, `t`/`tpd` for LNG/LPG
+7. `filter_activity` is explicitly set (not relying on `any_activity` default)
+8. `intra_movements` is set to `exclude_intra_country` for exports/imports
+9. Breakdown dimension (`timeseries_property`) is relevant to the query
+10. For pagination, use `search_after` from `next_request` (not offset-based)