Kpler

# Congestion Series Retrieves a time series of vessel congestion data, providing insights into port and regional congestion patterns over time measured by different metrics. ## Key Use Cases - **Congestion Pattern Analysis**: Track vessel congestion trends over time across different ports and regions - **Port Performance Monitoring**: Analyze port efficiency and congestion duration patterns - **Market Impact Assessment**: Understand how congestion affects cargo flows and vessel operations - **Regional Comparison**: Compare congestion metrics across different geographic areas and installations ## Usage Guidance ### Input Parameters Guidelines & Caveats **Unit Parameter** - ALWAYS Use the correct unit for the product type: - `tons` for dry products - `barrels` for liquids products (oil, jet fuel, diesel...) - `cubic meters` (m³) for `LNG` product - Apply multipliers when appropriate (`ktons`, `mtons`, `mmbarrels`…). - At display time, ALWAYS convert to a suitable unit. Example: for >1,000,000 tons, use ktons or mtons. Explain your choice of unit before calling this tool. **Product Filtering:** - DO USE the `products` parameter to only get the relevant entries whenever possible **Vessel Type Filtering:** - DO NOT USE VesselTypes, VesselTypesOil and VesselTypesCpp parameter if the user didn't explicitly request a specific vessel type - Beware: a Crude or LNG Tanker is not a specific vessel type **Split Guidelines:** - NEVER MIX `total` with other split values **CongestionOnly Parameter** - When asked about Suez or Panama, ALWAYS set congestionOnly to false ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Analysis Features - Time series analysis of vessel congestion patterns - Flexible metrics including count, deadWeight, duration, and capacity - Support for various split dimensions (country, port, installation, vessel type, etc.) - Commodity-specific filtering (Liquids, Dry, LNG, LPG) - Customizable time periods and date ranges - Advanced filtering by vessel characteristics and operations ## Examples - Track daily vessel congestion trends in major Asian ports by country? ```python commodityType="liquids" metric="count" split="country" vesselOperation="Load" startDate="2025-08-01" endDate="2025-08-13" zones=["China", "Singapore"] period="days" ``` - Analyze congestion duration patterns at specific installations? ```python commodityType="liquids" metric="duration" split="installation" vesselOperation="Discharge" startDate="2025-08-01" endDate="2025-08-13" zones=["Rotterdam"] period="weeks" products=["Crude"] ``` ## Output Format A CSV formatted time series with columns for: - Date (period start) - Split dimension columns (e.g., country names, installation names) - Metric values (count, deadweight, duration, or capacity) **Example:** ```csv Date;Singapore Republic;China 2025-08-01;91;59 2025-08-02;84;66 2025-08-03;82;67 ``` ## Technical Notes - Congestion is determined by waiting duration thresholds and zone-specific parameters - Duration metric provides average waiting time in hours - Count metric shows number of vessels in congestion - DeadWeight and capacity metrics show tonnage or capacity of congested vessels - Data is updated in real-time based on AIS vessel tracking

kpler_get_congestion_series

# Congestion Vessels Retrieves a list of vessels currently experiencing congestion at ports, providing detailed information about individual vessels based on waiting duration and zone-specific criteria. ## Key Use Cases - **Individual Vessel Congestion Tracking**: Monitor specific vessels currently experiencing congestion - **Congestion Duration Analysis**: Analyze how long individual vessels have been in congested states - **Vessel-level Impact Assessment**: Understand congestion effects on specific vessel operations - **Detailed Congestion Investigation**: Get comprehensive data on vessels contributing to port congestion ## Usage Guidance ### Input Parameters Guidelines & Caveats **Vessel Type Filtering:** - DO NOT USE VesselTypes, VesselTypesOil and VesselTypesCpp parameter if the user didn't explicitly request a specific vessel type - Beware: a Crude or LNG Tanker is not a specific vessel type **Columns Parameter** You **must** specify which columns to include in the response using the `columns` parameter. This dramatically reduces response size and focuses on specific data fields essential for your analysis. 1. **Always start with essential columns:** `["vessel", "vessel_imo", "cargo_tons", "product", "installation", "congestion_duration_hrs"]` 2. **Add location details if needed:** Add `"port"`, `"country"`, `"zone"` 3. **Add exact timing details if needed:** Add `"congestion_start_date"`, `"congestion_end_date"` 4. **Set `columns="all"` only if you need comprehensive data** **Size Parameter:** - Use **size=10000** when you want all available data - Use smaller values only if you need to limit results for performance reasons **CongestionOnly Parameter** - When asked about Suez or Panama, ALWAYS set congestionOnly to false ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Get detailed information on vessels currently in congestion at Singapore? ```python commodityType="liquids" size=10000 vesselOperation="Load" zones=["Singapore"] startDate="2025-08-13" endDate="2025-08-13" columns=["vessel", "cargo_tons", "product", "installation", "congestion_duration_hrs"] ``` - Find all crude oil vessels waiting for discharge in major ports for over 48 hours? ```python commodityType="liquids" size=10000 vesselOperation="Discharge" products=["Crude"] waitingDurationMin=2 zones=["World"] startDate="2025-08-13" endDate="2025-08-13" ``` ## Output Format A CSV formatted list with columns including: - Date, IMO, Name, Dead Weight Tonnage - Cargo details (tonnage, family, group, products) - Location (installation, port, country, zone) - Congestion details (waiting start/end dates, waiting time in hours, status) - Vessel information (type, operation) **Example:** ```csv Date (timestamp);IMO;Name;Dead Weight Tonnage;Cargo (t);Products;Installation;Waiting Time (hrs);Vessel Type;Vessel Operation 2025-08-13;9543536;Alegria I;104494;63242.451;FO;ExxonMobil PAC Refinery;199.95;LR2;Load 2025-08-13;9645437;Aegean Vision;164950;-81333.97;Crude;Tankstore;179.01;VLCC;Discharge ``` ## Technical Notes - Real-time data based on AIS vessel positions and port zone definitions - Supports filtering by minimum/maximum waiting duration in days - **`cargo_tons` sign convention:** Positive values = vessels loading; negative values = vessels discharging. This matches the `vessel_operation` column. Use `abs(cargo_tons)` when comparing magnitudes regardless of flow direction.

kpler_get_congestion_vessels

# Contracts The **Contracts** endpoint allows you to extract a list of **SPAs, TUAs, LTAs, and Tenders** for LNG players, installations, and zones. > In order to select specific columns to display, please use the **column IDs** listed in the endpoint documentation ("Columns id, name, description and deprecation status"). ## Key Use Cases - **Contract Landscape Monitoring**: Track long-term LNG commercial agreements by counterparties and regions - **Counterparty Analysis**: Filter contracts by key buyers/sellers using `players` - **Geographic Analysis**: Focus on specific destination/origin geographies via `zones` and `installations` - **Contract Type Analysis**: Isolate `SPA`, `TUA`, `LTA`, or `Tender` contracts using `types` ## Usage Guidance ### Input Parameters Guidelines & Caveats **IMPORTANT**: This tool has no `commodityType` input parameter (it is LNG-only). **Size Parameter** - Use larger `size` values when you need a broader extract - If results equal your `size` limit exactly, increase it to check if more rows are available **Types Parameter** - Valid values are: `["SPA", "TUA", "LTA", "Tender"]` - Use this filter when the user asks for one contract family only **Columns Parameter** - First call `contracts_columns_v1` to retrieve the latest valid column IDs - Use `columns=["all"]` to retrieve all available columns - Otherwise pass only the required column IDs to keep responses focused and lighter **Date Parameters** - `startDate` and `endDate` must use `YYYY-MM-DD` - Resolve relative periods ("last quarter", "this year") before calling the tool ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), explain how the range is computed - Week definition: weeks start on Monday by default - "Last week" = previous Monday to Sunday (not the last 7 days) - "Next week" = following Monday to Sunday (not the next 7 days) ## Input Parameters - `size`: Optional integer. Maximum number of contracts returned. - `players`: Optional list of strings. Name of buyer or seller involved in a contract. - `zones`: Optional list of strings. Country, region, or continent of installations involved in a contract. - `installations`: Optional list of strings. Names of installations. - `startDate`: Optional date. Start of the period (`YYYY-MM-DD`). - `endDate`: Optional date. End of the period (`YYYY-MM-DD`). - `types`: Optional list of strings. Use `["SPA", "TUA", "LTA", "Tender"]`. - `columns`: Optional list of strings. Use `"all"` to retrieve all available columns. ## Examples - Show all contract types in Europe with a short sample: ```python zones = ["europe"] size = 3 ``` - Show only SPA contracts signed in a specific period and return all columns: ```python zones = ["europe"] types = ["SPA"] startDate = "2030-01-01" endDate = "2038-12-31" columns = ["all"] size = 100 ``` ## Output Format Returns a CSV-style dataset where each row is a contract matching your filters. Common fields include: - `Type`, `Seller`, `Buyer` - `Capacity`, `Slots`, `Delivery` - `Start`, `End` - `Origin Zone`, `Destination Zone` ## Technical Notes - Date/time values are returned in UTC format from the upstream endpoint - The response can vary depending on selected `columns`

kpler_get_contracts_v1

# Contracts Columns This endpoint returns an up-to-date list of all columns available for the LNG contracts endpoint. ## Key Use Cases - **Column Discovery**: Retrieve valid column IDs for `contracts` queries - **Schema Validation**: Confirm which columns are currently available - **Deprecation Awareness**: Detect deprecated fields before building queries ## Usage Guidance ### Input Parameters Guidelines & Caveats **IMPORTANT**: This endpoint does not require query parameters. ### Recommended Workflow Use this endpoint before calling `contracts`: 1. Call `contracts_columns_v1` to fetch the latest column catalog. 2. Choose valid column IDs from the response. 3. Call `contracts_v1` with `columns=[...]` (or `columns=["all"]`). ## Examples - Retrieve current contracts column catalog: ```python # no parameters required ``` ## Output Format Returns a JSON object with two arrays: - `selected`: list of available columns with metadata - `unselected`: list of columns currently not selected Each column object typically includes: - `id` - `shortId` - `columnName` - `description` - `deprecated` - `type` Where: | Field | Description | | ----- | ----------- | | selected | Columns currently selected by default | | unselected | Additional columns available for selection |

kpler_get_contracts_columns_v1

# Crude Inventories Fetches global crude oil storage data using SAR satellite analysis to track global floating roof crude inventories with enhancement options for improved data accuracy. ## Key Use Cases - **Global Inventory Monitoring**: Track crude oil storage levels across global installations using satellite data - **Storage Capacity Analysis**: Monitor storage capacity utilization rates at different installations - **Market Supply Assessment**: Analyze inventory levels for market supply and demand insights - **Enhanced Data Analysis**: Use cargo tracking enhancements and EIA adjustments for improved accuracy ## Usage Guidance ### Input Parameters Guidelines & Caveats **Parameter Requirements:** - ALWAYS set parameters accordingly: granularity, splits and startDate/endDate - ALWAYS explain how you choose the value for fromDate and endDate arguments - ALWAYS ensure the fromDate/endDate argument matches the time range requested by the user - ALWAYS set the startDate and endDate to the shortest possible period to avoid too many results - For any zone, ALWAYS find the corresponding valid zone name from the 'get_kpler_zones' tool **Split Guidelines:** - You can apply multiple splits based on parameters such as Installation, Country, etc. - IMPORTANT: `totals` CAN NEVER be used with other splits - DO NOT MIX `totals` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Data Enhancement Options - **EIA Adjustment**: Remove the EIA adjustment factor from inventory and capacity values - **Cargo Tracking Enhancement**: Use cargo tracking data to fill gaps between satellite images ### Technical Limitations - Satellite data points updated between 6-13 days on average (some locations may be longer) - Historical limit: 1 January 2017 ## Examples - Track US crude oil storage levels over the last month ```python granularity="monthly" startDate="2025-07-01" endDate="2025-07-31" zones=["United States"] splits=["totals"] unit="kb" ``` - Monitor Singapore refinery crude inventories at installation level ```python granularity="weekly" startDate="2025-08-01" endDate="2025-08-07" zones=["Singapore"] splits=["installations"] unit="kb" ``` ## Output Format A JSON response containing time-series data with the following fields: **Time Series Structure:** - `date`: Period start date (YYYY-MM-DD) - `split`: Array containing inventory data for the specified split level **Inventory Data Fields:** - `storageVolume`: Current volume of stored crude oil in the specified unit - `storageCapacity`: Maximum storage capacity of the installation in the specified unit - `capacityUtilization`: Ratio of current storage volume to total capacity (0.0-1.0) - `revisitRate`: Frequency of satellite revisits for this installation - `lastImage`: Date of the last satellite image capture (YYYY-MM-DD format) - `valueDate`: Date for which the reported values are valid (YYYY-MM-DD format) - `unit`: Unit of measurement for volume values (e.g., "kb" for kilobarrels) **For installation-level splits, additional fields:** - `installationName`: Name of the storage installation ## Integration with Other Tools - Can be complemented by `kpler_get_cargo_fleet_metrics` with metric="floating-storage" to obtain crude volumes currently stored on vessels

kpler_get_crude_inventories

# Cushing Drones Inventories Provides Cushing crude oil inventory levels across all installations twice weekly using Cushing-AI, a machine learning model processing high-definition optical and infrared images. ## Key Use Cases - **Cushing Hub Monitoring**: Track inventory levels at the critical Cushing crude oil hub twice weekly - **Market Analysis**: Analyze inventory trends affecting WTI crude oil pricing and market dynamics - **AI-Enhanced Accuracy**: Leverage machine learning model trained on expert annotations for precise inventory tracking - **High-Frequency Updates**: Access mid-weekly and end-weekly inventory data for timely market insights ## Usage Guidance ### Input Parameters Guidelines & Caveats **Timing parameter** - mid-weekly updates: Available on Wednesdays - end-weekly-preliminary: Available on Fridays **Split Parameter** - Supports multiple split applications based on various parameters - NEVER MIX `totals` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Track total Cushing crude oil inventories for mid-weekly updates ```python timing="mid-weekly" startDate="2025-08-01" endDate="2025-08-13" splits=["totals"] unit="kb" ``` - Monitor individual Cushing installations with end-weekly data ```python timing="end-weekly-preliminary" startDate="2025-08-01" endDate="2025-08-09" splits=["installations"] unit="mmbls" ``` ## Output Format A JSON response containing time-series data with the following fields: **Time Series Structure:** - `date`: Period start date (YYYY-MM-DD) - `split`: Array containing inventory data for the specified split level **Inventory Data Fields:** - `flightDate`: Date when the drone flight was conducted (YYYY-MM-DD) - `storageVolume`: Current volume of stored crude oil in the specified unit - `storageCapacity`: Maximum storage capacity in the specified unit - `storageVolumeDelta`: Change in storage volume from previous period (null for first period) **For installation-level splits, additional fields:** - `installationName`: Name of the Cushing storage installation ## Technical Notes - Historical Data Limits: - Mid-weekly: Available from May 12, 2021 - End-weekly-preliminary: Available from August 2, 2019 - Methodology notes and FAQ: [Cushing Drone Inventories Guide](https://help.kpler.com/en/articles/5530686-cushing-drone-inventories#h_a4cb94bd9f)

kpler_get_cushing_drones_inventories

# Fleet Development Series Retrieves time series data related to vessel supply dynamics, including new orders, deliveries, demolitions, and active fleet counts, with grouping and filtering by vessel characteristics. ## Key Use Cases - **Fleet Supply Analysis**: Track vessel supply dynamics including new orders and deliveries over time - **Market Capacity Monitoring**: Analyze fleet development trends affecting market capacity - **Vessel Lifecycle Tracking**: Monitor deliveries, demolitions, and active fleet counts - **Industry Growth Analysis**: Understand fleet development patterns and market expansion ## Usage Guidance ### Input Parameters Guidelines & Caveats **Commodity Type Requirements:** - You must specify the commodity type concerned when calling this tool - If the user asks about fleet development not specific to one commodity type, query for all 4: liquids, lng, lpg and dry **Metric Types:** - `deliveries`: Track newly delivered vessels entering the fleet - `scrapping`: Monitor vessels being decommissioned or scrapped - `contracting`: Analyze new vessel orders placed - `available`: Count active vessels in the fleet **Split Guidelines:** - NEVER MIX `total` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Analysis Features Results can be grouped and filtered by vessel characteristics, period, and metric type including: - New orders tracking - Delivery monitoring - Demolition analysis - Active fleet counts ## Examples - Track quarterly tanker deliveries by vessel type in 2024? ```python commodityType="liquids" metric="deliveries" aggregationMetric="count" startDate="2024-01-01" endDate="2024-12-31" period="quarters" split="vesselTypeOil" ``` - Analyze annual fleet capacity growth across all commodity types? ```python commodityType="liquids" metric="available" aggregationMetric="sumdeadweight" startDate="2020-01-01" endDate="2024-12-31" period="years" unit="mt" ``` ## Output Format A CSV formatted time series dataset with the following possible columns (depending on split): - Period start date - Metric value (e.g. number of vessels, capacity) - Split (e.g. vessel type, compliance method) - Unit (kt or mt) **Example:** ```csv Date;Small Tanker;Product Tanker;Aframax;Suezmax;VLCC 2024-Q1;26;25;11;1;1 2024-Q2;40;17;5;; 2024-Q3;195;19;6;3;2 ``` ## Technical Notes - Data tracks vessel lifecycle events from contracting through delivery to scrapping - Aggregation metrics: count (number of vessels), sumdeadweight/sumcapacity (tonnage/capacity) - Historical data available for comprehensive fleet development analysis - Supports filtering by vessel characteristics, build year, and compliance methods

kpler_get_fleet_development_series

# Fleet Development Vessels Returns a detailed list of vessels contributing to a selected fleet development metric (e.g., deliveries, scrapping), with filtering by vessel attributes, compliance methods, types, and period. ## Key Use Cases - **Individual Vessel Tracking**: Monitor specific vessels contributing to fleet development metrics - **Delivery Analysis**: Analyze detailed information about newly delivered vessels - **Scrapping Monitoring**: Track vessels being decommissioned or scrapped - **Fleet Composition Analysis**: Understand vessel characteristics affecting fleet development ## Usage Guidance ### Input Parameters Guidelines & Caveats **Commodity Type Requirements:** - You must specify the commodity type concerned when calling this tool - If the user asks a question that is not to one specific commodity type, you MUST query for all 4 commodity types: liquids, lng, lpg and dry **Column Selection:** - You must specify which columns to include in the response using the `columns` parameter - The `columns` parameter accepts a list of columns **Size Parameter:** - Use **size=10000** (maximum limit) when you want all available data - Use smaller values only if you need to limit results for performance reasons ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Get details on all oil tankers delivered in August 2024? ```python commodityType="liquids" metric="deliveries" size=10000 startDate="2024-08-01" endDate="2024-08-31" columns=["vessel_name", "vessel_imo", "vessel_dead_weight", "vessel_build_year", "vessel_type_alt"] ``` - Find all VLCC tankers scrapped in 2024 with ownership details? ```python commodityType="liquids" metric="scrapping" vesselTypesOil=["VLCC"] startDate="2024-01-01" endDate="2024-12-31" size=10000 columns=["vessel_name", "vessel_imo", "vessel_dead_weight", "Owners_names", "vessel_dead_at"] ``` ## Output Format A CSV formatted string of vessels with columns that can be selected using the 'columns' parameter (which accepts a list of strings). | Column Name | Display Name | Description | | ------------------------------------ | ----------------------------- | --------------------------------------------- | | day | Day | Date (format: yyyy-MM-dd) | | vessel_name | Name | Name of the vessel | | vessel_imo | IMO | Vessel IMO number | | vessel_mmsi | MMSI | Maritime Mobile Service Identity (9 digits) | | vessel_status | Status | Status of the vessel | | vessel_build_year | Build year | Year of construction | | vessel_carrier_type | Carrier type | Ocean / Coastal | | vessel_flag_name | Flag name | Country flag | | vessel_engine_type | Engine type | Engine type | | vessel_cargo_system | Cargo system | Containment system | | vessel_cargo_type | Cargo type | Specific cargo type | | vessel_gross_tonnage | Gross tonnage | Gross tonnage | | vessel_dead_weight | Dead weight (t) | Dead weight in tons | | vessel_build_at | Build at | Building date | | vessel_order_at | Order at | Order date | | vessel_dead_at | Dead at | Decommission / death date | | vessel_last_dry_dock | Last dry dock | Date of last dry dock | | vessel_last_special_survey | Last special survey | Date of last special survey | | vessel_displacement | Displacement | Displacement | | vessel_depth | Depth | Depth of the vessel | | vessel_laden_speed | Laden Speed | Laden speed | | vessel_ballast_speed | Ballast Speed | Ballast speed | | vessel_tpcmi | TPCMI | Tons‑per‑centimeter immersion | | vessel_net_tonnage | Net tonnage | Net tonnage | | vessel_net_tonnage_suez | Net tonnage suez | Suez‑certified net tonnage | | vessel_net_tonnage_panama | Net tonnage panama | Panama‑certified net tonnage | | vessel_compliance_method | Compliance Method | Compliance method used | | vessel_scrubber_type | Scrubber type | Type of exhaust scrubber installed | | vessel_scrubber_date | Scrubber date | Date scrubber was installed | | vessel_capacity | Capacity (m³) | Maximum capacity in cubic meters | | current_vessel_controller_name | Current controller | Name of current vessel controller | | Owners_names | Owners | Vessel owners' names | | Operators_names | Operators | Vessel operators' names | | Builders_names | Builders | Vessel builders' names | | call_sign | Call Sign | Vessel call sign | | vessel_length | Length | Vessel length | | vessel_length_between_perpendiculars | Length between perpendiculars | Standard LBP measurement | | vessel_draught | Draught | Vessel's draught | | vessel_status_detail | Status detail | Additional status information | | vessel_ballast_consumption | Ballast Consumption | Ballast fuel consumption | | coating | Coating | Hull coating type | | vessel_type | Vessel type | Type of vessel | | vessel_type_alt | Vessel Type Alternative | Oil classification (e.g. Aframax, VLCC, etc.) | | coatingDetails | Coating Details | Additional coating specification details | | vessel_beam | Beam | Beam of the vessel | | vessel_build_country | Build Country | Country of vessel's construction | | vessel_build_month | Build Month | Month of construction | | builder | Builder | Builder of the vessel | | vessel_empirical_max_draught_change | Empirical max draught change | Max draught change empirical value | | vessel_horse_power | Horse Power | Engine horsepower | | vessel_is_ethylene_capable | Is ethylene capable | Ethylene compatibility (true/false) | | vessel_keel_laid_at | Keel laid at | Keel laying date | | vessel_launch_at | Launch at | Launch date | | vessel_light_displacement | Light Displacement | Vessel's light displacement | | vessel_mass | Mass | Mass of the vessel | | vessel_mass_capacity | Mass capacity | Mass capacity description | | vessel_mass_capacity_bale | Mass capacity bale | Bale capacity | | vessel_mass_capacity_grain | Mass capacity grain | Grain capacity | | vessel_mass_capacity_ore | Mass capacity ore | Ore capacity | | vessel_max_speed | Max Speed | Maximum vessel speed | | vessel_number_tanks | Number tanks | Number of cargo tanks | | vessel_price | Price | Price of the vessel | | vessel_ship_class | Ship Class | Commercial vessel class | | vessel_volume_gas | Volume Gas | Gas volume capacity | **Example:** ```csv Name;IMO;Dead weight (t);Build year;Vessel Type Alternative Almirante Tamandare;9919814;250000;2024;VLCC Sheng Hang Hua 16;1026154;7500;2024;Small Tanker Juan Hang Feng Da;9982251;3998;2024;Small Tanker ``` ## Technical Notes - Data tracks vessel events from order placement through delivery to scrapping - Supports filtering by compliance methods, vessel types, and build characteristics

kpler_get_fleet_development_vessels

# Fleet Metrics Vessels This endpoint provides users with comprehensive access to vessel-level fleet metrics data, allowing detailed analysis of vessels with their daily cargo in specific zones for either Floating Storage or Loaded Vessels metrics, including their location details. ## Key Use Cases - **Vessel Tracking**: Monitor specific vessels carrying cargo in designated zones - **Floating Storage Analysis**: Analyze vessels engaged in floating storage operations - **Cargo Volume Assessment**: Track cargo quantities across different vessel fleets - **Location-based Fleet Monitoring**: Monitor vessel positions and movements by geographic region ## Usage Guidance ### Input Parameters Guidelines & Caveats **Columns Parameter** You **must** specify which columns to include in the response using the `columns` parameter. This dramatically reduces response size and focuses on specific data fields essential for your analysis. ⚠️ **The `Quantity (X)` column you request must match the `unit` parameter.** Requesting `Quantity (kb)` with `unit="bbl"` returns empty values, not an error. Pick `unit` first, then request the matching `Quantity (<unit>)` column. 1. **Always start with essential columns:** `["Date", "IMO", "Name", "Product", "Quantity (<unit>)"]` — where `<unit>` matches the `unit` parameter 2. **Add tonnage if needed:** Add `"Dead Weight Tonnage"` 3. **Add location details if needed:** Add `"Current Continent"`, `"Current Country"` 4. **Add detailed location only if required:** Add `"Current Sea"`, `"Current Subcontinent"` See the Output Format section for more information about columns. **Unit Parameter** - ALWAYS Use the correct unit for the product type: - `t`, `kt`, or `mt` for dry products - `bbl`, `kb`, or `mmbbl` for liquids products (oil, jet fuel, diesel...) - `m³` (cubic meters) for `LNG` product - Apply multipliers when appropriate (`kb`, `mmbbl`, `kt`, `mt`…). - At display time, ALWAYS convert to a suitable unit. Example: for >1,000 barrels, use kb or mmbbl. Explain your choice of unit before calling this tool. **Date Range Constraint:** - The difference between `endDate` and `startDate` must be **strictly less than 31 days** (max 30 days). - Example (correct): `startDate=2025-07-13`, `endDate=2025-08-12` - Example (incorrect): `startDate=2025-07-12`, `endDate=2025-08-12` (31 days) **Metric Dependencies:** - **For `metric='loaded_vessels'`:** No additional parameters required - **For `metric='floating_storage'`:** ⚠️ **MUST provide both (non-null):** - `floatingStorageDurationMin` (one of: 7, 10, 12, 15, 20, 30, 90) - `floatingStorageDurationMax` (one of: 7, 10, 12, 15, 20, 30, 90, or "Inf") - By default set `floatingStorageDurationMax` to "Inf" ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Show me tonnage and quantities of all VLCC tankers carrying crude oil to Japan in the first week of August 2025? ```python commodityType = "liquids" metric = "loaded_vessels" products = ["Crude"] vesselTypesAlt = ["VLCC"] zones = ["Japan"] startDate = "2025-08-01" endDate = "2025-08-07" unit = "kb" columns = ["Date", "IMO", "Name", "Dead Weight Tonnage", "Product", "Quantity (kb)", "Current Country"] ``` - Show me oil tankers used for floating storage in the Mediterranean for more than 2 weeks? ```python commodityType = "liquids" metric = "floating_storage" floatingStorageDurationMin = 15 floatingStorageDurationMax = "Inf" zones = ["Mediterranean"] startDate = "2025-08-13" endDate = "2025-08-13" unit = "kb" columns = ["Date", "IMO", "Name", "Product", "Quantity (kb)", "Current Country", "Number of Floating Days"] ``` ## Output Format The following columns are available in the fleet metrics vessels response: | Column Name | Description | | ----------------------- | ---------------------------------------------------------------------------------- | | Date | Date of the fleet metrics data | | IMO | Vessel's IMO number | | Name | Name of the vessel | | Dead Weight Tonnage | Vessel's deadweight in tons | | Quantity (kb) | Quantity of cargo in kilobarrels (unit dependent) | | Family | Product family classification | | Group | Product group classification | | Product | Cargo product being transported | | Grade | Specific product grade | | Current Continent | Current continent location | | Current Subcontinent | Current subcontinent location | | Current Country | Current country location | | Current Sea | Current sea location | | Number of Floating Days | Number of days in floating storage (only available when metric="floating_storage") | | Floating Since | Start date of floating storage (only available when metric="floating_storage") | ## Technical Notes - All date/times within this endpoint are presented in Coordinated Universal Time (UTC) - Quantity columns are unit-dependent (e.g., `"Quantity (bbl)"`, `"Quantity (mmbbl)"`, etc.) based on the requested unit - Fleet metrics data is updated daily and represents vessels' cargo status at the end of each day

kpler_get_fleet_metrics_vessels

# Fleet Utilization Series Returns time-series metrics reflecting the utilization of a selected fleet segment, including total deadweight, capacity, or vessel count with comprehensive filtering and grouping options. ## Key Use Cases - **Fleet Efficiency Monitoring**: Track fleet utilization metrics over time to assess operational efficiency - **Capacity Analysis**: Analyze total deadweight and capacity utilization trends - **Segment Performance**: Compare utilization across different fleet segments and vessel types - **Market Utilization Trends**: Understand fleet utilization patterns affecting freight markets ## Usage Guidance ### Input Parameters Guidelines & Caveats **Required Parameters:** - `distinctAggregation`: Must be set to boolean (true/false) - controls whether to count unique vessels - `commodityType`: Required commodity type (liquids, lng, lpg, dry) - `metric`: Required metric type (count, deadWeight, capacity) **Metric Types:** - `count`: Number of vessels in the fleet - `deadWeight`: Total deadweight tonnage - `capacity`: Total capacity in cubic meters **Split Guidelines:** - NEVER MIX `total` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Filtering Capabilities Empowers users to search for specific fleet segments based on various parameters. These filters accept a list of strings. - **zones**: A list of zone names (e.g. `["Middle East", "Africa"]`) - **products**: A list of product names (e.g. `["Brent", "Gasoline"]`) - **vesselStates**: A list of vessel states (e.g. `["Ballast", "Loaded"]`) - **vesselTypesCpp**: A list of CPP vessel types (e.g. `["LR2", "VLCC"]`) - **vesselTypesOil**: A list of oil vessel types (e.g. `["Aframax", "Suezmax"]`) - **vesselTypes**: A list of vessel types for Dry, LNG, LPG (e.g. `["Capesize", "Q-Flex", "VLGC"]`) - **previousZones**: A list of zones the vessel is coming from (e.g. `["USGC (US Gulf Coast)"]`) - **nextZones**: A list of zones the vessel is going to (e.g. `["South China Sea"]`) ## Examples - Track daily global fleet utilization by vessel count? ```python commodityType="liquids" metric="count" split="total" startDate="2025-08-01" endDate="2025-08-13" period="days" distinctAggregation=false ``` - Analyze weekly deadweight capacity trends by vessel type? ```python commodityType="liquids" metric="deadWeight" split="vesselTypeOil" startDate="2025-07-01" endDate="2025-08-13" period="weeks" unit="mt" distinctAggregation=false ``` ## Output Format A CSV formatted time series with aggregated metric values per period (daily, weekly, etc.). Output includes: - Date (start of the period) - Aggregated metric value (`Total`) based on selected filters - Optionally, additional split columns if grouping is applied (e.g., vessel type, state, product) **Example:** ```csv Date;Total 2025-08-01;10184 2025-08-02;10183 2025-08-03;10183 ``` ## Technical Notes - `distinctAggregation` parameter is required and controls unique vessel counting - Metrics are aggregated based on vessel states (Ballast, Loaded, Maintenance, Other) - Supports filtering by vessel directions, zones, and operational states - Data reflects fleet utilization at daily granularity

kpler_get_fleet_utilization_series

# Fleet Utilization Vessels Retrieves a detailed list of vessels based on fleet utilization data, providing comprehensive vessel information for utilization analysis. ## Key Use Cases - **Individual Vessel Utilization**: Analyze specific vessels contributing to fleet utilization metrics - **Vessel Performance Tracking**: Monitor detailed performance data for vessels in the fleet - **Utilization-based Vessel Selection**: Identify vessels based on their utilization characteristics - **Detailed Fleet Analysis**: Get comprehensive vessel information for utilization studies ## Usage Guidance ### Input Parameters Guidelines & Caveats **Required Parameters** - `distinctAggregation`: Must be set to boolean (true/false) - `commodityType`: Required commodity type (liquids, lng, lpg, dry) **Size Parameter** - Use **size=200000** (maximum limit) when you want all available data - Use smaller values only if you need to limit results for performance reasons **Columns Parameter** You **must** specify which columns to include in the response using the `columns` parameter to focus on relevant data fields. - Use `columns="all"` only if you really need complete vessel information ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Get detailed vessel information for loaded tankers in Singapore? ```python commodityType="liquids" size=200000 startDate="2025-08-13" endDate="2025-08-13" zones="Singapore" vesselStates=["Loaded"] columns="all" distinctAggregation=false ``` - Find all VLCC vessels in ballast state globally? ```python commodityType="liquids" size=200000 vesselTypesOil=["VLCC"] vesselStates=["Ballast"] startDate="2025-08-13" endDate="2025-08-13" distinctAggregation=false ``` ## Output Format A CSV formatted response with comprehensive vessel details including: - Date, IMO, Name, Dead Weight Tonnage - Vessel Type, Vessel State, Last Product on board - Current location (Continent, Country, Sea) - Navigation details (Direction, Voyage ID, Port Call information) - Operational status (Floating Storage, FPSO/FSRU indicators) **Note:** Empty response if no vessels match the criteria for the specified date/zone combination. ## Technical Notes - Maximum 200,000 results per request to ensure performance - `distinctAggregation` parameter controls unique vessel counting logic - Vessel states: Ballast, Loaded, Maintenance, Other - Real-time vessel positions and operational states included

kpler_get_fleet_utilization_vessels

# Flows The Flows endpoint serves as an aggregation of trades, offering a macro-view of individual cargoes in real-time to quickly identify trends in the commodities market. ## Key Use Cases - **Market Trend Analysis**: Identify macro-level trends in commodities markets through trade aggregation - **Directional Analysis**: Analyze cargo movement patterns for imports, exports, or net flows - **Regional Comparison**: Compare trade flows across different origins and destinations - **Product Flow Tracking**: Monitor movement patterns for specific commodities and products ## Usage Guidance ### Input Parameters Guidelines & Caveats **TradeStatus Parameter** Specifies the trade depending on the vessel and cargo status: - **scheduled**: the vessel has not yet reached its berth and has not started loading - **loading**: the vessel is currently loading cargo - **in_transit**: the vessel is at sea with cargo loaded - **delivered**: the vessel has discharged its cargo at the destination port The statuses follow this chronology: scheduled -> loading -> in_transit -> delivered. **For present/current flows** (cargo currently moving): Use `tradeStatus` with `"in_transit"` or `"loading"` **without date parameters**. This returns aggregated volumes of cargo currently on the water. Example: *"What are the crude oil cargoes from Iran heading to China right now?"* → Use `tradeStatus=["in_transit"]` with `fromZones=["Iran"]`, `toZones=["China"]`, `products=["Crude"]`, `flowDirection="Export"` and **no date parameters**. **For future flows** (scheduled but not yet started): Use `tradeStatus=["scheduled"]` to analyze volumes that will be shipped in the future. **flowDirection and Date Relationship** The `flowDirection` parameter determines which date perspective is used for aggregation: - **Export**: Aggregates based on **departure date from origin** (corresponds to `originDateStart`/`originDateEnd` in Trades) - **Import**: Aggregates based on **arrival date at destination** (corresponds to `destinationDateStart`/`destinationDateEnd` in Trades) **IMPORTANT**: Always choose the `flowDirection` that matches your analysis perspective: - Use `"Export"` when analyzing **supply** from source countries/regions - Use `"Import"` when analyzing **demand** at destination countries/regions Example: *"I want to see OPEC exports in 2025"* → Use `flowDirection="Export"` with `fromZones=["OPEC"]`, `startDate="2025-01-01"`, `endDate="2025-12-31"`. Example: *"I want to know China imports of crude oil in 2025"* → Use `flowDirection="Import"` with `toZones=["China"]`, `products=["Crude"]`, `startDate="2025-01-01"`, `endDate="2025-12-31"`. **Flows from A to B**: When querying flows between specific origin and destination (e.g., "flows from Saudi Arabia to China"), use `flowDirection="Export"` by default as you're looking at when cargo left the exporter. **Always mention to the user that you are using the export perspective** so they understand how the data is aggregated. Example: *"Show me crude oil flows from Saudi Arabia to China in 2025"* → Use `flowDirection="Export"` with `fromZones=["Saudi Arabia"]`, `toZones=["China"]`, `products=["Crude"]`, `startDate="2025-01-01"`, `endDate="2025-12-31"`. → Tell the user: "I'm using the export perspective (aggregating by departure date from Saudi Arabia)". **Unit Parameter** - ALWAYS Use the correct unit for the product type: - `tons` for dry products - `barrels` for liquids products (oil, jet fuel, diesel...) - `cubic meters` (m³) for `LNG` product - Apply multipliers when appropriate (`ktons`, `mtons`, `mmbarrels`…). - At display time, ALWAYS convert to a suitable unit. Example: for >1,000,000 tons, use ktons or mtons. Explain your choice of unit before calling this tool. **Split Parameter**: - You can apply up to 5 splits simultaneously. For more granularity, you can use the `kpler_get_trades` tool - If asked about per-country results, always split both per destination and per origin countries using the split argument, unless the user explicitly specified to do only one: `split=["destinationCountries", "originCountries"]` - NEVER MIX `total` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Granular Split Capabilities ## Examples - What were the crude oil imports to China over the last month? ```python flowDirection="Import" granularity="monthly" toZones=["China"] products=["Crude"] startDate="2025-07-13" endDate="2025-08-13" split=["originCountries"] ``` - Compare LNG exports from US and Qatar in Q2 2025, broken down by destination countries? ```python flowDirection="Export" granularity="monthly" fromZones=["United States", "Qatar"] products=["LNG"] startDate="2025-04-01" endDate="2025-06-30" split=["destinationCountries", "originCountries"] ``` ## Output Format Returns an array of flow data, one for each time interval, containing quantities aggregated for the given splits values. For instance: ``` [ { "period": "2024-01-01", "splits": [ { "quantity": 1000.5, "unit": "ktons", "origin_country": "United States", "destination_country": "China" }, { "quantity": 500.2, "unit": "ktons", "origin_country": "Brazil", "destination_country": "China" } ... }, ... ] ``` ## Technical Notes - All date/times within this endpoint are presented in Coordinated Universal Time (UTC) - Empty or null values in split fields indicate that the split category is not applicable for that particular data point ## Integration with Other Tools - Do use kpler_get_trades if you need to get the list of vessels concerned by the flows

kpler_get_flows

# Freight Fixtures Retrieves a list of freight fixtures based on various parameters related to vessel movements, cargo, and contract terms, allowing analysis of freight contracts and pricing. ## Key Use Cases - **Freight Rate Analysis**: Track freight fixtures and pricing trends over specific time periods - **Market Activity Monitoring**: Monitor freight fixing activity and contract terms in the market - **Charter Market Analysis**: Analyze charterer activity and vessel owner participation - **Contract Terms Evaluation**: Examine laycan periods, origins, destinations, and pricing ## Usage Guidance ### Input Parameters Guidelines & Caveats **Size Parameter:** - Use **size=10000** when you want all available data - Use smaller values only if you need to limit results for performance reasons **Date Range Parameters:** - Use `reportedDateAfter`/`reportedDateBefore` for when fixtures were reported - Use `layCanStartAfter`/`layCanStartBefore` for loading window dates **Column Parameter:** - Set `columns="all"` to retrieve all available fixture details - Default returns essential fixture information ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Get recent crude oil fixtures reported this week? ```python commodityType="liquids" size=10000 reportedDateAfter="2025-08-01" reportedDateBefore="2025-08-13" products="Crude" columns="all" ``` - Find all VLCC fixtures from Middle East to Asia in the past month? ```python commodityType="liquids" size=10000 vesselTypesOil=["VLCC"] fromZones="Middle East" toZones="Asia" reportedDateAfter="2025-07-13" reportedDateBefore="2025-08-13" ``` ## Output Format A CSV formatted list of fixtures with the following columns: - Reported date - Vessel - IMO - Quantity (t) - Deadweight (t) - Family - Group - Product - Charterer - Vessel owner - Laycan start - Laycan end - Origin - Destination - Rates ($ price) - Status - Vessel Type Cpp - Vessel Type Oil **Example:** ```csv Reported date;Vessel;IMO;Quantity (t);Deadweight (t);Product;Charterer;Vessel owner;Laycan start;Origin;Destination;Rates ($ price);Status;Vessel Type Oil 2025-08-13;Ds Vision;9522178;260000.0;297345;Crude;Petrobras;China Shipping;2025-09-12;Brazil;Cochin;54.0;Fully Fixed;VLCC 2025-08-13;Yuan Hua Hu;9723588;260000.0;308603;Crude;UNIPEC;COSCO Group;2025-09-10;Western Africa;China;;Fully Fixed;VLCC ``` ## Technical Notes - Fixture status indicates progression: On Subs → Fully Fixed → other statuses - Laycan (Lay/Cancelling) dates define the loading window period - Rates show freight pricing when available in fixtures database - Supports filtering by vessel deadweight range, charterers, and fixture status

kpler_get_freight_fixtures

# Freight Metrics Series Alt Retrieves an alternative time series of freight metrics, providing alternative calculation methods or data sources for comprehensive freight analysis including ton-miles calculations. ## Key Use Cases - **Alternative Freight Analysis**: Access freight metrics using different calculation methods for cross-validation - **Ton-Miles Computation**: Calculate ton-miles over specific paths for efficiency analysis - **Comprehensive Market Analysis**: Compare alternative freight indicators with standard metrics - **Historical Trend Validation**: Use alternative data sources to validate freight market trends ## Usage Guidance ### Input Parameters Guidelines & Caveats **Required Parameters:** - `commodityType`: Must specify commodity type (liquids, dry, lng, lpg) - `metric`: Required metric type (AvgSpeed, AvgDistance, TonMiles, TonDays, Count) **Metric Types:** - `AvgSpeed`: Average vessel speed in knots - `AvgDistance`: Average distance traveled in nautical miles - `TonMiles`: Ton-miles calculation for cargo transport efficiency - `TonDays`: Ton-days measurement for cargo duration analysis - `Count`: Number of vessel movements or operations ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Track monthly average vessel speeds globally? ```python commodityType="liquids" metric="AvgSpeed" split="total" startDate="2025-01-01" endDate="2025-08-13" period="monthly" ``` - Analyze quarterly ton-miles efficiency by route? ```python commodityType="liquids" metric="TonMiles" split="originCountry" fromLocations=["Middle East"] toLocations=["China"] startDate="2024-01-01" endDate="2024-12-31" period="quarterly" ``` ## Output Format A CSV formatted time series with: - Date (period start) - Split dimension columns (if applicable) - Metric values based on selected measurement type **Example:** ```csv Date;Total 2025-08;6.53 ``` Units vary by metric: - AvgSpeed: knots - AvgDistance: nautical miles - TonMiles: ton-miles - TonDays: ton-days - Count: number of movements ## Technical Notes - Supports vessel status filtering (loaded, ballast, all) - Can filter by vessel types, speed ranges, and geographic routes - Period aggregation: monthly, quarterly, annually - Includes ton-miles and ton-days calculations for efficiency analysis

kpler_get_freight_metrics_series_alt

# Freight Metrics Vessels Alt Retrieves a list of vessels with alternative freight metrics data, providing different calculation methods for vessel-level freight analysis including ton-miles computations. ## Key Use Cases - **Alternative Vessel Freight Analysis**: Access vessel-level freight metrics using different calculation methods - **Vessel Performance Validation**: Cross-validate vessel freight performance using alternative data sources - **Ton-Miles Computation**: Calculate ton-miles for specific vessels over given paths - **Comprehensive Vessel Assessment**: Combine alternative and standard metrics for thorough vessel analysis ## Usage Guidance ### Input Parameters Guidelines & Caveats **Required Parameters:** - `commodityType`: Must specify commodity type (liquids, dry, lng, lpg) - `size`: Maximum number of vessels to return (max 1000) **Size Parameter:** - Use **size=1000** (maximum limit) when you want all available data - Use smaller values only if you need to limit results for performance reasons **Columns Parameter** You can use the `columns` parameter to limit the output and focus on specific data fields. This dramatically reduces response size and focuses on specific data fields essential for your analysis. - **Set `columns="all"` only if you need comprehensive data** ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Get freight metrics for VLCC vessels from Middle East to China? ```python commodityType="liquids" size=1000 startDate="2025-08-01" endDate="2025-08-13" fromLocations=["Middle East"] toLocations=["China"] vesselTypesOil=["VLCC"] ``` - Analyze alternative freight performance for product tankers globally? ```python commodityType="liquids" size=1000 vesselTypesCpp=["MR", "LR1", "LR2"] startDate="2025-08-01" endDate="2025-08-13" avgSpeedMin=10.0 avgSpeedMax=15.0 ``` ## Output Format A CSV formatted list with detailed vessel freight metrics: - Date, IMO, Name, Dead Weight Tonnage, Vessel Type - Speed metrics (Average Speed Loaded/Ballast/Total in knots) - Distance metrics (Distance Loaded/Ballast/Total in nautical miles) - Duration metrics (Duration Loaded/Ballast/Total in days) - Efficiency metrics (Ton-Miles, Ton-Days) **Example:** ```csv Date (timestamp);IMO;Name;Dead Weight Tonnage;Vessel Type;Average Speed Total (kn);Distance Total (nmi);Duration Total (days);Ton-Miles (tm);Ton-Days (td) 2025-08;9762998;Advantage Verity;299998;VLCC;11.64;1456.8;5.21;168947971.32;604699.96 ``` ## Technical Notes - Includes ton-miles and ton-days calculations for efficiency analysis - Supports filtering by average speed ranges (avgSpeedMin/Max) - Can filter by vessel status (loaded, ballast, all) - Provides detailed breakdown of loaded vs ballast performance metrics

kpler_get_freight_metrics_vessels_alt

Retrieves available search filter values for Kpler Insights content. Use this tool to discover valid filter values before searching for short contents or reports. ## Key Use Cases - **Discover Commodity Tags**: Get all available commodity categories (e.g. 'Liquids', 'LNG/Gas + Thermal Coal/Power', 'Dry Bulks'). - **Discover Hashtags**: Get all thematic/topic tags that can be used for filtering (e.g. 'energy', 'trading', 'forecast'). - **Discover Geography Tags**: Get all geographic region tags (e.g. 'USA', 'Europe', 'Asia', 'Middle East'). - **Discover Report Types**: Get all available report series types (e.g. 'crude-oil-weekly', 'lng-monthly'). ## Usage Guidance - **filterType** is required and must be one of: - `commodity_tags` — returns commodity categories for use with the `commodityTags` filter - `hashtags` — returns thematic tags for use with the `hashtags` filter - `geography_tags` — returns geographic regions for use with the `geographyTags` filter - `report_types` — returns report series types for use with the `reportType` filter ## Output Format Returns a JSON object with a single array field containing the available filter values: | filterType | Response field | Content | |------------------|-----------------|------------------------------| | commodity_tags | commodityTags | List of commodity tag labels | | hashtags | hashtags | List of hashtag strings | | geography_tags | geographyTags | List of geography tag labels | | report_types | reportTypes | List of report type names | ## Usage with other tools - Call this tool first to discover valid filter values, then use those values with `kpler_get_short_contents` or `kpler_get_reports`.

kpler_get_insights_search_filters

# LNG Capacities Serves as an aggregation of the Train Phase endpoint, offering time series view of historical, current and forecast capacities and operational status for global LNG installations. ## Key Use Cases - **Capacity Planning**: Track historical, current and forecast capacities across global LNG installations - **Market Analysis**: Analyze capacity trends affecting global LNG supply and demand dynamics - **Infrastructure Development**: Monitor capacity expansion and operational status changes - **Long-term Forecasting**: Access capacity forecasts up to 10 years for strategic planning ## Usage Guidance ### Input Parameters Guidelines & Caveats **Split Parameter:** - You can perform 1 split at a time - Split options include: Continent, Sub-Continent, Country, Installation, and Train or Phase - For more granularity, use the Train Phase endpoint **Date Range Parameter:** - Historical limit: 1 January 1969 - Forecast limit: 10 years from current month ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Coverage Provides comprehensive details for: - LNG liquefaction (export) installations - LNG regasification (import) installations - Historical, current and forecast data - Operational status information - Time series by month, quarter or year ## Examples - Track US LNG export capacity by installation over first quarter 2025 ```python installationType="export" granularity="monthly" startDate="2025-01-01" endDate="2025-03-31" zones=["United States"] splits=["installations"] ``` - Monitor Japan LNG import capacity yearly trend ```python installationType="import" granularity="yearly" startDate="2024-01-01" endDate="2024-12-31" zones=["Japan"] splits=["countries"] ``` ## Output Format A JSON response containing time-series capacity data with the following fields: **Time Series Structure:** - `date`: Period start date (YYYY-MM-DD) - `split`: Array containing capacity data for the specified split level **Capacity Data Fields:** - `nominalCapacity`: Nominal annual capacity in metric tons - `unit`: Unit of measurement (typically "mt" for metric tons) - `installationType`: Type of installation ("export" or "import") - `status`: Operational status ("active", "approved", "under construction", etc.) **For installation-level splits, additional fields:** - `installationName`: Name of the LNG installation **For country-level splits, additional fields:** - `country`: Country name where installations are located

kpler_get_lng_capacities

# Diversions Allows you to extract a list of historical and current diversions for all LNG vessels, providing insights into route changes and market dynamics. ## Key Use Cases - **Market Analysis**: Track vessel route changes to understand supply-demand imbalances - **Trade Flow Monitoring**: Identify disruptions and redirections in LNG trade flows - **Historical Tracking**: Analyze past diversions to identify seasonal patterns - **Real-time Monitoring**: Monitor current vessel diversions for immediate market insights ## Usage Guidance ### Input Parameters Guidelines & Caveats **Size Parameter** - Use **size=10000** when you want all available data - Use smaller values only if you need to limit results for performance reasons - **IMPORTANT**: If the number of results equals exactly the size parameter, **always increase it** to check if you missed some data ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Which LNG vessels have been diverted to China over the past three months, and what were their original destinations? ```python destinationZones = ["China"] startDate = "2025-05-13" endDate = "2025-08-13" size = 10000 ``` - How many loaded LNG vessels were diverted from Japan during this year's winter heating season, and to which destinations were they redirected? ```python cancelledZones = ["Japan"] vesselState = ["loaded"] startDate = "2024-12-01" endDate = "2025-02-28" size = 10000 ``` ## Output Format Returns an array of all diversions in the time period with the following information: | Field | Description | | -------------- | ----------------------------------------------------- | | date | When the diversion occurred | | vessel | Vessel name | | imo | Vessel IMO number (unique identifier) | | vesselType | Type of vessel (e.g., XL, L (Lower Conventional)) | | charterer | Company that chartered the vessel | | origin | Where the cargo was loaded (country and installation) | | divertedFrom | Original destination that was canceled | | newDestination | Where the vessel was redirected to | | cargo | Quantity of cargo in tons and cubic meters | | voyageId | Unique identifier for the voyage |

kpler_get_lng_diversions

# Installations Retrieves the list of LNG installations with detailed technical and operational information based on various filtering parameters. ## Key Use Cases - **Installation Discovery**: Find LNG installations across different regions and countries - **Technical Specifications**: Access detailed capacity, storage, and operational data for LNG facilities - **Market Analysis**: Analyze LNG infrastructure distribution and capabilities globally - **Operational Intelligence**: Access information about operators, owners, and facility status ## Usage Guidance ### Input Parameters Guidelines & Caveats **Filtering Options:** - Filter by geographical hierarchy: continent, country, port - Filter by installation type (Import or Export) - Filter by operator or owner names - Use installation IDs for specific facility lookup ## Examples - Find all LNG export terminals in the United States: ```python country="United States" type="Export" ``` - Get installation details for a specific port: ```python port="Sabine Pass" ``` - Find US installations operated by a specific company: ```python country="United States" operator="Cheniere Energy" ``` ## Output Format A CSV formatted list of installations with comprehensive details: | Column | Description | | ------------------------------ | ----------------------------------------------------- | | Continent | Continental location | | Country | Country location | | Port | Port/terminal location | | Installation | Specific installation name | | Installation Type | Import (regasification) or Export (liquefaction) | | Status | Operational status (Active, Under Construction, etc.) | | Operator | Operating company | | Owners | Ownership structure | | LNG Storage Capacity (cbm) | Storage tank capacity in cubic meters | | Nominal Annual Capacity (Mtpa) | Processing capacity in million tons per annum | | Number Trains | Count of liquefaction/regasification trains | | Number Tanks | Count of storage tanks | | Start Year | Year of first operation | | Installation Id | Unique Kpler identifier | ## Technical Notes - Contains global LNG infrastructure database - Covers both liquefaction and regasification facilities - Includes operational and planned installations - Installation IDs can be used with other LNG-related tools for detailed analysis

kpler_get_lng_installations

# LNG Inventories Leverages multiple data sources including Kpler flow data to provide comprehensive time-series view of historical and forecasted LNG inventory storage across global installations. ## Key Use Cases - **LNG Inventory Tracking**: Monitor historical and forecasted inventory levels across global LNG installations - **Market Analysis**: Analyze LNG inventory trends affecting global LNG markets and pricing - **Import/Export Monitoring**: Track inventory levels at both regasification (import) and liquefaction (export) installations - **Forecasting Analysis**: Access short-term inventory forecasts for planning and analysis ## Usage Guidance ### Input Parameters Guidelines & Caveats **Split Parameter:** - Supports multiple split applications based on parameters such as Installation, Country, and more - NEVER MIX `totals` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Date Field Structure **Dates included in the response:** - **date**: The first day of the period, serves as immutable reference for each group of splits and should be used as the primary key when storing data or joining with other endpoints - For granularity=daily: Each calendar day - For granularity=weekly: The Monday of each week - For granularity=monthly: The first day of the month - For granularity=yearly: The first day of the year - **valueDate**: The date when the metrics were measured - **lastImage**: The date of the last satellite or source image used to measure or infer the metrics ## Examples - Track US LNG storage inventories over past quarter ```python granularity="monthly" startDate="2024-01-01" endDate="2024-03-31" zones=["United States"] splits=["totals"] unit="kwh" ``` - Monitor LNG inventory levels at specific installations with weekly granularity ```python granularity="weekly" startDate="2025-08-01" endDate="2025-08-07" zones=["Singapore"] splits=["installations"] unit="tj" ``` ## Output Format A JSON response containing time-series inventory data with the following fields: **Time Series Structure:** - `date`: Period start date (YYYY-MM-DD) - primary key for data grouping - `split`: Array containing inventory data for the specified split level **Inventory Data Fields:** - `storageVolume`: Current volume of stored LNG in the specified unit - `storageCapacity`: Maximum storage capacity in the specified unit - `capacityUtilization`: Ratio of current storage to total capacity (0.0-1.0) - `storageHeel`: Minimum operational storage level maintained - `cargoImport`: Volume of LNG imported during the period - `cargoExport`: Volume of LNG exported during the period - `gasSend-in`: Gas volume sent into storage - `gasSend-out`: Gas volume sent out from storage - `valueDate`: Date when the metrics were measured (YYYY-MM-DD) - `unit`: Unit of measurement (e.g., "kwh", "tj", "m3") **Additional Date Fields:** - `lastImage`: Date of last satellite or source image used for measurement ## Technical Notes - Uses multiple data sources including Kpler flow data - Historical limit: January 1, 2017 - Forecast limit: Up to 2 weeks

kpler_get_lng_inventories

# LNG Outages Provides comprehensive details about outages and operational disruptions at global LNG liquefaction (export) and regasification (import) installations. ## Key Use Cases - **LNG Infrastructure Monitoring**: Track outages at LNG liquefaction and regasification installations globally - **Market Impact Analysis**: Assess how LNG facility outages affect global LNG supply and demand - **Operational Planning**: Plan LNG operations and logistics around known facility outages - **Supply Chain Risk Management**: Monitor infrastructure risks affecting LNG supply chains ## Usage Guidance ### Input Parameters Guidelines & Caveats **Outage Type Options:** - planned, unplanned, any kind, dismissed, observed_reduction - Use to filter by the nature of the operational disruption **Status Filtering:** - Available status values: cancelled, postponed, extended, brought forward, reduced - Track changes to initially reported outage schedules ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### LNG Installation Coverage Provides information on both: - LNG liquefaction (export) installations - LNG regasification (import) installations ## Examples - Check for US LNG facility outages in August 2025 ```python startDate="2025-08-01" endDate="2025-08-31" zones=["United States"] ``` - Monitor unplanned outages in Australia LNG facilities ```python startDate="2025-07-01" endDate="2025-08-31" zones=["Australia"] outageType=["unplanned"] ``` ## Output Format A JSON array containing outage records with the following fields: **Core Information:** - `product`: Product details including ID and name (typically "LNG") - `installation`: Installation details including ID and name - `port`: Port details including ID and name - `location`: Location hierarchy (continent, subcontinent, country) **Outage Details:** - `outage.type`: Type of outage ("planned" or "unplanned") - `outage.status`: Current status of the outage (may be null) - `outage.startDate`: Start date of the outage (YYYY-MM-DD) - `outage.endDate`: End date of the outage (YYYY-MM-DD) - `outage.comment`: Additional details about the outage and impact - `outage.unavailableCapacity`: Amount of capacity affected by the outage - `outage.unavailableCapacityUnit`: Unit for unavailable capacity (typically "mt") ## Technical Notes - Covers both LNG liquefaction (export) and regasification (import) installations - Outage data includes both planned maintenance and unplanned disruptions - Impact details include capacity affected and operational comments - Historical and forecast outage information available

kpler_get_lng_outages

# LNG Trains Phases Offers the most granular details of installation capacity for each individual train (liquefaction) and phase (regasification) unit, including operational status and timing information. ## Key Use Cases - **Granular Capacity Analysis**: Access detailed capacity information for individual LNG trains and regasification phases - **Operational Status Monitoring**: Track operational status of specific LNG infrastructure units - **Project Timeline Tracking**: Monitor start-up and end dates for individual trains and phases - **Infrastructure Development Analysis**: Analyze LNG facility expansion and development projects ## Usage Guidance ### Input Parameters Guidelines & Caveats **Installation Type Required:** - Must specify `installationType` as either "export" (liquefaction) or "import" (regasification) **Status Filtering:** - Available status values: active, approved, planned and proposed, under construction, decommissioned, speculative, suspended, mothballed - Filter by multiple status values to focus on specific operational states ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Granular Detail Coverage Provides most granular details including: - Individual train (liquefaction) capacity details - Individual phase (regasification) capacity information - Operational status for each unit - Start-up and end date information - Individual unit specifications ## Examples - Get individual train details for US LNG export facilities ```python installationType="export" startDate="2025-01-01" endDate="2025-03-31" zones=["United States"] status=["active"] ``` - Monitor specific installation train capacity and timing ```python installationType="import" startDate="2024-01-01" endDate="2024-12-31" installations=["Gate Terminal"] status=["active", "under construction"] ``` ## Output Format A JSON array containing installation records with granular train/phase details: **Installation Information:** - `installation.name`: Name of the LNG installation - `installation.id`: Unique installation identifier - `installation.type`: Type of installation ("export" or "import") - `location`: Geographic hierarchy (continent, subcontinent, country) **Train/Phase Details Array:** - `trainsPhases`: Array of individual units with the following fields: - `name`: Individual train or phase identifier - `status`: Operational status ("active", "under construction", "planned", etc.) - `startDate`: Start date of operations (ISO 8601 format) - `endDate`: End date of operations (null if ongoing) - `quantity.mass`: Capacity in metric tons - `quantity.unit`: Unit of measurement (typically "mt") ## Technical Notes - Provides most granular level of LNG infrastructure detail - Individual train (liquefaction) and phase (regasification) capacity information - Includes operational timeline with start/end dates for each unit - Status tracking for infrastructure development projects - Capacity data in metric tons for precise capacity planning

kpler_get_lng_trains_phases

# LNG Utilizations Trends Harnesses Kpler's proprietary LNG flows and capacity data set to provide real-time view of utilization rates, moving averages, and key statistics on Year To Date (YTD) and Year Over Year (YOY) LNG cargo flows. Data is real-time and covers global LNG liquefaction (export) and regasification (import) installations ## Key Use Cases - **Real-time Utilization Monitoring**: Track current utilization rates across LNG installations with real-time data - **Trend Analysis**: Analyze utilization trends using multiple moving averages (14, 30, 90, 180 days) - **Performance Comparison**: Compare Year To Date (YTD) and Year Over Year (YOY) performance metrics - **Market Intelligence**: Access trend indicators and key statistics for LNG market analysis ## Usage Guidance ### Input Parameters Guidelines & Caveats **Split Parameter:** - You can perform 1 split at a time - Split options include: Continent, Sub-Continent, Country, and Installation ### Moving Averages Coverage Provides multiple moving average data points: - 180 days moving average - 90 days moving average - 30 days moving average - 14 days moving average - Trend indicator ### Key Statistics Includes key statistics on: - Year To Date (YTD) LNG cargo flows - Year Over Year (YOY) LNG cargo flows - Real-time utilization rates ## Examples - Get real-time US LNG export utilization trends by country ```python installationType="export" zones=["United States"] splits=["countries"] ``` - Monitor LNG facility utilization trends at installation level ```python installationType="import" zones=["Japan"] splits=["installations"] ``` ## Output Format A JSON response containing real-time utilization trend data: **Response Structure:** - `timestamp`: Current timestamp when data was generated (ISO 8601 format) - `split`: Object containing trend data for the specified split level **Trend Data Fields:** - `nominalCapacity`: Total nominal capacity in metric tons - `trendIndicator`: Current trend direction (e.g., "UptrendShortRun", "Downtrend") - `ytdCargovolume`: Year-to-date cargo volume processed - `utilization14Days`: 14-day moving average utilization rate - `utilization30Days`: 30-day moving average utilization rate - `utilization90Days`: 90-day moving average utilization rate - `utilization180Days`: 180-day moving average utilization rate - `utilizationYoy`: Year-over-year utilization comparison - `utilizationYtd`: Year-to-date utilization rate - `installationType`: Type of installation ("export" or "import") **For country-level splits:** - `country`: Country name **For installation-level splits:** - `installationName`: Installation name ## Technical Notes - Uses Kpler's proprietary LNG flows and capacity data set - Provides real-time data updates - Split granularity: 1 split at a time

kpler_get_lng_utilizations_trends

# LNG Utilizations Harnesses Kpler's proprietary LNG flows and capacity data set to provide time series view of historical to real-time utilization rates for global LNG installations. ## Key Use Cases - **Utilization Monitoring**: Track historical to real-time utilization rates across global LNG installations - **Performance Analysis**: Analyze utilization efficiency at LNG liquefaction and regasification facilities - **Market Efficiency Assessment**: Understand how effectively LNG infrastructure is being utilized - **Operational Benchmarking**: Compare utilization rates across different installations and regions ## Usage Guidance ### Input Parameters Guidelines & Caveats **Split Parameter:** - You can perform 1 split at a time - Split options include: Continent, Sub-Continent, Country, and Installation **Date Range parameter:** - Historical limit: 1 January 2009 - Forecast limit: Month to date ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Data Coverage Provides comprehensive utilization data for: - Global LNG liquefaction (export) installations - Global LNG regasification (import) installations - Historical to real-time utilization rates - Time series by month, quarter or year ## Examples - Track US LNG export facility utilization rates by installation ```python installationType="export" granularity="monthly" startDate="2025-01-01" endDate="2025-03-31" zones=["United States"] splits=["installations"] ``` - Monitor global LNG import utilization trends by country ```python installationType="import" granularity="quarterly" startDate="2024-01-01" endDate="2024-12-31" splits=["countries"] ``` ## Output Format A JSON response containing time-series utilization data with the following fields: **Time Series Structure:** - `date`: Period start date (YYYY-MM-DD) - `split`: Array containing utilization data for the specified split level **Utilization Data Fields:** - `nominalCapacity`: Available capacity for the period in metric tons - `cargoVolume`: Actual cargo volume processed in metric tons - `utilizationRate`: Utilization rate as decimal (e.g., 0.85 = 85%) - `installationType`: Type of installation ("export" or "import") **For installation-level splits, additional fields:** - `installationName`: Name of the LNG installation **For country-level splits, additional fields:** - `country`: Country name where installations are located ## Technical Notes - Uses Kpler's proprietary LNG flows and LNG capacity data set - Historical coverage from 1 January 2009 - Real-time data updates available - Split granularity: 1 split at a time

kpler_get_lng_utilizations

# Next Destination Returns a vessel's next known destination along with the ETA, remaining sailing distance, and projected route, computed from the vessel's latest position using either AIS-reported or schedule-derived destination data. ## Key Use Cases - **Voyage Tracking**: Answer "where is this vessel headed next and when will it arrive?" - **Fleet Monitoring**: Retrieve next destinations for a list of vessels in a single call - **Remaining Voyage Analysis**: Assess remaining distance, ECA/HRA exposure, and canal crossings still ahead - **Incremental Polling**: Fetch only destination records that changed since a given timestamp ## Usage Guidance ### Input Parameters Guidelines & Caveats **Vessel Identifiers (provide at least one):** - **`vesselUid`**: MarineTraffic vessel unique identifiers (e.g., `["312657"]`) - **`imo`**: Vessel IMO numbers (e.g., `["9312482"]`) - **`mmsi`**: Vessel MMSI numbers (e.g., `["258758000"]`) - Each identifier accepts multiple values; they are sent to the API as a comma-separated list. - Use whichever identifier the user provides. IMO is the most stable identifier; MMSI can change over a vessel's lifetime. **Optional Filter:** - **`updatedSince`**: Return only records updated after this timestamp. Accepts an ISO 8601 timestamp (`YYYY-MM-DDTHH:MM:SSZ`) or a date (`YYYY-MM-DD`, interpreted as `00:00:00Z`). Useful for incremental polling. ### Important Notes - The `eta` is Kpler-estimated and may differ from the ETA the vessel broadcasts over AIS. - The `source` field indicates whether the destination is `ais` (reported by the vessel) or `schedule` (derived from scheduling data). - A vessel with no known next destination will not appear in the response. ## Examples - Where is a vessel headed next, by IMO: ```python imo=["9312482"] ``` - Next destinations for several vessels at once, by MMSI: ```python mmsi=["258758000", "419000636"] ``` - Records updated since the start of April 2026 for a given vessel: ```python imo=["9312482"] updatedSince="2026-04-01" ``` ## Output Format The response is a list of records, one per vessel with a known next destination: - **`vesselUid`**, **`imo`**, **`mmsi`**, **`vesselName`**: Vessel identifiers and name - **`destinationId`**, **`destinationName`**, **`destinationUnlocode`**, **`destinationCountry`**: Destination zone identification - **`eta`**: Kpler-estimated time of arrival (ISO 8601, UTC) - **`distance`**: Remaining sailing distance to the destination (nautical miles) - **`distanceEca`**: Remaining distance within Emission Control Areas (nautical miles) - **`distanceHra`**: Remaining distance within High Risk Areas (nautical miles) - **`canalCrossing`**: Canals expected to be crossed along the remaining route (e.g., `PANAMA`, `SUEZ`) - **`route`**: Projected route geometry to the destination as a WKT LINESTRING - **`source`**: Destination data source (`ais` or `schedule`) - **`updatedAt`**: Record last updated timestamp (ISO 8601, UTC) **Example output:** ```json [ { "vesselUid": 312657, "imo": 9312482, "mmsi": 258758000, "vesselName": "HOEGH SHANGHAI", "destinationId": 656, "destinationName": "JACKSONVILLE", "destinationUnlocode": "USJAX", "destinationCountry": "US", "route": "LINESTRING (-79.5302 8.8457, -81.52 30.3754)", "distance": 1556, "distanceEca": 202, "distanceHra": 0, "canalCrossing": ["PANAMA"], "eta": "2026-03-14T14:03:54Z", "source": "ais", "updatedAt": "2026-03-10T12:00:51Z" } ] ``` ## Integration with Other Tools - Use **vessel_position** to confirm a vessel's current location before assessing its next destination - Combine with **route_emissions** to estimate emissions for the remaining voyage

kpler_get_next_destination

# Port Calls The **Port Calls** query returns the **cargo-by-cargo details** for loadings/discharges taking place in a **point of interest** (installation/zone). Historical data goes back to **2013**. Each terminal, port, and zone is precisely defined by Kpler. A port call is automatically generated when a vessel enters a designated area based on **AIS (Automatic Identification System)** signals. > In order to select specific columns to display, please use the **column IDs** explicited in the example called **“Columns id, name, description and deprecation status.”** --- ## 🔍 Key Use Cases - **Port Activity Monitoring** — Track cargo load/discharge operations by installation or zone - **Cargo Flow Analysis** — Understand trade patterns and product movements at terminals - **Canal & Transit Detection** — Identify vessel crossings and operational events - **Forecasting & Planning** — Combine historical and forecasted data for logistics insight --- ## ⚙️ Parameter Usage Notes **Size** - Use `size=10000` to retrieve all available port calls. - If results equal your `size` limit, **increase it** (more data may be available). **Dates** - `startDate` and `endDate` define the query window. - Resolve relative periods (“this week”, “last month”) to calendar dates. - Weeks start on **Monday**. - “Last week” → Previous Monday–Sunday - “Next week” → Following Monday–Sunday **Forecast Data** - With `withForecast=true`, results include **predicted port calls** with a **confidence** score. **Columns** - Select fields by their **column IDs** (see “Columns id, name, description and deprecation status”). - Use `columns="all"` to return every available field. --- ## 🧩 Example Usage **1) LNG vessels at Singapore terminals (past week)** zones = ["Singapore"] products = ["LNG"] startDate = "2025-08-06" endDate = "2025-08-13" size = 10000 **2) Crude oil discharges at US Gulf terminals (last week)** zones = ["US Gulf"] products = ["Crude"] startDate = "2025-08-06" endDate = "2025-08-13" size = 10000 --- ## 📤 Output Format The response is a CSV-like or structured JSON dataset. Typical column groups include: - **Timestamps** — `eta`, `start`, `end` - **Vessel Info** — `vessel_name`, `vessel_imo`, `vessel_mmsi`, `vessel_type`, `vessel_capacity_cubic_meters` - **Cargo Details** — `cargo_origin_tons_split_by_product`, `cargo_origin_barrels_split_by_product`, `closest_ancestor_product`, `closest_ancestor_family`, `closest_ancestor_grade` - **Location Info** — `installation_name`, `location_name`, `zone_name`, `country_name`, `continent_name` - **Commercial Data** — `charterer_name`, `confidence`, `is_forecasted` - **Operational Flags** — `is_partial_cargo`, `is_reexport`, `is_sts` --- ## 🚢 Operation Type For each record, the **sign of the volume** determines the operation type: - **Positive** → **Loading** - **Negative** → **Discharge** --- ## 🧾 Technical Notes - Port calls can exist in the **past**, **present**, or **future**. - **Ship-to-Ship (STS)** transfers appear as dual port calls (one loading, one discharging). - Forecasted operations include model-generated predictions with confidence values. - `withEmptyVolume` expands visibility (subscription required). --- **Sample Response (excerpt)** Forecasted;Confidence;Id (portCall);Vessel;Location;Installation;zone;Country;ETA;Start;End;Family;Group;Product;Grade;Volume (m3);Volume (bbl);Cargo (tons);Charterer;Reexport;PartialCargo;Ship to ship;IMO (vessel);MMSI (vessel);Capacity (m3);Cargo type (vessel);Vessel type;Id (vessel);Id (installation);Id (zone);Type (installation);SubContinent;Continent;Storage capacity (installation);Status (installation);Id (voyage);Grade API;Grade Sulfur;Berth Name;Vessel Type Alternative;Forecasted Zones;Forecasted Zones Confidence false;;385214208;Trans Fjord;Le Havre;;Le Havre;France;2026-01-27 00:00;;;Chem/Bio;;;;14166.0;89101;11191;;false;false;false;9956939;352003272;14382;;GP;119108;;2363;;Western Europe;Europe;;;43244417;;;;Product Tanker;; false;;385319880;New Silver;Ulsan;;Ulsan;South Korea;2026-01-24 00:00;;;Chem/Bio;Chemicals;Aromatics;Styrene;-12883.0;-81031;-11710;;false;false;false;9346043;440622000;13079;;GP;77218;;2527;;Eastern Asia;Asia;;;43202337;;;;Product Tanker;; …

kpler_get_port_calls_v1

# Products Tool Retrieves an alphabetically sorted list of all commodity or energy products supported by the Kpler APIs. ## Key Use Cases - **Product Discovery**: Find all available commodity and energy products when Resource is unavailable - **Fallback Access**: Alternative access to product list when products Resource is not accessible - **Query Validation**: Verify valid product names for API queries as backup method - **Legacy Support**: Support for environments where Resource access is limited - **Commodity tree exploration**: Check the Kpler Commodity tree to understand its hierarchy ## Usage Guidance The full list of products can be large. If possible, try to specify the needed columns in the request filters ## Output Format A csv list of the matching products with the requested columns **Example:** ```csv Id (Product);Name;Type (Product);Family;Family Id;Group;Group Id;Product;Product Id;Grade;Grade Id;Density (Product);Density Unit;Energy Density;Energy Density Unit;Expansion Ratio 2951;Itapu;grade;Dirty;1398;Crude/Co;1370;Crude;1368;Itapu;2951;882.0;kg/cm;26948.236;MJ/cm;1.0 2952;CPC Russia;grade;Dirty;1398;Crude/Co;1370;Crude;1368;CPC Russia;2952;805.0;kg/cm;26948.236;MJ/cm;1.0 2953;CPC Kazakhstan;grade;Dirty;1398;Crude/Co;1370;Crude;1368;CPC Kazakhstan;2953;805.0;kg/cm;26948.236;MJ/cm;1.0 ```

kpler_get_products

# Refineries Crude Co Imports Retrieves feedstock import data for crude oil and condensate available to refineries via seaborne imports, using moving averages and dispatch strategies for accurate allocation. ## Key Use Cases - **Feedstock Availability Analysis**: Track crude oil and condensate imports available to specific refineries - **Supply Chain Monitoring**: Analyze seaborne imports feeding refinery operations - **Refinery Input Analysis**: Understand feedstock distribution across refinery networks - **Market Supply Assessment**: Monitor crude oil and condensate availability for refinery operations ## Usage Guidance ### Input Parameters Guidelines & Caveats **Product Type Options:** - crude-co: Includes both crude oil and condensate - other-feedstock: Encompasses Straight Run Fuel Oil (SRFO), Vacuum Gasoil (VGO), and High Sulfur Fuel Oil (HSFO) **Allocation Strategy:** - Applies 30-day moving average to smooth data and align with refinery capacities - Uses dispatch strategy for feedstock distribution from terminals to refineries - When multiple refineries connect to single terminal, distribution is calibrated by available processing unit capacities - Crude/Co allocation based on available capacities of Primary Distillation Units ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Split Capabilities Empowers users to perform multiple splits based on various parameters including crude grades, countries, refineries and more. ## Examples - Track crude oil and condensate imports to US Gulf Coast (PADD 3) refineries over the last quarter: ```python granularity="monthly" zones=["PADD 3"] startDate="2025-05-01" endDate="2025-08-01" splits=["countries", "refineries"] unit="kbd" ``` - Analyze feedstock imports by crude grade for European refineries: ```python granularity="weekly" zones=["Europe"] startDate="2025-08-01" endDate="2025-08-13" splits=["crude grades", "refineries"] crudeGrades=["Brent", "WTI", "Forties"] unit="kbd" ``` ## Output Format A CSV formatted time series dataset containing: - **Date**: Period start date based on selected granularity - **Feedstock Quantities**: Import volumes in selected unit (kbd, kb, Mbbl, m3) - **Split Dimensions**: Additional columns based on selected splits (countries, refineries, crude grades, etc.) - **Allocation Data**: Quantities distributed to refineries using dispatch strategy Example structure: ``` Date,Total,Country,Refinery 2025-08-01,1500.5,United States,Motiva Port Arthur 2025-08-01,850.2,United States,ExxonMobil Baytown ``` ## Technical Notes - Uses 30-day moving average to smooth data - Employs dispatch strategy for feedstock distribution - Ensures balanced feedstock availability across pipeline network refineries

kpler_get_refineries_crude_co_imports

# Refineries Margins Returns the gross margins of selected refineries, calculated as the sum of refined product price × quantity produced, minus feedstock and freight costs, and excluding operating expenses such as power generation, hydrogen, maintenance, catalysts etc. ## Key Use Cases - **Refinery Profitability Analysis**: Track gross margins to assess refinery economic performance - **Market Margin Monitoring**: Monitor margin trends across different refineries and regions - **Investment Analysis**: Evaluate refinery investment opportunities based on margin performance - **Comparative Analysis**: Compare margins across different refinery types and locations ## Usage Guidance ### Input Parameters Guidelines & Caveats **Split Options:** - Available splits: total, refinery types, refineries, countries, subcontinents, continents, trading regions - Use "refineries" split to get individual refinery details with installation information - NEVER MIX `total` with other split values **Date Range:** - Historical data available from 2017-01-01 - Default date range is one year ago to +7 days from today ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Filtering Capabilities Empowers users to search for specific refineries based on various parameters. These filters accept a list of strings. - **zones**: A list of zone names (e.g. `["OECD", "Africa"]`) - **installations**: A list of installation names (e.g. `["Qingdao", "Sabine Pass"]`) - **players**: A list of player names (e.g. `["ExxonMobil", "Shell"]`) ### Split Capabilities Empowers users to perform multiple splits based on various parameters including countries, refineries, refinery types and more. ## Examples - What were the average refinery margins globally in the last month? ```python granularity = "monthly" splits = ["total"] startDate = "2025-07-13" endDate = "2025-08-13" ``` - Which countries had the highest refinery margins in Q2 2025? ```python granularity = "monthly" splits = ["countries"] startDate = "2025-04-01" endDate = "2025-06-30" ``` ## Output Format Returns time series data of refinery margins with the following structure: | Field | Description | | ------ | ---------------------------------------------------------------------------------- | | Date | The date for which the margin data is reported (based on specified granularity) | | Splits | Array of margins value and unit for each split combination (country, continent...) | When splitting by `refineries`, the installation information is also provided. Example for a split by trading regions: ``` [ { "Date": "2025-07-01", "Splits": [ {"Trading Region": "Caspian Sea Russia", "Margins":42.09, "Unit": "$/bbl"}, {"Trading Region": "East Coast Canada", "Margins":22.48, "Unit": "$/bbl"} ... }, ... ] ``` ## Technical Notes - Margins reported in $/bbl (dollars per barrel) - Data calculated using Kpler's proprietary refinery models - Includes both simple and complex refineries globally

kpler_get_refineries_margins

# Refineries Particulars Returns a list of refineries along with their respective particulars including owner, age, nelson complexity index, operational status, and startup/shutdown dates. ## Key Use Cases - **Refinery Database Access**: Access comprehensive refinery information and specifications - **Asset Intelligence**: Understand refinery ownership, age, and technical characteristics - **Operational Status Monitoring**: Track refinery operational status and lifecycle events - **Market Analysis**: Analyze refinery characteristics for market and investment insights ## Usage Guidance ### Input Parameters Guidelines & Caveats ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - What are all refineries owned by Chevron worldwide? ```python players=["Chevron Corporation"] ``` - Find complex refineries in the United States with high Nelson Complexity Index (NCI) ```python zones = ["United States"] ``` ## Output Format Returns an array of refinery information with the following details: | Field | Description | | --------------- | ----------------------------------------------------------------------------------------------- | | Installation | Name of the refinery installation/facility | | Installation id | Unique identifier for the installation in the Kpler system | | Refinery | Full name of the refinery | | Refinery id | Unique identifier for the refinery in the Kpler system | | Owner | Company that owns the refinery | | Age | Age of the refinery in years (null if unknown) | | Nci | Nelson Complexity Index - a measure of refinery complexity and sophistication (null if unknown) | | Type | Classification of the refinery (Complex, Medium, Simple, or Other) | | Status | Operational status (Operational, Closed, etc.) | | State | State/province where the refinery is located (null for non-US locations) | | Country | Country where the refinery is located | | Startup | Year when the refinery first became operational (integer, null if unknown) | | Shutdown | Year when the refinery was shut down or decommissioned (integer, null if still operational) | | Owner share | Map of owner → ownership share for the refinery (null if unknown) |

kpler_get_refineries_particulars

# Refineries Primary Distillation Retrieves operational run data of Primary Distillation Units including Crude Distillation Units (CDU) and Condensate Splitters for selected refineries. ## Key Use Cases - **Primary Processing Monitoring**: Track operational run data for crude distillation and condensate splitting units - **Refinery Throughput Analysis**: Analyze primary distillation capacity utilization and performance - **Feedstock Processing Assessment**: Monitor how refineries process crude oil and condensate inputs - **Operational Efficiency Analysis**: Evaluate primary distillation unit performance across different refineries ## Usage Guidance ### Input Parameters Guidelines & Caveats **Unit Coverage:** - Primary Distillation includes both Crude Distillation Unit (CDU) and Condensate Splitter - Secondary Units encompass Reformer, Distillate Hydrocracker, Fluid Catalytic Cracking (FCC) unit, and Coker **Split Restrictions:** - DO NOT USE "players" for the `splits` parameter - IT IS NOT A VALID VALUE FOR `splits` - DO NOT MIX `total` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Split Capabilities Empowers users to perform multiple splits based on various parameters including crude grades, countries, refineries and more. ## Examples - Track primary distillation runs at US refineries by crude quality: ```python granularity="weekly" zones=["United States"] startDate="2025-07-01" endDate="2025-08-13" splits=["crude qualities", "refineries"] unit="kbd" ``` - Analyze crude grade processing at European refineries: ```python granularity="daily" zones=["Europe"] startDate="2025-08-01" endDate="2025-08-13" splits=["crude grades", "countries"] crudeGrades=["Brent", "Forties", "Ekofisk"] unit="kbd" ``` ## Output Format A CSV formatted time series dataset showing primary distillation operational runs: - **Date**: Period start date based on selected granularity - **Processing Volumes**: Crude distillation runs in selected unit (kbd, kb, Mbbl, m3) - **Split Dimensions**: Additional columns based on selected splits (crude qualities, grades, refineries, countries, etc.) - **Unit Data**: Primary distillation unit operational data Example structure: ``` Date,Total,Crude Quality,Refinery 2025-08-01,2500.8,Light Sweet,Marathon Petroleum Texas City 2025-08-01,1850.3,Heavy Sour,ExxonMobil Baytown ``` ## Technical Notes - Focuses on Primary Distillation Units (CDU and Condensate Splitter) - Provides operational run data for selected refineries - Supports analysis by crude grades, countries, and refineries

kpler_get_refineries_primary_distillation

# Refineries Utilization Rates Returns the available utilization rate for chosen unit types of selected refineries, calculated as unit runs divided by available capacity. ## Key Use Cases - **Operational Efficiency Monitoring**: Track utilization rates to assess refinery operational efficiency - **Capacity Analysis**: Analyze how effectively refineries utilize their available processing capacity - **Performance Benchmarking**: Compare utilization rates across different refineries and regions - **Market Capacity Assessment**: Understand refinery capacity utilization trends affecting market supply ## Usage Guidance ### Input Parameters Guidelines & Caveats **Calculation Method:** - Utilization rate formulated as unit runs/available capacity - Applies to chosen unit type of selected refineries **Split Restrictions:** - DO NOT USE "players" for the `splits` parameter - IT IS NOT A VALID VALUE FOR `splits` - DO NOT MIX `total` with other split values ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ### Split Capabilities Empowers users to perform multiple splits based on various parameters including trading regions, countries, refineries and more. ## Examples - Monitor primary distillation utilization rates across US Gulf Coast refineries: ```python granularity="monthly" unitType="Primary Distillation" zones=["US Gulf"] startDate="2025-01-01" endDate="2025-08-13" splits=["refineries"] ``` - Compare FCC unit utilization rates by refinery type in Europe: ```python granularity="weekly" unitType="FCC" zones=["Europe"] startDate="2025-08-01" endDate="2025-08-13" splits=["refinery types", "countries"] ``` ## Output Format A CSV formatted time series dataset showing utilization rates: - **Date**: Period start date based on selected granularity - **Utilization Rate**: Unit runs divided by available capacity (as percentage or ratio) - **Split Dimensions**: Additional columns based on selected splits (refineries, countries, refinery types, etc.) - **Unit Type**: Specific processing unit being analyzed Example structure: ``` Date,Total,Refinery Type,Country 2025-08-01,85.2,Complex,United States 2025-08-01,78.5,Simple,United States ``` ## Technical Notes - Calculated as unit runs/available capacity - Supports analysis by unit type and refinery selection - Provides utilization efficiency metrics

kpler_get_refineries_utilization_rates

Retrieves a single Kpler Insights report by its URL slug. ## Key Use Cases - **Report Lookup**: Get full details of a specific report identified by its slug. - **Follow-up Reading**: Retrieve the full content of a report found via `kpler_get_reports`. ## Usage Guidance - **slug** is required — the URL slug identifier for the report (e.g. `oil-market-analysis`). - Set **usePlainTextContent** to `true` to get plain text without HTML markup. - **language** defaults to English (`en`). Available translations: Korean (`ko`), Chinese (`zh`), Japanese (`ja`), Arabic (`ar`), French (`fr`), Portuguese-Brazil (`pt-BR`), Spanish (`es`), Russian (`ru`). ## Output Format Returns a single report object with: | Field | Description | |-----------------|------------------------------------------| | id | Unique identifier | | title | Report title | | slug | URL slug | | description | Brief description | | content | Report body and metadata | | commodityTags | Associated commodity tags | | geographyTags | Associated geography tags | | hashtags | Associated hashtags | | typename | Content type | | reportType | Report series type | | frequency | Publication frequency | | publishedAt | Publication date/time | | createdAt | Creation date/time | | updatedAt | Last update date/time | ## Usage with other tools - Use `kpler_get_reports` to search for reports by date range and filters, then use this tool to get the full details of a specific report.

kpler_get_report_by_slug

Retrieves Kpler Insights reports published within a specified date range. ## Key Use Cases - **Research Reports**: Access weekly, monthly, or quarterly analytical reports on commodity markets. - **Commodity-Specific Reports**: Find reports related to specific commodities like Crude Oil, LNG, etc. - **Regional Reports**: Retrieve reports focused on specific geographic areas. - **Report Series Tracking**: Follow a specific report type over time (e.g. 'The Crude View'). ## Usage Guidance - **startDate** and **endDate** are required and define the publication date range (inclusive). - Use **commodityTags**, **geographyTags**, and **hashtags** to narrow results. Call `kpler_get_insights_search_filters` first to discover valid filter values. - **reportType** filters by report series name (e.g. 'The Crude View'). Use `kpler_get_insights_search_filters` with filterType `report_types` to discover valid values. - **frequency** filters by publication frequency: `weekly`, `monthly`, or `quarterly`. - Set **usePlainTextContent** to `true` to get plain text without HTML markup. - **language** defaults to English (`en`). Available translations: Korean (`ko`), Chinese (`zh`), Japanese (`ja`), Arabic (`ar`), French (`fr`), Portuguese-Brazil (`pt-BR`), Spanish (`es`), Russian (`ru`). ## Output Format Returns a JSON object with a `reports` array. Each item includes: | Field | Description | |-----------------|------------------------------------------| | id | Unique identifier | | title | Report title | | slug | URL slug (use with `kpler_get_report_by_slug`) | | description | Brief description | | content | Report body and metadata | | commodityTags | Associated commodity tags | | geographyTags | Associated geography tags | | hashtags | Associated hashtags | | typename | Content type | | reportType | Report series type | | frequency | Publication frequency | | publishedAt | Publication date/time | | createdAt | Creation date/time | | updatedAt | Last update date/time | ## Usage with other tools - Use `kpler_get_insights_search_filters` to discover valid commodity tags, geography tags, hashtags, and report types before filtering. - Use `kpler_get_report_by_slug` to get the full details of a specific report by its slug.

kpler_get_reports

# Routes Estimates optimal maritime routes between origin and destination, returning distance, ETA, canal crossings, and route geometry. ## Key Use Cases - **Voyage Planning**: Calculate optimal routes from a vessel's current position to a destination port - **ETA Estimation**: Determine estimated arrival times based on route distance and vessel speed - **Canal Transit Analysis**: Identify which canals (Suez, Panama, Kiel) a route will cross - **Emissions Zone Analysis**: Calculate distance spent in Emission Control Areas (ECA) or High Risk Areas (HRA) ## Usage Guidance ### Input Parameters Guidelines & Caveats **Origin Location (Required):** - **`originType`**: How the origin is specified - `imo`: Vessel IMO number (e.g., 9271248) - `mmsi`: Vessel MMSI number (e.g., 257739000) - `vesselUid`: MarineTraffic vessel ID (e.g., 308459) - `coordinates`: Longitude,latitude format (e.g., "-170.2,10.12345") - `port`: UN/LOCODE (e.g., "USHOU") or MarineTraffic port ID (e.g., 919) - **`originValue`**: The actual value matching the selected type **Destination Location (Required):** - **`destinationType`**: How the destination is specified - `coordinates`: Longitude,latitude format - `port`: UN/LOCODE or MarineTraffic port ID - **`destinationValue`**: The actual value matching the selected type **Optional Parameters:** - **`avoidCanals`**: Canals to strictly avoid: `SUEZ`, `PANAMA`, `KIEL` - **`avoidZones`**: Zones to minimize time in: `ECA` (Emission Control Areas), `HRA` (High Risk Areas) - **`startDate`**: Route start time in ISO 8601 format (e.g., "2025-12-22T00:00:00Z"). Defaults to current time. - **`speed`**: Vessel speed in knots (e.g., "14" or "12.5"). Defaults to 14 knots. ### Important Notes - When using vessel identifiers (`imo`, `mmsi`, `vesselUid`) as origin, the route starts from the vessel's current position - Zone avoidance (`avoidZones`) is soft - the route minimizes time in these zones but may not avoid them entirely - Canal avoidance (`avoidCanals`) is strict - the route will never pass through specified canals - Port input accepts **maritime ports only** — airport UN/LOCODEs (e.g., `CNSHA` is Shanghai Hongqiao Airport, not Shanghai port) are not supported. - UN/LOCODE coverage is **partial**. If a code is rejected, fall back to `coordinates` (`longitude,latitude`) — any point on water near the location produces a valid route. ## Examples - Calculate route from a vessel to Rotterdam: ```python originType="imo" originValue="9271248" destinationType="port" destinationValue="NLRTM" ``` - Route from Houston to Singapore avoiding Suez Canal: ```python originType="port" originValue="USHOU" destinationType="port" destinationValue="SGSIN" avoidCanals=["SUEZ"] ``` - Route from coordinates to a port with custom speed: ```python originType="coordinates" originValue="-95.27,29.73" destinationType="port" destinationValue="NLRTM" speed="12.5" startDate="2025-06-15T08:00:00Z" ``` - Route minimizing ECA exposure: ```python originType="port" originValue="USHOU" destinationType="port" destinationValue="BEANR" avoidZones=["ECA"] ``` ## Output Format The response includes: - **`distance`**: Total route distance in nautical miles - **`distanceEca`**: Distance within Emission Control Areas (nautical miles) - **`distanceHra`**: Distance within High Risk Areas (nautical miles) - **`canalCrossing`**: List of canals the route crosses (PANAMA, SUEZ, KIEL) - **`startDate`**: Route start time (ISO 8601) - **`endDate`**: Estimated arrival time (ISO 8601) - **`route`**: Route geometry as WKT LINESTRING in WGS84 coordinates **Example output:** ```json { "distance": 2196, "distanceEca": 357, "distanceHra": 0, "canalCrossing": ["PANAMA"], "startDate": "2025-12-11T00:00:00Z", "endDate": "2025-12-18T23:55:59Z", "route": "LINESTRING (-95.27 29.73, -80.72 -0.94, ...)" } ``` ## Technical Notes - Routes are calculated using optimal maritime navigation paths considering navigational constraints - ETA calculation uses the specified speed (default 14 knots) applied uniformly across the route - Canal crossings are detected automatically based on route geometry - The route geometry can be used for visualization or further geospatial analysis ## Integration with Other Tools - Use with **vessel_position** to get current vessel coordinates as origin - Combine with **route_emissions** to estimate emissions for the calculated route - Use **distance_matrix** for bulk distance calculations between multiple port pairs

kpler_get_routes

Retrieves a single Kpler Insights short content (news article or market pulse) by its URL slug. ## Key Use Cases - **Content Lookup**: Get full details of a specific short content item identified by its slug. - **Follow-up Reading**: Retrieve the full content of an item found via `kpler_get_short_contents`. ## Usage Guidance - **slug** is required — the URL slug identifier for the content (e.g. `oil-market-analysis`). - Set **usePlainTextContent** to `true` to get plain text without HTML markup. - **language** defaults to English (`en`). Available translations: Korean (`ko`), Chinese (`zh`), Japanese (`ja`), Arabic (`ar`), French (`fr`), Portuguese-Brazil (`pt-BR`), Spanish (`es`), Russian (`ru`). ## Output Format Returns a single short content object with: | Field | Description | |-----------------|------------------------------------------| | id | Unique identifier | | title | Content title | | slug | URL slug | | description | Brief description | | content | Content body and metadata | | commodityTags | Associated commodity tags | | geographyTags | Associated geography tags | | hashtags | Associated hashtags | | typename | Content type (news/marketPulse) | | publishedAt | Publication date/time | | createdAt | Creation date/time | | updatedAt | Last update date/time | ## Usage with other tools - Use `kpler_get_short_contents` to search for short contents by date range and filters, then use this tool to get the full details of a specific item.

kpler_get_short_content_by_slug

Retrieves Kpler Insights short-form content (news articles and market pulses) published within a specified date range. ## Key Use Cases - **Market News**: Get the latest news articles and market pulses about commodities and energy markets. - **Commodity Research**: Find insights related to specific commodities (e.g., Crude Oil, Natural Gas). - **Regional Analysis**: Retrieve content focused on specific geographic areas. - **Topic Exploration**: Search for content by hashtags/topics. ## Usage Guidance - **startDate** and **endDate** are required and define the publication date range (inclusive). - Use **commodityTags**, **geographyTags**, and **hashtags** to narrow results. Call `kpler_get_insights_search_filters` first to discover valid filter values. - **typename** filters by content type: `news` for news articles, `marketPulse` for market pulse updates. - Set **usePlainTextContent** to `true` to get plain text without HTML markup. - **language** defaults to English (`en`). Available translations: Korean (`ko`), Chinese (`zh`), Japanese (`ja`), Arabic (`ar`), French (`fr`), Portuguese-Brazil (`pt-BR`), Spanish (`es`), Russian (`ru`). ## Output Format Returns a JSON object with a `shortContents` array. Each item includes: | Field | Description | |-----------------|------------------------------------------| | id | Unique identifier | | title | Content title | | slug | URL slug (use with `kpler_get_short_content_by_slug`) | | description | Brief description | | content | Content body and metadata | | commodityTags | Associated commodity tags | | geographyTags | Associated geography tags | | hashtags | Associated hashtags | | typename | Content type (news/marketPulse) | | publishedAt | Publication date/time | | createdAt | Creation date/time | | updatedAt | Last update date/time | ## Usage with other tools - Use `kpler_get_insights_search_filters` to discover valid commodity tags, geography tags, hashtags, and report types before filtering. - Use `kpler_get_short_content_by_slug` to get the full details of a specific short content item by its slug.

kpler_get_short_contents

# SOH Crossing Data Retrieves vessel crossing data for the Strait of Hormuz (SoH) from BigQuery. ## Key Use Cases - **Traffic monitoring**: Track vessels crossing the Strait of Hormuz by direction, commodity, and loading state - **Commodity flow analysis**: Filter crossings by commodity type (liquids, LNG, LPG, dry) over a date range ## Usage Guidance ### Parameters - **startDate / endDate**: Limit results to a date range. If omitted, all available data is returned (from late February 2026 onward). - **commodity**: Filter by vessel category. Accepted values: `liquids`, `lng`, `lpg`, `dry`. If omitted, all commodities are returned. ### Caveats - If no filters are provided, the response may exceed the size limit — use `commodity` and/or a date range to narrow results. - Data is refreshed every 2 hours. ## Output Format Returns a list of crossing events (one row per event). Each row includes: - **Vessel**: `vessel_name`, `imo`, `vessel_id`, `dead_weight`, `build_year`, `build_country`, `flag_name` - **Crossing**: `direction` (e.g. `West -> East`), `crossing_date`, `crossing_type`, `loading_state`, `cargo_type` - **Classification**: `vessel_category` (`liquids` / `lng` / `lpg` / `dry`) - **Quantity** (when applicable): `quantity`, `quantity_unit` - **Cargo / ports**: `last_cargo_zone`, `last_cargo_country`, `next_port`, `next_port_country` - **Links and freshness**: `link` (terminal / vessel context in Kpler), `updated_at` (row update time in BigQuery)

kpler_get_soh_crossing

# Supply Demand Retrieves supply and demand data for a given product, providing market fundamentals and balance information. ## Key Use Cases - **Market Fundamentals Analysis**: Access supply and demand data for comprehensive market analysis - **Product Balance Monitoring**: Track supply-demand balance for specific commodities - **Market Intelligence**: Understand market dynamics through supply and demand metrics - **Trading Analysis**: Support trading decisions with fundamental supply-demand data ## Usage Guidance ### Input Parameters Guidelines & Caveats **Metric Selection:** - Use `["supply", "demand", "balance"]` for basic market fundamentals - For Crude/Co product, additional metrics available: `refineryRun`, `directCrudeUse`, `stockChange`, `balancingFactor` - For other products, `otherChanges` metric is available **Split Options:** - `"total"`: Global aggregation - `"country"`: Split data by individual countries when `zones` parameter specified **Date Limitations:** - Historical limit: January 1, 2017 - Forward limit: 18 months from today - Use `snapshotDate` parameter to get data from a specific snapshot ### Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), **always remind what is the current date and explain how you compute the date range** - **Week definition**: Weeks start on Monday by default - **"Last week"** = Previous Monday to Sunday (NOT the last 7 days) - **"Next week"** = Following Monday to Sunday (NOT the next 7 days) ## Examples - Get global crude oil supply and demand balance for July 2025: ```python product="Crude/Co" metrics=["supply", "demand", "balance"] split="total" startDate="2025-07-01" endDate="2025-08-01" ``` - Compare gasoline supply and demand between China and US: ```python product="Gasoline" metrics=["supply", "demand"] split="country" zones=["China", "United States"] startDate="2025-07-01" endDate="2025-08-01" ``` ## Output Format CSV formatted data with columns: - **Snapshot Date**: Date of the data snapshot - **Date**: Period date for the data - **Product**: Product name - **Metric**: Type of metric (supply, demand, balance, etc.) - **Zones**: Geographic zone (World for total split, country names for country split) - **Value**: Numeric value for the metric - **Unit**: Unit of measurement (typically kbd - thousand barrels per day) ## Technical Notes - Snapshot dates indicate when the data was captured/calculated - Balance = Supply - Demand (negative values indicate demand exceeding supply)

kpler_get_supply_demand

# Supply Demand Products Retrieves available products for supply and demand data analysis, providing a list of commodities with available market fundamentals. ## Key Use Cases - **Product Discovery**: Find all products with available supply and demand data - **Market Coverage Assessment**: Understand which commodities have fundamental data available - **Query Planning**: Identify valid product parameters for supply-demand analysis - **Market Scope Analysis**: Assess breadth of available market fundamental data ## Usage Guidance ### Input Parameters Guidelines & Caveats **Usage Instructions:** - This tool does not take any parameters - Returns all available products with their metrics and data coverage periods - Use this tool first to identify valid product names for other supply-demand queries ## Examples - Get all available products for supply-demand analysis: ```python # No parameters required ``` ## Output Format CSV formatted data with columns: - **Product**: Product name (e.g., "Crude/Co", "Gasoline", "LPG") - **Metrics**: Available metrics for the product (supply, demand, balance, etc.) - **Snapshot Start Date**: Earliest available data date - **Snapshot End Date**: Latest available data date **Example output:** ``` Product;Metrics;Snapshot Start Date;Snapshot End Date Crude/Co;supply,demand,refineryRun,directCrudeUse,balance,netExport,stockChange,balancingFactor;2022-06-14;2025-08-12 Gasoline;balance,netExport,supply,demand,otherChanges;2023-10-24;2025-08-06 ``` ## Technical Notes - Product names are case-sensitive and must be used exactly as returned - Different products have different available metrics - Crude/Co has the most comprehensive metric coverage including refinery-specific data - Data availability periods vary by product

kpler_get_supply_demand_products