Kpler

# 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, removals, 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, removals, and active fleet counts - **Industry Growth Analysis**: Understand fleet development patterns and market expansion ## Usage Guidance ### Input Parameters Guidelines & Caveats This is a single, cross-commodity endpoint. You do not select a commodity: tankers, LPG, LNG and dry bulk segments are all covered by one `vesselClassifications` filter. To restrict the result to a segment, pass the relevant vessel classifications (e.g. `VLCC`, `Suezmax/LR3` for large tankers; `VLGC` for LPG; `Q-Flex` for LNG; `Capesize` for dry bulk). **Metric Types:** - `available`: Count active vessels in service at the end of each period - `deliveries`: Track newly built vessels entering service - `orders`: Analyze new vessel orders placed within the period - `removals`: Monitor vessels permanently removed from service (scrapped / demolished) **Aggregation Metric:** - `count`: number of vessels (default) - `deadweight`: summed deadweight tonnage (in tonnes) **Granularity:** `daily`, `weekly` (default), `monthly`, `quarterly`, `yearly`. **Split Guidelines:** - `splitBy` accepts `vesselClassification`, `vesselCoating`, `scrubberType`, `engineType`, `fuelType` - Omit `splitBy` entirely for a single total series (do not mix a total with a split) - Use `numberOfSplits` to cap the number of split buckets (top N + an `Others` bucket) **Projection (deliveries only):** `actual` caps build dates at today; `predictive` also includes future build dates within the requested range. ### 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 quarterly large-tanker deliveries by classification in 2024? ```python metric="deliveries" aggMetric="count" startDate="2024-01-01" endDate="2024-12-31" granularity="quarterly" splitBy="vesselClassification" vesselClassifications=["VLCC", "Suezmax/LR3", "Aframax/LR2"] ``` - Analyze annual fleet deadweight growth for the whole fleet? ```python metric="available" aggMetric="deadweight" startDate="2020-01-01" endDate="2024-12-31" granularity="yearly" ``` ## Output Format A CSV formatted time series dataset. The first column is the period date (in the requested granularity, e.g. `2020-W01`, `2024-Q1`, `2024-01`); the remaining columns are the metric value, one per split value when `splitBy` is set, otherwise a single `Total` column. **Example:** ```csv Date;VLCC;Suezmax/LR3 2024-Q1;30;20 2024-Q2;31;20 ``` ## Technical Notes - Data tracks vessel lifecycle events from ordering through delivery to removal - Aggregation metrics: `count` (number of vessels), `deadweight` (summed tonnage) - History is available from 2017-01-01; future dates are allowed up to 5 years ahead (fleet orders can be placed years ahead of delivery)

kpler_get_fleet_development_series

# Fleet Development Vessels Returns a detailed list of vessels contributing to a selected fleet development metric (e.g., deliveries, removals), with filtering by vessel attributes, classifications, 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 - **Removal Monitoring**: Track vessels being decommissioned or scrapped - **Fleet Composition Analysis**: Understand vessel characteristics affecting fleet development ## Usage Guidance ### Input Parameters Guidelines & Caveats This is a single, cross-commodity endpoint. You do not select a commodity: tankers, LPG, LNG and dry bulk segments are all covered by one `vesselClassifications` filter. To restrict the result to a segment, pass the relevant vessel classifications. **Metric Types:** - `available`: active vessels in service - `deliveries`: newly built vessels entering service - `orders`: vessels newly ordered within the period - `removals`: vessels permanently removed from service (scrapped / demolished) **Pagination:** - `size`: number of vessels to return per page (max 10000, default 40) - `offset`: number of vessels to skip (default 0) **Projection (deliveries only):** `actual` caps build dates at today; `predictive` also includes future build dates within the requested range. The response columns are fixed by the API (there is no column-selection parameter). ### 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 tankers delivered in August 2024? ```python metric="deliveries" startDate="2024-08-01" endDate="2024-08-31" size=10000 ``` - Find VLCC tankers removed (scrapped) in 2024? ```python metric="removals" vesselClassifications=["VLCC"] startDate="2024-01-01" endDate="2024-12-31" size=10000 ``` ## Output Format A CSV formatted string of vessels with the following fixed columns: | Column | Description | | --------------------- | -------------------------------------------------- | | IMO | Vessel IMO number | | Name | Name of the vessel | | Status | Vessel status (e.g. In Service, On Order, Dead) | | Vessel classification | Commercial classification (e.g. VLCC, Suezmax/LR3) | | Dead weight (t) | Deadweight tonnage in tonnes | | Vessel coating | Tank coating type | | Order at | Order date | | Build at | Build / delivery date | | Dead at | Removal / death date | | Scrubber type | Type of exhaust scrubber | | Scrubber date | Date scrubber was installed | | Engine type | Engine type | | Fuel type | Primary fuel type of the main engine | **Example:** ```csv IMO;Name;Status;Vessel classification;Dead weight (t);Vessel coating;Order at;Build at;Dead at;Scrubber type;Scrubber date;Engine type;Fuel type 9123456;Test Vessel;In Service;Small Tankers;150000;Fully Coated;1999-06-01T00:00:00.000Z;2002-06-10T00:00:00.000Z;;Open Loop;2020-01-15T00:00:00.000Z;Diesel Engine;Marine Diesel Oil ``` ## Technical Notes - Data tracks vessel events from order placement through delivery to removal - Supports filtering by vessel classifications, coatings, scrubber types, engine types, fuel types, IMO/vessel IDs and deadweight range

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. **Products Parameter** - `products` is an optional filter; omitting it aggregates **every** commodity. Omit it whenever the user asks about total or unspecified volumes. - Only set it when the user names a commodity. Never infer one from the origin, destination, company or region: a country's trade usually spans many products, and filtering to the one it is best known for silently discards the rest of the volume without any error. - Resolve commodity names with `kpler_get_products` rather than guessing them. **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 - A period in the future can only mean the loading window: a fixture is reported when the deal is struck, so nothing is reported ahead of today. Use `layCanStart*` whenever the question is about vessels fixed or loading for an upcoming period, and `reportedDate*` only when the question is explicitly about when fixtures were reported. **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. 'Geopolitics', 'Sanctions', 'Refining'). - **Discover Geography Tags**: Get all geographic region tags (e.g. 'United States', 'Europe', 'Asia', 'Middle East'). - **Discover Report Types**: Get all available report series types (e.g. 'The Crude View', '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) - **"Last N weeks"** = the N complete weeks before the current week: start on the Monday N weeks before this week's Monday, end on the Sunday immediately before it. The current, partial week is excluded, so the range spans exactly N*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 - **No period given**: when the question names no time period, omit `startDate` and `endDate` entirely and let the API apply its own default. Do not invent a window — a guessed range silently excludes data the user asked about. - **"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 - **No period given**: when the question names no time period, omit `startDate` and `endDate` entirely and let the API apply its own default. Do not invent a window — a guessed range silently excludes data the user asked about. - **"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:** - To break down or compare by operator, pass the company names to the `players` filter and split by `refineries`. The `splits` enum contains only geographic, crude-quality and refinery dimensions, so an operator is never a valid split value. - 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 - To compare companies, pass them to the `players` filter and split by `refineries`. `players` filters which refineries are returned; it is not a split dimension. ### 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 the utilization rates of two companies over the last 6 months: ```python granularity="monthly" players=["TotalEnergies", "Shell"] splits=["refineries"] startDate="2025-02-01" endDate="2025-08-13" ``` - 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`). - Cite content by its **url** — it is the article's page in the Kpler terminal. The **slug** alone is an API identifier and is not a web address. ## 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 | | url | Article page in the Kpler terminal | ## 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. - **commodityTags**, **geographyTags**, **hashtags** and **reportType** match **exact** taxonomy values. Several values in one of them match **any** of those values; two different ones **intersect**. A value outside the taxonomy matches nothing and is not reported as an error — the call succeeds and returns an empty list, indistinguishable from a period with no publications. `frequency` and `language` are closed sets and reject an unknown value outright, so this does not apply to them. - **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`). - Cite content by its **url** — it is the article's page in the Kpler terminal. The **slug** alone is an API identifier and is not a web address. ## 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 | | url | Article page in the Kpler terminal | ## 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`). - Cite content by its **url** — it is the article's page in the Kpler terminal. The **slug** alone is an API identifier and is not a web address. ## 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 | | url | Article page in the Kpler terminal | ## 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. - **commodityTags**, **geographyTags** and **hashtags** match **exact** taxonomy values. Several values in one of them match **any** of those values; two different ones **intersect**. A value outside the taxonomy matches nothing and is not reported as an error — the call succeeds and returns an empty list, indistinguishable from a period with no publications. `typename` and `language` are closed sets and reject an unknown value outright, so this does not apply to them. - **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`). - Cite content by its **url** — it is the article's page in the Kpler terminal. The **slug** alone is an API identifier and is not a web address. ## 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 | | url | Article page in the Kpler terminal | ## 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

# Supply Demand Snapshots Retrieves available snapshot dates for supply and demand data, providing information about data availability periods and update schedules. ## Key Use Cases - **Data Availability Assessment**: Understand available time periods for supply and demand data - **Historical Analysis Planning**: Identify snapshot dates for historical market analysis - **Update Schedule Monitoring**: Track when supply and demand data snapshots are available - **Time Series Analysis**: Plan time-series analysis based on available snapshot dates ## Usage Guidance ### Input Parameters Guidelines & Caveats **Required Parameters:** - `product`: Must be a valid product name from supply_demand_products tool - Date range parameters are optional but recommended to limit results **Date Filtering:** - Use `startDate` and `endDate` to filter snapshots by date range - Helps identify data availability for specific analysis periods ### 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 all available snapshots for crude oil data: ```python product="Crude/Co" ``` - Get recent snapshots for gasoline data: ```python product="Gasoline" startDate="2025-08-01" endDate="2025-08-12" ``` ## Output Format Returns snapshot dates in text format showing when supply and demand data snapshots are available for the specified product and date range. ## Technical Notes - Snapshot dates indicate when market data was captured and processed - Different products may have different snapshot frequencies - Use snapshot dates with the `snapshotDate` parameter in supply_demand tool for consistent historical analysis

kpler_get_supply_demand_snapshots

# Trades This endpoint provides users with comprehensive access to commodities flows at a granular trades level, representing commercial operations centered around cargo involving buyers, charterers, and sellers. Data is sourced from AIS vessel tracking, commercial intelligence, ML-powered forecasting algorithms, and analyst verification to provide real-time trade tracking with destination prediction and product estimation capabilities. **Data Source Classification:** - **Market**: Commercial intelligence and market data - **AIS**: Automatic Identification System vessel tracking data - **Algorithm**: Machine learning and algorithmic predictions - **Analyst**: Human analyst input and verification ## Key Use Cases - **Granular Trade Analysis**: Access detailed trade-level data for comprehensive market analysis - **Commercial Operations Monitoring**: Track buyers, charterers, and sellers in specific trades - **Cargo Flow Tracking**: Monitor individual cargo movements from origin to destination - **STS Transfer Analysis**: Analyze trades involving multiple vessels in ship-to-ship operations - **Trade Count Aggregation**: Get the count of trades matching specific filters for questions like "How many vessels..." or "How many trades..." ## Usage Guidance ### Input Parameters Guidelines & Caveats **IMPORTANT**: This tool has no `commodityType` input parameter. **Aggregation Parameter** Controls what aggregated information is returned alongside the trade data: - **Not specified (default)**: Returns only the trade data as `{"data": [...]}` - **"count"**: Returns both count and data as `{"count": 123, "data": [...]}` - **"countOnly"**: Returns only the count as `{"count": 123}` Use `"countOnly"` when you only need to know "how many" trades match the filters, without needing the detailed trade information. This is more efficient for counting operations. **IMPORTANT**: When using `aggregationMode="countOnly"`, the `size` parameter is **ignored** and the count reflects the total number of matching trades, not limited by pagination. This allows getting accurate counts without worrying about the size limit. **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 trades** (trades happening right now): Use `tradeStatus` with `"in transit"` or `"loading"` **without date parameters**. This returns cargoes currently moving or being loaded. 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"]` and **no date parameters**. **For future trades** (scheduled but not yet started): Use `tradeStatus=["scheduled"]` to find trades that will happen in the future. When filtering scheduled trades by date, **apply the same origin/destination date logic**: - For scheduled **exports** (fromZones specified): use `originDateStart`/`originDateEnd` - For scheduled **imports** (toZones specified): use `destinationDateStart`/`destinationDateEnd` Example: *"What shipments are scheduled for Europe next week?"* → Use `tradeStatus=["scheduled"]` with `toZones=["Europe"]` and `destinationDateStart`/`destinationDateEnd` for the week range (Europe is the destination, so use destination dates). **For historical trades** (already delivered): Use `tradeStatus=["delivered"]` with date parameters to analyze past trade data. **Date Parameters - Origin vs Destination Perspective** This tool provides two distinct date parameter sets to query trades from different market perspectives: **Origin Dates** (`originDateStart` and `originDateEnd`): Looks at trades from the **exporter/supply perspective**. Filters trades based on when cargo **departed from origin**. Use this when analyzing supply from source countries or export volumes. Example: *"I want to see the OPEC exports in 2025"* → Use `originDateStart="2025-01-01"`, `originDateEnd="2025-12-31"` with `fromZones=["OPEC"]`. **Destination Dates** (`destinationDateStart` and `destinationDateEnd`): Looks at trades from the **importer/demand perspective**. Filters trades based on when cargo **arrived at destination**. Use this when analyzing demand at receiving countries or import volumes. Example: *"I want to know China imports of crude oil in 2025"* → Use `destinationDateStart="2025-01-01"`, `destinationDateEnd="2025-12-31"` with `toZones=["China"]`, `products=["Crude"]`. **Trades from A to B**: When querying trades between specific origin and destination (e.g., "trades from Saudi Arabia to China"), use **origin dates** by default as you're looking at when cargo left the exporter. **Always mention to the user that you are using the export date perspective** so they understand how the data is filtered. Example: *"Show me crude oil trades from Saudi Arabia to China in 2025"* → Use `originDateStart="2025-01-01"`, `originDateEnd="2025-12-31"` with `fromZones=["Saudi Arabia"]`, `toZones=["China"]`, `products=["Crude"]`. → Tell the user: "I'm filtering by export date (when cargo departed from Saudi Arabia)". **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 **IMPORTANT**: When facing "Returned data is too large" errors: - Reduce requested columns to only essential fields - Split time-based queries into several ones with smaller date ranges **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. If you request data from a major region or period, BE VERY AGRESSIVE with column selection. 1. **Always start with essential columns:** `["id", "dateOrigin", "dateDestination", "status", "origin", "destination"]` 2. **Add cargo details if needed:** Add `"cargo"` for product and quantity information 3. **Add vessel details if needed:** Add `"vessels"` for vessel-specific analysis 4. **Add commercial details if needed:** Add `"players"` for buyer/seller information 5. **Only add complex fields like `"billsOfLading"` if specifically required** See the Output Format section for more information about columns. ### 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 the vessels carrying crude coming to Spain last week? ```python size=10000, toZones=["Spain"], products=["Crude"], destinationDateEnd="2025-08-13", destinationDateStart="2025-05-13", columns=["id", "dateOrigin", "dateDestination", "status", "origin", "destination", "cargo", "vessels"] ``` ## Output Format The following top-level columns are available in the trades response: | Column Name | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Kpler identifier of the trade. This ID is unique and cannot be reused. However, since multiple products can be exchanged during a trade, it can span over multiple lines. In this case, the Origin PortCall Id & Destination PortCall Id will be the same on each of these lines. | | dateOrigin | Start of the Trade. It can be either actual or estimated. Trade starts at the end of the loading Port Call. | | dateDestination | End of the Trade. It can be either actual or estimated. Trade ends at the start of the discharge Port Call. | | status | Status depicting the state of advancement of the trade. Scheduled means the load has not started yet. Loading means the load is ongoing. In Transit means the load is over and the discharge is in the future. Delivered means the discharge occurred. | | intraCountry | Cargo is traded within the same country. | | origin | Origin location details (zone, installation, country, etc.) | | destination | Destination location details (zone, installation, country, etc.) | | cargo | Cargo details including product and quantity information | | route | Name of the canal or route taken if any. | | players | Commercial players (buyers, sellers, charterers) | | longHaulVesselType | Type of vessel used for long haul transport | | commercialSequence | Commercial sequence details | | vessels | Vessel information including details and ship-to-ship operations | | billsOfLading | Bill of lading information | **Detailed Output Features:** - **ML Confidence Scoring**: Product estimations include confidence scores and predicted product names; destination forecasts provide multiple predictions with confidence levels - **Product Granularity**: Complete commodity hierarchy (family/group/product/grade/subgrade) with technical specs (API gravity, sulfur content for crude) - **Precision Quantities**: Dual-format measurements (tons + barrels/cubic meters) for both origin and destination quantities - **Shipment Tracking**: Evolution IDs for tracking commercial information changes over time - **STS Operations**: Detailed duration and location data for ship-to-ship transfers - **Vessel Intelligence**: Technical specifications (tank technology, power plant type) and ownership details including chartered vessel arrangements ## Technical Notes - All date/times within this endpoint are presented in Coordinated Universal Time (UTC) - A trade commences with the conclusion of the origin Port Call, and concludes either when the vessel reaches the berth at the destination Port Call or when the vessel departs the port if the installation is unknown - In the case of Ship-to-Ship (STS) transfers, multiple vessels may be involved - Trade status progression: scheduled → loading → in-transit → delivered, with ML destination forecasting and product estimation trained on historical Kpler data

kpler_get_trades