kpler_get_ais_historical
ChatGPTAIS Historical Vessel Positions Retrieves historical AIS vessel positions over a requested time window. Unlike AIS Latest (one position per vessel), this endpoint returns multiple positions per vessel within the requested period. Key Use Cases - Voyage Reconstruction: Trace a vessel's path over days or months by querying its historical positions - Traffic Analysis: Analyze vessel traffic patterns within a geographic area over a specific time period - Port Activity: Monitor vessel movements in and around ports or anchorages - Speed & Behavior Analysis: Study vessel speed changes, course alterations, and navigational patterns over time (use downsample=none for full resolution) When to use AIS Historical vs AIS Latest: Use this tool whenever the user asks about a specific date, time range, or past positions. Use AIS Latest only for current/real-time positions with no date filter. Usage Guidance CRITICAL RULES 1. ALWAYS use BBOX for rectangular areas — When the user provides coordinates that form a rectangle (e.g., two corner points, or four coordinates defining a box), use BBOX(position, minLon, minLat, maxLon, maxLat). Do NOT convert rectangular coordinates into a POLYGON. Only use INTERSECTS(position, POLYGON(...)) for irregular, non-rectangular shapes. 2. Area queries require a bounded 1-day date range — When using BBOX or POLYGON, you MUST use posDt BETWEEN '...' AND '...' with at most 1 day. Do NOT use posDt >= '...' (open-ended) with area queries — it will fail. Input Parameters Guidelines & Caveats Filter Parameter (ECQL Syntax) — REQUIRED: The filter must always include: 1. A posDt time constraint: - With area queries: posDt BETWEEN '...' AND '...' (bounded, max 1 day) - With vessel queries: posDt BETWEEN '...' AND '...' or posDt >= '...' (open-ended allowed, max 366 days) 2. At least one of: - Vessel identifiers: vesselUid or mmsi - ⚠️ imo is not an accepted filter field. If you only have an IMO, resolve it to an MMSI first by calling kpler_get_vessel_ownership_and_particulars with a GraphQL query (use kpler_get_vessel_ownership_and_particulars_graphql_schema to inspect the schema). If the lookup returns no result, ask the user to provide the MMSI or vesselUid directly. - Geographic constraint: - BBOX(position, minLon, minLat, maxLon, maxLat) — rectangular areas - INTERSECTS(position, POLYGON(...)) — irregular shapes (inside or touching boundary) - WITHIN(position, POLYGON(...)) — strictly inside, excludes boundary - NOT INTERSECTS(position, POLYGON(...)) — exclusion zone - DWITHIN(position, POINT(lon lat), distance, meters) — proximity search (1 nm = 1,852 m) - NOT DWITHIN(position, POINT(lon lat), distance, meters) — farther than distance from a point Query scope constraints: - By vessel identifiers: Up to 10 vessels per request, max date range of 366 days (raised to 100 vessels/year with downsample="hourly"). posDt >= '...' (open-ended) is allowed. - By geographic area: Area must not exceed 55,000 km², max date range of 1 day (raised to 1,000,000 km²/day with downsample="hourly"). Must use posDt BETWEEN '...' AND '...' — open-ended posDt >= is NOT allowed. - For broad-area or many-vessel sweeps, prefer downsample="hourly" to reach these raised caps instead of tiling small queries. Polygon Coordinates: Must be in (longitude, latitude) order and closed (first/last point identical). Only use POLYGON for non-rectangular shapes. For querying multiple non-contiguous areas in a single request, use INTERSECTS(position, MULTIPOLYGON(((...)),((...))));. Downsample Parameter: Controls whether historical positions are returned in full (none) or reduced (dynamic, hourly). - dynamic (default): Keeps at least one position every 10 minutes and additionally preserves positions where the absolute change in rate of turn is >= 10 degrees or speed over ground is >= 10 knots - hourly: Keeps only the first position received within each hour bucket per vesselUid. Unlocks the r…
kpler_get_ais_latest
ChatGPTAIS Latest Vessel Positions Retrieves the most recent known AIS positions for vessels worldwide, updated in near real-time. Key Use Cases - Real-time Vessel Tracking: Get current positions of vessels globally or within specific regions - Fleet Monitoring: Track multiple vessels by MMSI, IMO, or vessel characteristics - Geographic Analysis: Query vessels within specific polygons or areas of interest - Vessel Filtering: Filter by DWT, vessel type, flag, speed, or navigational status Usage Guidance Input Parameters Guidelines & Caveats Filter Parameter (ECQL Syntax): The filter parameter uses ECQL syntax with comparison (=, <>, <, >, <=, >=), logical (AND, OR, NOT), and spatial operators (BBOX, INTERSECTS, WITHIN, DWITHIN). Common filters: - By DWT: dwt >= 200000 - By IMO: imo = 9128520 - By flag: flag = 'FR' - By speed: sog > 10 - Combined: dwt >= 100000 AND flag = 'US' - Bounding box: BBOX(position, -5, 35, 10, 45) (min LON, min LAT, max LON, max LAT) - Polygon: INTERSECTS(position, POLYGON((-5 50, 5 50, 5 60, -5 60, -5 50))) — inside or touching boundary - Strictly inside: WITHIN(position, POLYGON(...)) — inside only, excludes boundary - Outside polygon: NOT INTERSECTS(position, POLYGON(...)) — exclusion zone - Proximity: DWITHIN(position, POINT(-10.25 35.87), 9260, meters) — within distance of a point (1 nm = 1,852 m) - Beyond distance: NOT DWITHIN(position, POINT(-10.25 35.87), 9260, meters) — farther than distance from a point Polygon Coordinates: Must be in (longitude, latitude) order and closed (first/last point identical). For querying multiple non-contiguous areas in a single request, use INTERSECTS(position, MULTIPOLYGON(((...)),((...))));. When to use AIS Latest vs AIS Historical: Use this tool only for current/real-time vessel positions (no date filter needed). If the user asks about a specific date, time range, or past positions, use AIS Historical instead. Fields Parameter: Use fields to limit response columns and reduce payload size. Available fields: mmsi, imo, longitude, latitude, sog, cog, heading, vesselName, flag, vesselType, dwt, posDt, etc. Examples - Get latest positions of large tankers: ``python filter="dwt >= 200000" limit=100 fields="mmsi,imo,vesselName,longitude,latitude,sog,dwt" ` - Find vessels in the North Sea: `python filter="BBOX(position, -5, 50, 10, 62)" limit=500 ` - Track specific vessel by IMO: `python filter="imo = 9128520" ` Output Format **JSON Response (default):** GeoJSON FeatureCollection with vessel positions and properties. The response includes metadata fields: - totalFeatures — total number of vessels matching the filter (even if limit returns fewer) - numberReturned — number of features in the current response **Counting tip:** To count vessels without fetching all data, use limit=1 and read totalFeatures` from the response. CSV Response: Tabular format with headers matching the requested fields. Technical Notes - Returns positions received within the past 7 days only - Positions updated in near real-time from terrestrial, roaming, and satellite AIS receivers - All coordinates use WGS84 (EPSG:4326) reference system - sog = Speed Over Ground (knots), cog = Course Over Ground (degrees)
kpler_get_arbitrage_benchmarks
ChatGPTArbitrage Benchmarks Get a list of available benchmarks used in crude oil arbitrage calculations. Key Use Cases - Discover Benchmarks: List all supported pricing benchmarks (e.g., Brent Future, Dubai Swap, WTI) - Parameter Discovery: Identify valid benchmark values for use with the arbitrage timeseries endpoints - Benchmark Selection: Help users choose the appropriate destination benchmark for their arbitrage analysis Usage Guidance This endpoint requires no additional parameters beyond authentication. It returns all available benchmarks. Output Format Returns a list of benchmarks, each with: - `name`: Full benchmark name (e.g., "Brent Future") - `shortName`: API identifier to use in other endpoints (e.g., "brentFuture") - `commodity`: Commodity type (e.g., "Crude Oil/Condensate") Example output: ``json { "benchmarks": [ { "name": "Brent Future", "shortName": "brentFuture", "commodity": "Crude Oil/Condensate" }, { "name": "Dubai Swap", "shortName": "dubaiSwap", "commodity": "Crude Oil/Condensate" } ] } ` Integration with Other Tools - Use the shortName values as the destinationBenchmark parameter in kpler_get_arbitrage_timeseries and kpler_get_arbitrage_timeseries_rolling`
kpler_get_arbitrage_combinations
ChatGPTArbitrage Combinations Get a list of unique arbitrage combinations (origin, destination, route, vessel type) available for crude oil arbitrage analysis. Key Use Cases - Discover Routes: Find all available arbitrage route combinations for a given product or destination - Parameter Discovery: Identify valid combinations before querying timeseries data - Filter Combinations: Narrow down combinations by product, destination, vessel type, or route Usage Guidance Input Parameters Guidelines & Caveats All parameters are optional filters. When no filters are provided, all available combinations are returned. - `products`: Filter by crude oil product names (e.g., "Agbami", "Access western blend") - `destinationPorts`: Filter by destination port names (e.g., "Rotterdam", "Singapore") - `destinationTradingRegions`: Filter by destination trading regions (e.g., "NWE", "SING", "MED") - `vesselTypes`: Filter by vessel types: "Suezmax", "Aframax", or "VLCC" - `viaRoutes`: Filter by shipping routes: "direct", "cogh" (Cape of Good Hope), "suez", "panama", "capehorn" Important Notes - Each combination includes a reference route used as the benchmark comparison for arbitrage calculations - The distance field represents the nautical miles for that route combination Examples - Get all combinations for a specific product: ``python products=["Agbami"] ` - Get VLCC combinations to Rotterdam: `python destinationPorts=["Rotterdam"] vesselTypes=["VLCC"] ` Output Format Returns a list of combinations, each containing: - **commodity**: Commodity type (e.g., "Crude Oil/Condensate") - **product**: Crude oil product name - **origin**: Origin location with port and tradingRegion - **destination**: Destination location with port and tradingRegion - **vesselType**: Vessel type (Suezmax, Aframax, VLCC) - **viaRoute**: Shipping route (direct, cogh, suez, etc.) - **referenceRoute**: The reference route used for arbitrage comparison - **distance**: Route distance in nautical miles **Example output:** `json { "combinations": [ { "commodity": "Crude Oil/Condensate", "product": "Access western blend", "origin": { "port": "Beaumont/Port Arthur", "tradingRegion": "USGC" }, "destination": { "port": "Singapore", "tradingRegion": "SING" }, "vesselType": "VLCC", "viaRoute": "cogh", "referenceRoute": { "product": "Oman", "origin": { "port": "Muscat", "tradingRegion": "MEG" }, "destination": { "port": "Singapore", "tradingRegion": "SING" }, "vesselType": "VLCC", "viaRoute": "direct" }, "distance": 13259 } ] } ` Integration with Other Tools - Use the returned combination values as inputs for kpler_get_arbitrage_timeseries and kpler_get_arbitrage_timeseries_rolling - Use kpler_get_arbitrage_products to discover available product names - Use kpler_get_arbitrage_regions` to discover available trading regions
kpler_get_arbitrage_products
ChatGPTArbitrage Products Get a list of all available crude oil products for arbitrage analysis. Key Use Cases - Discover Products: List all crude oil grades available for arbitrage analysis - Parameter Discovery: Identify valid product names for use with other arbitrage endpoints Usage Guidance This endpoint requires no additional parameters beyond authentication. It returns all available products. Output Format Returns a list of products, each containing: - `name`: Product name (e.g., "Access western blend", "Agbami") - `commodity`: Commodity type (e.g., "Crude Oil/Condensate") Example output: ``json { "products": [ { "name": "Access western blend", "commodity": "Crude Oil/Condensate" } ] } ` Integration with Other Tools - Use product name values as the product parameter in kpler_get_arbitrage_timeseries and kpler_get_arbitrage_timeseries_rolling - Use product name values as the products filter in kpler_get_arbitrage_combinations`
kpler_get_arbitrage_regions
ChatGPTArbitrage Regions Get a list of all available discharge regions with their reference ports and associated benchmarks. Key Use Cases - Discover Regions: List all trading regions available for crude oil arbitrage - Benchmark Mapping: Find which pricing benchmarks are available for each region - Default Benchmarks: Identify the default benchmark for each region Usage Guidance This endpoint requires no additional parameters beyond authentication. It returns all available regions. Output Format Returns a list of regions, each containing: - `name`: Trading region name (e.g., "USAC", "NWE", "SING", "MED", "USGC") - `referencePort`: Reference port for the region (e.g., "New York", "Rotterdam") - `commodity`: Commodity type (e.g., "Crude Oil/Condensate") - `benchmarks`: List of available benchmarks for this region: - `name`: Benchmark identifier (e.g., "brentFuture", "dubaiSwap") - `default`: Whether this is the default benchmark for the region Example output: ``json { "regions": [ { "name": "USAC", "referencePort": "New York", "commodity": "Crude Oil/Condensate", "benchmarks": [ { "name": "wtiSwap", "default": true } ] }, { "name": "NWE", "referencePort": "Rotterdam", "commodity": "Crude Oil/Condensate", "benchmarks": [ { "name": "datedSwap", "default": true }, { "name": "brentFuture", "default": false }, { "name": "brentSwap", "default": false } ] } ] } ` Integration with Other Tools - Use region names as the destinationTradingRegions filter in kpler_get_arbitrage_combinations - Use region benchmark names as the destinationBenchmark parameter in kpler_get_arbitrage_timeseries and kpler_get_arbitrage_timeseries_rolling - Use kpler_get_arbitrage_benchmarks` to get full benchmark details
kpler_get_arbitrage_timeseries
ChatGPTArbitrage Timeseries Lookup crude oil arbitrage timeseries data for a specific route and time window. Key Use Cases - Arbitrage Analysis: Calculate the economics of shipping crude oil between two locations for a specific window - Landed Value Breakdown: Get detailed breakdown of freight, costs, benchmark spread, and time structure - Refinery Margin Analysis: Compare refinery economics across simple, medium, and complex refinery types - Historical Assessment: Analyze how arbitrage economics evolved over an assessment period Usage Guidance Input Parameters Guidelines & Caveats Required Parameters: - `product`: Crude oil product name (use kpler_get_arbitrage_products to discover valid values) - `loadPort`: Load port name for the combination to analyze. Use the origin.port field of the matching entry from kpler_get_arbitrage_combinations for this product/destinationPort/vesselType/viaRoute — do not guess it. - `destinationPort`: Destination port name (use kpler_get_arbitrage_combinations to discover valid values) - `vesselType`: "Suezmax", "Aframax", or "VLCC" - `flowDirection`: Whether the window represents a Load ("export") or Discharge ("import") period - `assessmentStartDate`: Start date (YYYY-MM-DD) - `assessmentEndDate`: End date (YYYY-MM-DD) - `viaRoute`: Shipping route: "direct", "cogh" (Cape of Good Hope), "suez", "panama", "capehorn" - `window`: Window string defining the load/discharge period. There are 3 types of windows corresponding to 3 types of WindowGranularity. For example, "1-5 Oct-25" is a 5-day window, "1-10 Oct-25" is a 10-day window and "Oct-25" is a Month window. Optional Parameters: - `destinationBenchmark`: Pricing benchmark (e.g., "brentFuture", "dubaiSwap"). Defaults to region's default benchmark. Important Notes - The window parameter defines the delivery period in case of import, or the load period in case of export - Assessment dates define the range of pricing assessments to return - Route: "cogh" for Cape of Good Hope Examples - Agbami arbitrage to Rotterdam via direct route: ``python product="Agbami" loadPort="Agbami" destinationPort="Rotterdam" vesselType="Suezmax" flowDirection="import" assessmentStartDate="2025-01-01" assessmentEndDate="2025-01-31" viaRoute="direct" window="1-5 Oct-25" ` - VLCC arbitrage to Singapore with specific benchmark: `python product="Access western blend" loadPort="..." from kpler_get_arbitrage_combinations' matching origin.port destinationPort="Singapore" vesselType="VLCC" flowDirection="import" assessmentStartDate="2025-01-01" assessmentEndDate="2025-01-31" viaRoute="cogh" window="Oct-25" destinationBenchmark="dubaiSwap" ` Output Format Returns a timeseries object with: - **flowDirection**: "import" or "export" - **identifier**: Route identifier (product, destination, vesselType, viaRoute) - **referenceIdentifier**: Reference route used for comparison - **items**: Array of assessment data points, each containing: - **assessmentDate**: Date of the price assessment - **period**: Window period details (start/end dates, granularity) - **voyage**: Load/discharge dates and quantity - **benchmarks**: Load and discharge benchmark names and tenors - **arbitrage**: Arbitrage values by refinery type (SIMPLE, MEDIUM, COMPLEX) in $/bbl - **refineryMargin**: Refinery margins by type in $/bbl - **landedArbitrage**: Landed arbitrage value in $/bbl (may be null) - **landedValue**: Detailed breakdown with components: - freight: Freight cost and canal costs - costs: Demurrage, financing, inspection, and losses costs - timestructure: Time structure adjustment - benchmarkSpread: Benchmark spread between origin and destination Integration with Other Tools - Use kpler_get_arbitrage_products to discover valid product names - Use kpler_get_arbitrage_combinations to find valid route combinations - Use kpler_get_arbitrage_benchmarks to find valid benchmark names - Use kpler_get_arbitrage_regions` to find region-specific default benchmarks - Use…
kpler_get_arbitrage_timeseries_rolling
ChatGPTArbitrage Timeseries Rolling Get rolling period crude oil arbitrage timeseries data. Unlike the lookup timeseries endpoint which uses a fixed window, this endpoint uses a rolling window that moves forward based on the assessment date. For each assessment date, the first available forward period for an arbitrage will change (eg. on 2-Jan (assessment date) the first available export maybe on 12-Jan (load date), on 12-Jan (assessment) the first available load date may be 22-Jan (load date). As the assessment date changes, the window returned also changes. Key Use Cases - Automatic Forward Window Selection: For each assessment date, automatically picks the nearest (or n-th) available forward arbitrage window — unlike /timeseries, no need to manually specify or update the load/discharge window - Forward Period Comparison: Compare arbitrage for different forward periods (1st, 2nd, 3rd rolling period) - Time-Granularity Analysis: Analyze arbitrage at different granularities (5-day, 10-day, or monthly windows) Usage Guidance Input Parameters Guidelines & Caveats Required Parameters: - `product`: Crude oil product name (use kpler_get_arbitrage_products to discover valid values) - `loadPort`: Load port name for the combination to analyze. Use the origin.port field of the matching entry from kpler_get_arbitrage_combinations for this product/destinationPort/vesselType/viaRoute — do not guess it. - `destinationPort`: Destination port name (use kpler_get_arbitrage_combinations to discover valid values) - `vesselType`: "Suezmax", "Aframax", or "VLCC" - `flowDirection`: Whether the window represents a Load ("export") or Discharge ("import") period - `assessmentStartDate`: Start date (YYYY-MM-DD) - `assessmentEndDate`: End date (YYYY-MM-DD) - `windowGranularity`: Window size: "5d" (5-day), "10d" (10-day), or "month" - `viaRoute`: Shipping route: "direct", "cogh" (Cape of Good Hope), "suez", "panama", "capehorn" Optional Parameters: - `rollingPeriod`: Index of the rolling period (default: 1 = nearest forward period). Higher values look further into the future. - `destinationBenchmark`: Pricing benchmark. Defaults to region's default benchmark. - `requireArbitrage`: If true (default), only returns data points that have arbitrage values. Set to false to also include data points that have landed value and refinery margin but no arbitrage. Important Notes - The rolling period automatically adjusts the delivery window as it rolls forward - rollingPeriod=1 is the nearest forward period, rollingPeriod=2 is the next one, etc. - Route: "cogh" for Cape of Good Hope Examples - Rolling 5-day arbitrage for Agbami to Rotterdam: ``python product="Agbami" loadPort="Agbami" destinationPort="Rotterdam" vesselType="Suezmax" flowDirection="import" assessmentStartDate="2025-01-01" assessmentEndDate="2025-01-31" windowGranularity="5d" viaRoute="direct" ` - Monthly rolling arbitrage for 2nd forward period: `python product="Access western blend" loadPort="..." from kpler_get_arbitrage_combinations' matching origin.port destinationPort="Singapore" vesselType="VLCC" flowDirection="import" assessmentStartDate="2025-01-01" assessmentEndDate="2025-03-31" windowGranularity="month" viaRoute="cogh" rollingPeriod=2 ` Output Format Same as kpler_get_arbitrage_timeseries. Returns a timeseries object with: - **flowDirection**: "import" or "export" - **identifier**: Route identifier - **referenceIdentifier**: Reference route for comparison - **items**: Array of assessment data points with arbitrage, refinery margins, landed arbitrage, landed value breakdown, voyage details, and benchmark information Integration with Other Tools - Use kpler_get_arbitrage_products to discover valid product names - Use kpler_get_arbitrage_combinations to find valid route combinations - Use kpler_get_arbitrage_benchmarks to find valid benchmark names - Use kpler_get_arbitrage_regions to find region-specific default benchmarks - Use kpler_get_arbitrage_timeseries`…
kpler_get_cargo_fleet_metrics
ChatGPTFleet Metrics The Fleet Metrics endpoint offers a comprehensive view of both global and regional trends by aggregating fleet data, providing valuable insights into impactful trends within the markets. 2 metrics are available: - Floating Storage Allows to analyse laden vessels that have been floating for a minimum of 7 days for liquids and at least 1 day for LNG. It provides insights into vessels in a state of suspended operation, offering a unique perspective on market conditions. - Commodities On Water Allows to analyse the total amount of commodities carried by vessels, regardless of their state—whether in motion or stationary. It includes both actively moving vessels and those engaged in floating storage. Key Use Cases - Market Trend Analysis: Track global and regional fleet dynamics to identify market trends - Floating Storage Monitoring: Analyze laden vessels in suspended operation for market insights - Commodity Volume Assessment: Monitor total commodities on water regardless of vessel state - Regional Comparison: Compare fleet performance across different geographical regions - Complete Storage Analysis: ALWAYS consider using this tool when analyzing storage levels for any commodity to include floating storage (vessels stationary for 7+ days) and in-transit volumes. Usage Guidance Input Parameters Guidelines & Caveats Status Parameter - "status=scheduled" only include vessels that have not yet left the origin port. This is very rarely what the user wants. DO NOT FILTER only on scheduled unless the user explicitely asked for it. 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 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) Examples - How has crude oil floating storage evolved globally over the past quarter, broken down by major trading regions?" ``python metric="floating-storage" granularity="weekly" startDate="2025-05-13" endDate="2025-08-13" products=["Crude"] split=["currentCountries"] ` - What are the current volumes of clean petroleum products on water globally, broken down by product type? `python metric="commodities-on-water" granularity="daily" startDate="2025-08-06" endDate="2025-08-13" products=["Clean Products"] split=["Products"] ` Output Format Returns an array of time-series data points, one for each time interval based on the specified granularity, containing quantities aggregated according to the requested split parameters. For instance: ` [ { "date": "2025-08-06", "splits": [ { "quantity": 3007.16, "unit": "kb", "currentContinent": "Africa" }, { "quantity": 252.88, "unit": "kb", "currentContinent": "Americas" }, ... ] }, ... ] ` Technical Notes - All date/times within this endpoint are presented in Coordinated Universal Time (UTC) - Among the two types of analysis we can provide granular data through aggregation Integration with Other Tools - Complements kpler_get_crude_inventories` by providing offshore storage data to complete the land-based storage picture
kpler_get_compliance_screening
ChatGPTCompliance Screening Provides comprehensive compliance screening and fleet risk assessment for maritime vessels, enabling bulk filtering and identification of vessels based on multiple risk criteria including sanctions, operational behaviors, management oversight, and fleet categorization. Returns paginated lists of vessels matching specified compliance and risk parameters. Key Use Cases - Fleet-wide risk screening: Identify vessels across entire fleets based on specific risk profiles and compliance criteria - Sanctions monitoring: Find all vessels with active sanctions from specific authorities (OFAC, OFSI, EU, UN, FCDO) - Shadow fleet identification: Screen for vessels categorized as shadow, sanctioned, or white fleet - Risk-based vessel discovery: Locate vessels with specific combinations of operational, management, or flag risks - Compliance due diligence: Generate comprehensive lists of vessels for regulatory reporting and risk assessment Usage Guidance Input Parameters Guidelines & Caveats Risk Type Logic: - Category-level selection (e.g., riskType=["sanction"]): Returns vessels with ANY associated subrisk (OR logic) - Subrisk-level selection (e.g., riskType=["vessel", "cargo"]): Returns vessels with ALL selected subrisks (AND logic) - Mixing categories and subrisks in the same request may produce unexpected results Parameter Incompatibilities: - fleetType parameter is mutually exclusive with riskType, authority, and vessels filters - authority filter only works when riskType is set to "sanction" or sanction subcategories - Cross-category vessel type filtering (mixing Dry, Liquids, LNG, LPG types) is not supported and will return an error Performance Recommendations: - For large-scale screening, ALWAYS paginate; limit can go up to 500 (use a smaller value like 200 if you hit response size errors) - When screening entire fleets, consider using fleetType for initial high-level assessment - For detailed analysis, combine specific risk filters rather than requesting all risks at once - Critical: When response shows count > vessels returned, continue fetching additional pages until all data is retrieved Products Parameter: - Product IDs can be found using the products tool 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) - Default startDate: 2022-01-01 if not specified - Default endDate: Current date if not specified Pagination and Data Retrieval - page: Number of records to skip — i.e. an offset, not a page index (default: 0) - limit: Maximum records to return (default: 200, max: 500) - IMPORTANT: Always check if more data is available using the response count field - Auto-pagination requirement: When count > returned vessels, ALWAYS make additional requests, advancing page by limit (or by vessels.length) each call, to retrieve all available data - To detect if more pages exist: page + vessels.length < count - Use limit=500 for fewer round-trips, or a smaller value (e.g. 200) if you hit response size errors Examples Find all sanctioned vessels of a specific type: ``python vesselType=["AFRAMAX_LR2", "SUEZMAX_LR3"] riskType=["sanction"] startDate="2024-01-01" endDate="2024-12-31" limit=100 ` **Screen shadow fleet vessels with specific flag:** `python fleetType="shadow" vesselFlag=["PA", "LR"] Panama and Liberia flags startDate="2024-06-01" ` **Find vessels with multiple operational risks:** `python riskType=["aisGaps", "darkStsTransfer", "aisSpoofing"] startDate="2024-01-01" limit=50 ` **Search for OFAC-sanctioned vessels carrying specific products:** ``python riskType=["sanction"] authority=["ofac"] products=[1334, 1335] Specific product IDs sta…
kpler_get_congestion_series
ChatGPTCongestion Series Retrieves a time series of vessel congestion data, providing insights into port and regional congestion patterns over time measured by different metrics. Key Use Cases - Congestion Pattern Analysis: Track vessel congestion trends over time across different ports and regions - Port Performance Monitoring: Analyze port efficiency and congestion duration patterns - Market Impact Assessment: Understand how congestion affects cargo flows and vessel operations - Regional Comparison: Compare congestion metrics across different geographic areas and installations Usage Guidance Input Parameters Guidelines & Caveats Unit Parameter - ALWAYS Use the correct unit for the product type: - tons for dry products - barrels for liquids products (oil, jet fuel, diesel...) - cubic meters (m³) for LNG product - Apply multipliers when appropriate (ktons, mtons, mmbarrels…). - At display time, ALWAYS convert to a suitable unit. Example: for >1,000,000 tons, use ktons or mtons. Explain your choice of unit before calling this tool. Product Filtering: - DO USE the products parameter to only get the relevant entries whenever possible Vessel Type Filtering: - DO NOT USE VesselTypes, VesselTypesOil and VesselTypesCpp parameter if the user didn't explicitly request a specific vessel type - Beware: a Crude or LNG Tanker is not a specific vessel type Split Guidelines: - NEVER MIX total with other split values CongestionOnly Parameter - When asked about Suez or Panama, ALWAYS set congestionOnly to false Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), always remind what is the current date and explain how you compute the date range - Week definition: Weeks start on Monday by default - "Last week" = Previous Monday to Sunday (NOT the last 7 days) - "Next week" = Following Monday to Sunday (NOT the next 7 days) Analysis Features - Time series analysis of vessel congestion patterns - Flexible metrics including count, deadWeight, duration, and capacity - Support for various split dimensions (country, port, installation, vessel type, etc.) - Commodity-specific filtering (Liquids, Dry, LNG, LPG) - Customizable time periods and date ranges - Advanced filtering by vessel characteristics and operations Examples - Track daily vessel congestion trends in major Asian ports by country? ``python commodityType="liquids" metric="count" split="country" vesselOperation="Load" startDate="2025-08-01" endDate="2025-08-13" zones=["China", "Singapore"] period="days" ` - Analyze congestion duration patterns at specific installations? `python commodityType="liquids" metric="duration" split="installation" vesselOperation="Discharge" startDate="2025-08-01" endDate="2025-08-13" zones=["Rotterdam"] period="weeks" products=["Crude"] ` Output Format A CSV formatted time series with columns for: - Date (period start) - Split dimension columns (e.g., country names, installation names) - Metric values (count, deadweight, duration, or capacity) **Example:** `csv Date;Singapore Republic;China 2025-08-01;91;59 2025-08-02;84;66 2025-08-03;82;67 `` Technical Notes - Congestion is determined by waiting duration thresholds and zone-specific parameters - Duration metric provides average waiting time in hours - Count metric shows number of vessels in congestion - DeadWeight and capacity metrics show tonnage or capacity of congested vessels - Data is updated in real-time based on AIS vessel tracking
kpler_get_congestion_vessels
ChatGPTCongestion Vessels Retrieves a list of vessels currently experiencing congestion at ports, providing detailed information about individual vessels based on waiting duration and zone-specific criteria. Key Use Cases - Individual Vessel Congestion Tracking: Monitor specific vessels currently experiencing congestion - Congestion Duration Analysis: Analyze how long individual vessels have been in congested states - Vessel-level Impact Assessment: Understand congestion effects on specific vessel operations - Detailed Congestion Investigation: Get comprehensive data on vessels contributing to port congestion Usage Guidance Input Parameters Guidelines & Caveats Vessel Type Filtering: - DO NOT USE VesselTypes, VesselTypesOil and VesselTypesCpp parameter if the user didn't explicitly request a specific vessel type - Beware: a Crude or LNG Tanker is not a specific vessel type Columns Parameter You must specify which columns to include in the response using the columns parameter. This dramatically reduces response size and focuses on specific data fields essential for your analysis. 1. Always start with essential columns: ["vessel", "vessel_imo", "cargo_tons", "product", "installation", "congestion_duration_hrs"] 2. Add location details if needed: Add "port", "country", "zone" 3. Add exact timing details if needed: Add "congestion_start_date", "congestion_end_date" 4. Set `columns="all"` only if you need comprehensive data Size Parameter: - Use size=10000 when you want all available data - Use smaller values only if you need to limit results for performance reasons CongestionOnly Parameter - When asked about Suez or Panama, ALWAYS set congestionOnly to false Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), always remind what is the current date and explain how you compute the date range - Week definition: Weeks start on Monday by default - "Last week" = Previous Monday to Sunday (NOT the last 7 days) - "Next week" = Following Monday to Sunday (NOT the next 7 days) Examples - Get detailed information on vessels currently in congestion at Singapore? ``python commodityType="liquids" size=10000 vesselOperation="Load" zones=["Singapore"] startDate="2025-08-13" endDate="2025-08-13" columns=["vessel", "cargo_tons", "product", "installation", "congestion_duration_hrs"] ` - Find all crude oil vessels waiting for discharge in major ports for over 48 hours? `python commodityType="liquids" size=10000 vesselOperation="Discharge" products=["Crude"] waitingDurationMin=2 zones=["World"] startDate="2025-08-13" endDate="2025-08-13" ` Output Format A CSV formatted list with columns including: - Date, IMO, Name, Dead Weight Tonnage - Cargo details (tonnage, family, group, products) - Location (installation, port, country, zone) - Congestion details (waiting start/end dates, waiting time in hours, status) - Vessel information (type, operation) **Example:** `csv Date (timestamp);IMO;Name;Dead Weight Tonnage;Cargo (t);Products;Installation;Waiting Time (hrs);Vessel Type;Vessel Operation 2025-08-13;9543536;Alegria I;104494;63242.451;FO;ExxonMobil PAC Refinery;199.95;LR2;Load 2025-08-13;9645437;Aegean Vision;164950;-81333.97;Crude;Tankstore;179.01;VLCC;Discharge ` Technical Notes - Real-time data based on AIS vessel positions and port zone definitions - Supports filtering by minimum/maximum waiting duration in days - **cargo_tons sign convention:** Positive values = vessels loading; negative values = vessels discharging. This matches the vessel_operation column. Use abs(cargo_tons)` when comparing magnitudes regardless of flow direction.
kpler_get_contracts_columns_v1
ChatGPTContracts 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_v1
ChatGPTContracts 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_crude_inventories
ChatGPTCrude 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_cushing_drones_inventories
ChatGPTCushing 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 kpler_get_fleet_development_series
ChatGPTFleet 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_vessels
ChatGPTFleet 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_metrics_vessels
ChatGPTFleet 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 | | ----------------------- | ------------…
kpler_get_fleet_utilization_series
ChatGPTFleet 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_vessels
ChatGPTFleet 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_flows
ChatGPTFlows The Flows endpoint serves as an aggregation of trades, offering a macro-view of individual cargoes in real-time to quickly identify trends in the commodities market. Key Use Cases - Market Trend Analysis: Identify macro-level trends in commodities markets through trade aggregation - Directional Analysis: Analyze cargo movement patterns for imports, exports, or net flows - Regional Comparison: Compare trade flows across different origins and destinations - Product Flow Tracking: Monitor movement patterns for specific commodities and products Usage Guidance Input Parameters Guidelines & Caveats TradeStatus Parameter Specifies the trade depending on the vessel and cargo status: - scheduled: the vessel has not yet reached its berth and has not started loading - loading: the vessel is currently loading cargo - in transit: the vessel is at sea with cargo loaded - delivered: the vessel has discharged its cargo at the destination port The statuses follow this chronology: scheduled -> loading -> in transit -> delivered. For present/current flows (cargo currently moving): Use tradeStatus with "in transit" or "loading" without date parameters. This returns aggregated volumes of cargo currently on the water. Example: "What are the crude oil cargoes from Iran heading to China right now?" → Use tradeStatus=["in transit"] with fromZones=["Iran"], toZones=["China"], products=["Crude"], flowDirection="Export" and no date parameters. For future flows (scheduled but not yet started): Use tradeStatus=["scheduled"] to analyze volumes that will be shipped in the future. flowDirection and Date Relationship The flowDirection parameter determines which date perspective is used for aggregation: - Export: Aggregates based on departure date from origin (corresponds to originDateStart/originDateEnd in Trades) - Import: Aggregates based on arrival date at destination (corresponds to destinationDateStart/destinationDateEnd in Trades) IMPORTANT: Always choose the flowDirection that matches your analysis perspective: - Use "Export" when analyzing supply from source countries/regions - Use "Import" when analyzing demand at destination countries/regions Example: "I want to see OPEC exports in 2025" → Use flowDirection="Export" with fromZones=["OPEC"], startDate="2025-01-01", endDate="2025-12-31". Example: "I want to know China imports of crude oil in 2025" → Use flowDirection="Import" with toZones=["China"], products=["Crude"], startDate="2025-01-01", endDate="2025-12-31". Flows from A to B: When querying flows between specific origin and destination (e.g., "flows from Saudi Arabia to China"), use flowDirection="Export" by default as you're looking at when cargo left the exporter. Always mention to the user that you are using the export perspective so they understand how the data is aggregated. Example: "Show me crude oil flows from Saudi Arabia to China in 2025" → Use flowDirection="Export" with fromZones=["Saudi Arabia"], toZones=["China"], products=["Crude"], startDate="2025-01-01", endDate="2025-12-31". → Tell the user: "I'm using the export perspective (aggregating by departure date from Saudi Arabia)". Unit Parameter - ALWAYS Use the correct unit for the product type: - tons for dry products - barrels for liquids products (oil, jet fuel, diesel...) - cubic meters (m³) for LNG product - Apply multipliers when appropriate (ktons, mtons, mmbarrels…). - At display time, ALWAYS convert to a suitable unit. Example: for >1,000,000 tons, use ktons or mtons. Explain your choice of unit before calling this tool. Split Parameter: - You can apply up to 5 splits simultaneously. For more granularity, you can use the kpler_get_trades tool - If asked about per-country results, always split both per destination and per origin countries using the split argument, unless the user explicitly specified to do only one: `split=["destinationCountries", "originCountries"…
kpler_get_freight_fixtures
ChatGPTFreight Fixtures Retrieves a list of freight fixtures based on various parameters related to vessel movements, cargo, and contract terms, allowing analysis of freight contracts and pricing. Key Use Cases - Freight Rate Analysis: Track freight fixtures and pricing trends over specific time periods - Market Activity Monitoring: Monitor freight fixing activity and contract terms in the market - Charter Market Analysis: Analyze charterer activity and vessel owner participation - Contract Terms Evaluation: Examine laycan periods, origins, destinations, and pricing Usage Guidance Input Parameters Guidelines & Caveats Size Parameter: - Use size=10000 when you want all available data - Use smaller values only if you need to limit results for performance reasons Date Range Parameters: - Use reportedDateAfter/reportedDateBefore for when fixtures were reported - Use layCanStartAfter/layCanStartBefore for loading window dates Column Parameter: - Set columns="all" to retrieve all available fixture details - Default returns essential fixture information Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), always remind what is the current date and explain how you compute the date range - Week definition: Weeks start on Monday by default - "Last week" = Previous Monday to Sunday (NOT the last 7 days) - "Next week" = Following Monday to Sunday (NOT the next 7 days) Examples - Get recent crude oil fixtures reported this week? ``python commodityType="liquids" size=10000 reportedDateAfter="2025-08-01" reportedDateBefore="2025-08-13" products="Crude" columns="all" ` - Find all VLCC fixtures from Middle East to Asia in the past month? `python commodityType="liquids" size=10000 vesselTypesOil=["VLCC"] fromZones="Middle East" toZones="Asia" reportedDateAfter="2025-07-13" reportedDateBefore="2025-08-13" ` Output Format A CSV formatted list of fixtures with the following columns: - Reported date - Vessel - IMO - Quantity (t) - Deadweight (t) - Family - Group - Product - Charterer - Vessel owner - Laycan start - Laycan end - Origin - Destination - Rates ($ price) - Status - Vessel Type Cpp - Vessel Type Oil **Example:** `csv Reported date;Vessel;IMO;Quantity (t);Deadweight (t);Product;Charterer;Vessel owner;Laycan start;Origin;Destination;Rates ($ price);Status;Vessel Type Oil 2025-08-13;Ds Vision;9522178;260000.0;297345;Crude;Petrobras;China Shipping;2025-09-12;Brazil;Cochin;54.0;Fully Fixed;VLCC 2025-08-13;Yuan Hua Hu;9723588;260000.0;308603;Crude;UNIPEC;COSCO Group;2025-09-10;Western Africa;China;;Fully Fixed;VLCC `` Technical Notes - Fixture status indicates progression: On Subs → Fully Fixed → other statuses - Laycan (Lay/Cancelling) dates define the loading window period - Rates show freight pricing when available in fixtures database - Supports filtering by vessel deadweight range, charterers, and fixture status
kpler_get_freight_metrics_series_alt
ChatGPTFreight 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_vessels_alt
ChatGPTFreight 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_insights_search_filters
ChatGPTRetrieves 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_lng_capacities
ChatGPTLNG 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_diversions
ChatGPTDiversions 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_installations
ChatGPTInstallations 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_inventories
ChatGPTLNG Inventories Leverages multiple data sources including Kpler flow data to provide comprehensive time-series view of historical and forecasted LNG inventory storage across global installations. Key Use Cases - LNG Inventory Tracking: Monitor historical and forecasted inventory levels across global LNG installations - Market Analysis: Analyze LNG inventory trends affecting global LNG markets and pricing - Import/Export Monitoring: Track inventory levels at both regasification (import) and liquefaction (export) installations - Forecasting Analysis: Access short-term inventory forecasts for planning and analysis Usage Guidance Input Parameters Guidelines & Caveats Split Parameter: - Supports multiple split applications based on parameters such as Installation, Country, and more - NEVER MIX totals with other split values Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), always remind what is the current date and explain how you compute the date range - Week definition: Weeks start on Monday by default - "Last week" = Previous Monday to Sunday (NOT the last 7 days) - "Next week" = Following Monday to Sunday (NOT the next 7 days) Date Field Structure Dates included in the response: - date: The first day of the period, serves as immutable reference for each group of splits and should be used as the primary key when storing data or joining with other endpoints - For granularity=daily: Each calendar day - For granularity=weekly: The Monday of each week - For granularity=monthly: The first day of the month - For granularity=yearly: The first day of the year - valueDate: The date when the metrics were measured - lastImage: The date of the last satellite or source image used to measure or infer the metrics Examples - Track US LNG storage inventories over past quarter ``python granularity="monthly" startDate="2024-01-01" endDate="2024-03-31" zones=["United States"] splits=["totals"] unit="kwh" ` - Monitor LNG inventory levels at specific installations with weekly granularity `python granularity="weekly" startDate="2025-08-01" endDate="2025-08-07" zones=["Singapore"] splits=["installations"] unit="tj" ` Output Format A JSON response containing time-series inventory data with the following fields: **Time Series Structure:** - date: Period start date (YYYY-MM-DD) - primary key for data grouping - split: Array containing inventory data for the specified split level **Inventory Data Fields:** - storageVolume: Current volume of stored LNG in the specified unit - storageCapacity: Maximum storage capacity in the specified unit - capacityUtilization: Ratio of current storage to total capacity (0.0-1.0) - storageHeel: Minimum operational storage level maintained - cargoImport: Volume of LNG imported during the period - cargoExport: Volume of LNG exported during the period - gasSend-in: Gas volume sent into storage - gasSend-out: Gas volume sent out from storage - valueDate: Date when the metrics were measured (YYYY-MM-DD) - unit: Unit of measurement (e.g., "kwh", "tj", "m3") **Additional Date Fields:** - lastImage`: Date of last satellite or source image used for measurement Technical Notes - Uses multiple data sources including Kpler flow data - Historical limit: January 1, 2017 - Forecast limit: Up to 2 weeks
kpler_get_lng_outages
ChatGPTLNG 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_trains_phases
ChatGPTLNG Trains Phases Offers the most granular details of installation capacity for each individual train (liquefaction) and phase (regasification) unit, including operational status and timing information. Key Use Cases - Granular Capacity Analysis: Access detailed capacity information for individual LNG trains and regasification phases - Operational Status Monitoring: Track operational status of specific LNG infrastructure units - Project Timeline Tracking: Monitor start-up and end dates for individual trains and phases - Infrastructure Development Analysis: Analyze LNG facility expansion and development projects Usage Guidance Input Parameters Guidelines & Caveats Installation Type Required: - Must specify installationType as either "export" (liquefaction) or "import" (regasification) Status Filtering: - Available status values: active, approved, planned and proposed, under construction, decommissioned, speculative, suspended, mothballed - Filter by multiple status values to focus on specific operational states Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), always remind what is the current date and explain how you compute the date range - Week definition: Weeks start on Monday by default - "Last week" = Previous Monday to Sunday (NOT the last 7 days) - "Next week" = Following Monday to Sunday (NOT the next 7 days) Granular Detail Coverage Provides most granular details including: - Individual train (liquefaction) capacity details - Individual phase (regasification) capacity information - Operational status for each unit - Start-up and end date information - Individual unit specifications Examples - Get individual train details for US LNG export facilities ``python installationType="export" startDate="2025-01-01" endDate="2025-03-31" zones=["United States"] status=["active"] ` - Monitor specific installation train capacity and timing `python installationType="import" startDate="2024-01-01" endDate="2024-12-31" installations=["Gate Terminal"] status=["active", "under construction"] ` Output Format A JSON array containing installation records with granular train/phase details: **Installation Information:** - installation.name: Name of the LNG installation - installation.id: Unique installation identifier - installation.type: Type of installation ("export" or "import") - location: Geographic hierarchy (continent, subcontinent, country) **Train/Phase Details Array:** - trainsPhases: Array of individual units with the following fields: - name: Individual train or phase identifier - status: Operational status ("active", "under construction", "planned", etc.) - startDate: Start date of operations (ISO 8601 format) - endDate: End date of operations (null if ongoing) - quantity.mass: Capacity in metric tons - quantity.unit`: Unit of measurement (typically "mt") Technical Notes - Provides most granular level of LNG infrastructure detail - Individual train (liquefaction) and phase (regasification) capacity information - Includes operational timeline with start/end dates for each unit - Status tracking for infrastructure development projects - Capacity data in metric tons for precise capacity planning
kpler_get_lng_utilizations
ChatGPTLNG Utilizations Harnesses Kpler's proprietary LNG flows and capacity data set to provide time series view of historical to real-time utilization rates for global LNG installations. Key Use Cases - Utilization Monitoring: Track historical to real-time utilization rates across global LNG installations - Performance Analysis: Analyze utilization efficiency at LNG liquefaction and regasification facilities - Market Efficiency Assessment: Understand how effectively LNG infrastructure is being utilized - Operational Benchmarking: Compare utilization rates across different installations and regions Usage Guidance Input Parameters Guidelines & Caveats Split Parameter: - You can perform 1 split at a time - Split options include: Continent, Sub-Continent, Country, and Installation Date Range parameter: - Historical limit: 1 January 2009 - Forecast limit: Month to date Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), always remind what is the current date and explain how you compute the date range - Week definition: Weeks start on Monday by default - "Last week" = Previous Monday to Sunday (NOT the last 7 days) - "Next week" = Following Monday to Sunday (NOT the next 7 days) Data Coverage Provides comprehensive utilization data for: - Global LNG liquefaction (export) installations - Global LNG regasification (import) installations - Historical to real-time utilization rates - Time series by month, quarter or year Examples - Track US LNG export facility utilization rates by installation ``python installationType="export" granularity="monthly" startDate="2025-01-01" endDate="2025-03-31" zones=["United States"] splits=["installations"] ` - Monitor global LNG import utilization trends by country `python installationType="import" granularity="quarterly" startDate="2024-01-01" endDate="2024-12-31" splits=["countries"] ` Output Format A JSON response containing time-series utilization data with the following fields: **Time Series Structure:** - date: Period start date (YYYY-MM-DD) - split: Array containing utilization data for the specified split level **Utilization Data Fields:** - nominalCapacity: Available capacity for the period in metric tons - cargoVolume: Actual cargo volume processed in metric tons - utilizationRate: Utilization rate as decimal (e.g., 0.85 = 85%) - installationType: Type of installation ("export" or "import") **For installation-level splits, additional fields:** - installationName: Name of the LNG installation **For country-level splits, additional fields:** - country`: Country name where installations are located Technical Notes - Uses Kpler's proprietary LNG flows and LNG capacity data set - Historical coverage from 1 January 2009 - Real-time data updates available - Split granularity: 1 split at a time
kpler_get_lng_utilizations_trends
ChatGPTLNG 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_next_destination
ChatGPTNext 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_port_calls_v1
ChatGPTPort 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;-…
kpler_get_products
ChatGPTProducts 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_refineries_crude_co_imports
ChatGPTRefineries 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_margins
ChatGPTRefineries 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_particulars
ChatGPTRefineries 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_primary_distillation
ChatGPTRefineries Primary Distillation Retrieves operational run data of Primary Distillation Units including Crude Distillation Units (CDU) and Condensate Splitters for selected refineries. Key Use Cases - Primary Processing Monitoring: Track operational run data for crude distillation and condensate splitting units - Refinery Throughput Analysis: Analyze primary distillation capacity utilization and performance - Feedstock Processing Assessment: Monitor how refineries process crude oil and condensate inputs - Operational Efficiency Analysis: Evaluate primary distillation unit performance across different refineries Usage Guidance Input Parameters Guidelines & Caveats Unit Coverage: - Primary Distillation includes both Crude Distillation Unit (CDU) and Condensate Splitter - Secondary Units encompass Reformer, Distillate Hydrocracker, Fluid Catalytic Cracking (FCC) unit, and Coker Split Restrictions: - DO NOT USE "players" for the splits parameter - IT IS NOT A VALID VALUE FOR splits - DO NOT MIX total with other split values Generic Date Range Considerations - When given relative periods (e.g., "this week", "last month"), always remind what is the current date and explain how you compute the date range - Week definition: Weeks start on Monday by default - "Last week" = Previous Monday to Sunday (NOT the last 7 days) - "Next week" = Following Monday to Sunday (NOT the next 7 days) Split Capabilities Empowers users to perform multiple splits based on various parameters including crude grades, countries, refineries and more. Examples - Track primary distillation runs at US refineries by crude quality: ``python granularity="weekly" zones=["United States"] startDate="2025-07-01" endDate="2025-08-13" splits=["crude qualities", "refineries"] unit="kbd" ` - Analyze crude grade processing at European refineries: `python granularity="daily" zones=["Europe"] startDate="2025-08-01" endDate="2025-08-13" splits=["crude grades", "countries"] crudeGrades=["Brent", "Forties", "Ekofisk"] unit="kbd" ` Output Format A CSV formatted time series dataset showing primary distillation operational runs: - **Date**: Period start date based on selected granularity - **Processing Volumes**: Crude distillation runs in selected unit (kbd, kb, Mbbl, m3) - **Split Dimensions**: Additional columns based on selected splits (crude qualities, grades, refineries, countries, etc.) - **Unit Data**: Primary distillation unit operational data Example structure: ` Date,Total,Crude Quality,Refinery 2025-08-01,2500.8,Light Sweet,Marathon Petroleum Texas City 2025-08-01,1850.3,Heavy Sour,ExxonMobil Baytown `` Technical Notes - Focuses on Primary Distillation Units (CDU and Condensate Splitter) - Provides operational run data for selected refineries - Supports analysis by crude grades, countries, and refineries
kpler_get_refineries_utilization_rates
ChatGPTRefineries 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_report_by_slug
ChatGPTRetrieves 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_reports
ChatGPTRetrieves 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_routes
ChatGPTRoutes 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 geome…
kpler_get_short_content_by_slug
ChatGPTRetrieves 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_contents
ChatGPTRetrieves 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_soh_crossing
ChatGPTSOH 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_supply_demand
ChatGPTSupply 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_products
ChatGPTSupply 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_snapshots
ChatGPTSupply 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_trades
ChatGPTTrades 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 f…
kpler_get_vessel_ownership_and_particulars
ChatGPTVessel Ownership Retrieves vessel ownership and particulars data using custom GraphQL queries, providing access to ownership structure, technical specifications, and registry details for 220,000+ IMO vessels. Key Use Cases - Ownership Structure Analysis: Access detailed vessel ownership and corporate structure information - Technical Specifications Lookup: Retrieve comprehensive vessel particulars and technical data - Registry Information: Access vessel registration and compliance details - Custom Data Queries: Use GraphQL flexibility to retrieve specific data combinations Usage Guidance GraphQL Requirements - YOU MUST CALL get_vessel_ownership_and_particulars_graphql_schema before using this tool to know the query schema to follow - YOU MUST submit valid GraphQL request as the query parameter - YOU MUST ONLY REQUEST THE FIELDS YOU NEED in your GraphQL query for efficiency reasons Available Filter Operators The following operators are supported in where filters. YOU MUST ONLY USE THESE OPERATORS: | Operator | Description | Example | |----------|-------------|---------| | EQ | Equal to (exact match) | {field: "particulars.general.flag", op: EQ, values: ["Australia"]} | | NOT_EQ | Not equal to | {field: "management.registeredOwner.current.name", op: NOT_EQ, values: ["Evergreen Marine"]} | | GE | Greater than or equal to | {field: "particulars.tonnage.grossTonnage", op: GE, values: ["100000"]} | | LE | Less than or equal to | {field: "particulars.tonnage.deadweightTonnage", op: LE, values: ["50000"]} | | LIKE | Contains substring | {field: "particulars.general.name", op: LIKE, values: ["BW"]} | | IN | Matches any value in list | {field: "identifier.imo", op: IN, values: ["1234567", "2345678"]} | | NOT_IN | Excludes values in list | {field: "associatedCompanies.classificationSociety.current.name", op: NOT_IN, values: ["ABS", "Lloyd's Register"]} | IMPORTANT: - There is NO `GT` or `LT` operator. Use GE (>=) or LE (<=) instead. - Use EQ for exact company name matching. Use LIKE only for partial/substring matching. Combining Filters with Logical Operators You can combine multiple filters using AND or OR operators: ``graphql AND: All conditions must match where: { filters: [ {field: "particulars.general.flag", op: EQ, values: ["Panama"]}, {field: "particulars.tonnage.grossTonnage", op: GE, values: ["50000"]} ], operator: AND } OR: Any condition can match where: { filters: [ {field: "particulars.general.flag", op: EQ, values: ["Liberia"]}, {field: "particulars.general.flag", op: EQ, values: ["Panama"]} ], operator: OR } ` Common Filterable Field Paths **Identifier fields:** - identifier.imo - IMO number - identifier.mmsi - MMSI number - identifier.callSign - Radio call sign **Particulars fields:** - particulars.general.name - Vessel name - particulars.general.flag - Flag state (use mixed case: "Malta", "Panama", "Australia") - particulars.general.generalVesselType - Vessel type category - particulars.general.detailedVesselType - Specific vessel type - particulars.general.commercialFleet - Commercial fleet category - particulars.general.serviceStatus - Operational status (e.g., "IN_SERVICE") - particulars.hull.yearOfBuild - Year of construction - particulars.tonnage.grossTonnage - Gross tonnage - particulars.tonnage.deadweightTonnage - Deadweight tonnage **Management fields:** - management.registeredOwner.current.name - Current registered owner - management.beneficialOwner.current.name - Current beneficial owner - management.operator.current.name - Current operator - management.technicalManager.current.name - Current technical manager - management.commercialManager.current.name - Current commercial manager **Associated companies fields:** - associatedCompanies.classificationSociety.current.name - Classification society - associatedCompanies.shipBuilder.current.name - Ship builder - associatedCompanies.shipBuilder.current.country` - Ship builder country (use UPPERCASE: "CHINA", "SOUTH KOREA") #…
kpler_get_vessel_ownership_and_particulars_graphql_schema
ChatGPTVessel Ownership GraphQL Schema Retrieves the complete GraphQL schema structure for querying vessel ownership and particulars data, providing all available types, fields, descriptions, and filters. Key Use Cases - Schema Discovery: Get complete GraphQL schema structure before constructing queries - Field Reference: Understand available fields, types, and relationships for vessel data - Query Planning: Plan efficient GraphQL queries based on available schema structure - API Documentation: Access comprehensive field descriptions and available filters Usage Guidance Input Parameters Guidelines & Caveats Usage Pattern: - Always call this tool first to get schema structure before using vessel_ownership tool - Use returned schema to construct valid GraphQL queries Output Format Returns a complete GraphQL schema document including: - Types: All data types available for querying (Vessel, Particulars, Ownership, etc.) - Fields: Available fields within each type with descriptions - Queries: Root query types and available query methods - Filters: Available filtering options for queries - Relationships: How different data types are connected The schema follows standard GraphQL introspection format.
kpler_get_vessel_risks
ChatGPTVessel Compliance Risk Assessment Provides comprehensive compliance risk assessment for maritime vessels, focusing on sanctions, operational behavior, management oversight, and flag state compliance. Enables systematic screening to identify regulatory and reputational risks before business engagement. Key Use Cases - Pre-transaction screening: Assess vessel compliance before chartering or procurement decisions - Portfolio risk monitoring: Regular screening of existing vessel relationships and fleet exposure - Regulatory compliance: Ensure adherence to international sanctions and maritime regulations - Due diligence reporting: Generate compliance reports for stakeholders and regulatory authorities Usage Guidance Input Parameters Guidelines & Caveats Imos Paramater You MUST ABSOLUTELY NOT INVENT IMOs numbers!! Either you got them directly from the user or you got them from another kpler MCP tool output. Columns Parameter You must specify which columns to include in the response using the columns parameter to focus on relevant data fields. - Always start with `columns=["sanctionRisks"]` - This is the most critical compliance data - Only request additional columns if sanctions data is insufficient for your analysis - If you need more detail, then add: managementRisks, operationalRisks, or flagRisks - Never request all columns at once unless specifically required - If you request all compliance risks information, limit yourself to 10 IMOs Max Compliance Event Parameter By default, only the last compliance events are returned for each risk or sanction events (sanctioned cargos, sanctioned trades, ship-to-ship event...). You can set max_compliance_events to a higher value to get more information. ONLY USE IT IF YOU REALLY NEED THAT INFORMATION, as a lot of data can be returned. Data Range Parameter Always use `startDate`/`endDate` to limit historical risk data when recent assessment is sufficient - For ongoing monitoring: Focus on last 12-24 months of risk data - For comprehensive due diligence: Include the full historical period available - Historical data beyond 5 years may have limited coverage 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 Basic sanctions screening: ``python columns=["sanctionRisks"] imos=[1234567, 2345678, 3456789] ` **Enhanced risk assessment:** `python columns=["sanctionRisks", "operationalRisks"] imos=[1234567, 2345678] startDate="2024-01-01" endDate="2024-12-31" ` **Comprehensive due diligence:** `python columns=["sanctionRisks", "managementRisks", "operationalRisks", "flagRisks"] imos=[1234567] ` Output Format data contains a list of risk assessment objects for each requested IMO with the following fields: **Vessel Information Fields:** - imo - International Maritime Organization number - mmsi - Maritime Mobile Service Identity number - callsign - Vessel call sign - shipname - Vessel name - flag - Flag country or territory - countryCode - Two-letter country code representing the flag country - typeName - Detailed vessel type classification - typeSummary - Generic vessel type category - particulars - Technical specifications (gross tonnage, year of build) - vesselCompanies - Ownership and management company details with association dates **Compliance Risk Fields:** - sanctionRisks - Sanctions and embargo-related risks including sanctioned entities, flag state sanctions, and historical sanctions data - operationalRisks - Behavioral patterns including port calls, ship-to-ship transfers, AIS gaps, and dark activity patterns - managementRisks` - Management oversight including classification societies, P&I clubs, ISM managers, and port state contro…
kpler_get_zones
ChatGPTZones Tool Returns a list of all geographical zones supported for the Kpler MCP tools. Key Use Cases - Zone Discovery: Find all available geographical zones - Fallback Access: Alternative access to zones list - Query Validation: Verify valid zone names for API queries as backup method Usage Guidance Important: The full zones dataset is large. Use filters to reduce token usage: - Prefer specifying columns to reduce payload size - Use ancestor/descendant filters to narrow the hierarchy Name matching is exact. descendantName and ancestorName are exact filters, not a search: there is no substring or fuzzy matching. - If a name is not found, list by ancestorName (country or region) and pick the exact descendant_name from the result. Example: for "West Coast India", query ancestorName: "India" - Strip qualifiers that are not part of the place name: vessel classes (PMX, Capesize, VLCC), commodities, metrics, directions Output Format CSV text with requested columns. Example: ``csv Ancestor Id;Ancestor Name;Ancestor Type;Descendant Id;Descendant Name;Descendant Type 649;Northern America;continent;840;United States;country ``
kpler_get_ais_historical
Claudekpler_get_ais_latest
Claudekpler_get_arbitrage_benchmarks
Claudekpler_get_arbitrage_combinations
Claudekpler_get_arbitrage_products
Claudekpler_get_arbitrage_regions
Claudekpler_get_arbitrage_timeseries
Claudekpler_get_arbitrage_timeseries_rolling
Claudekpler_get_cargo_fleet_metrics
Claudekpler_get_compliance_screening
Claudekpler_get_congestion_series
Claudekpler_get_congestion_vessels
Claudekpler_get_crude_inventories
Claudekpler_get_cushing_drones_inventories
Claudekpler_get_fleet_development_series
Claudekpler_get_fleet_development_vessels
Claudekpler_get_fleet_metrics_vessels
Claudekpler_get_fleet_utilization_series
Claudekpler_get_fleet_utilization_vessels
Claudekpler_get_flows
Claudekpler_get_freight_fixtures
Claudekpler_get_freight_metrics_series_alt
Claudekpler_get_freight_metrics_vessels_alt
Claudekpler_get_insights_search_filters
Claudekpler_get_lng_capacities
Claudekpler_get_lng_diversions
Claudekpler_get_lng_installations
Claudekpler_get_lng_inventories
Claudekpler_get_lng_outages
Claudekpler_get_lng_trains_phases
Claudekpler_get_lng_utilizations
Claudekpler_get_lng_utilizations_trends
Claudekpler_get_next_destination
Claudekpler_get_port_calls_v1
Claudekpler_get_products
Claudekpler_get_refineries_crude_co_imports
Claudekpler_get_refineries_margins
Claudekpler_get_refineries_particulars
Claudekpler_get_refineries_primary_distillation
Claudekpler_get_refineries_utilization_rates
Claudekpler_get_report_by_slug
Claudekpler_get_reports
Claudekpler_get_routes
Claudekpler_get_short_content_by_slug
Claudekpler_get_short_contents
Claudekpler_get_single_vessel_position
Claudekpler_get_soh_crossing
Claudekpler_get_supply_demand
Claudekpler_get_supply_demand_products
Claudekpler_get_supply_demand_snapshots
Claudekpler_get_trades
Claudekpler_get_vessel_ownership_and_particulars
Claudekpler_get_vessel_ownership_and_particulars_graphql_schema
Claudekpler_get_vessel_risks
Claudekpler_get_zones
Claude
