openapi: 3.0.3 info: title: Kpler Direct Access API version: '1.0' description: >- REST API for the Kpler commodities intelligence platform, giving programmatic access to the same trades, flows, and vessel data available in the Kpler terminal. The same Direct Access endpoint surface is served per commodity platform from four hosts - Liquids (api.kpler.com), LNG (api-lng.kpler.com), LPG (api-lpg.kpler.com), and Dry (api-dry.kpler.com). ACCESS MODEL - Kpler APIs are customer-gated. Documentation (Direct Access user guides at *.dev.kpler.com and the developer portal at developers.kpler.com) and the Python SDK are public, but calling the API requires client credentials issued with a commercial Kpler subscription. ENDPOINTS MODELED - x-endpoints-modeled: this document describes only the endpoints and parameters confirmed from Kpler's public Direct Access guides, the public Python SDK (python-sdk.dev.kpler.com), and Kpler's public Postman workspace, including the documented example request https://api-dry.kpler.com/v1/trades?size=6&columns=trade_id,vessel_name,start,end&fromZones=Europe&toZones=Asia. The full parameter and response surface is only visible to authenticated customers, so responses are modeled loosely and additional documented endpoint families (port calls, ship-to-ship transfers, storage, contracts, prices, outages, fleet metrics, congestion, inventories, refineries, products, installations, zones, players) are noted but not fully modeled here. Nothing in this document is fabricated beyond that abridgement. contact: name: Kpler Customer Success email: cs@kpler.com url: https://developers.kpler.com/ x-access-model: customer-gated x-endpoints-modeled: true externalDocs: description: Kpler Developer Portal url: https://developers.kpler.com/ servers: - url: https://api.kpler.com description: Liquids platform (crude, CPP, DPP) - url: https://api-lng.kpler.com description: LNG platform - url: https://api-lpg.kpler.com description: LPG platform - url: https://api-dry.kpler.com description: Dry platform (coal and dry bulk) security: - basicAuth: [] - bearerAuth: [] tags: - name: Authentication - name: Facts description: Trades, vessels, and other observed fact data. - name: Aggregations description: Flows and other aggregated series. paths: /login: post: operationId: login tags: - Authentication summary: Exchange Kpler client credentials for a bearer token description: >- Returns an authorization token used as a bearer pass for subsequent API requests. Basic Authentication with encoded credentials in the Authorization header is also supported directly on data endpoints, without calling /login. security: [] requestBody: required: true content: application/json: schema: type: object properties: email: type: string description: Kpler account email. password: type: string description: Kpler account password. required: - email - password responses: '200': description: Authorization token issued. content: application/json: schema: type: object properties: token: type: string '401': description: Invalid credentials. /v1/trades: get: operationId: getTrades tags: - Facts summary: List trades description: >- Returns cargo trades observed on the platform, with selectable columns (for example trade_id, vessel_name, start, end) and origin/destination zone filters. Kpler recommends querying this endpoint no more than once per hour and running queries sequentially. parameters: - $ref: '#/components/parameters/columns' - $ref: '#/components/parameters/size' - $ref: '#/components/parameters/fromZones' - $ref: '#/components/parameters/toZones' - $ref: '#/components/parameters/startDate' - $ref: '#/components/parameters/endDate' - $ref: '#/components/parameters/products' responses: '200': $ref: '#/components/responses/TabularData' '401': $ref: '#/components/responses/Unauthorized' /v1/flows: get: operationId: getFlows tags: - Aggregations summary: Aggregated commodity flows description: >- Returns aggregated flows for a point of interest (installation or zone) on a daily, weekly, weekly EIA (US), monthly, or yearly basis. Documented SDK-level filters include flow direction, split, granularity, date range, from/to installations and zones, products, unit, intra-country and intra-region inclusion, forecasts, and vessel types. parameters: - $ref: '#/components/parameters/columns' - $ref: '#/components/parameters/size' - $ref: '#/components/parameters/fromZones' - $ref: '#/components/parameters/toZones' - $ref: '#/components/parameters/startDate' - $ref: '#/components/parameters/endDate' - $ref: '#/components/parameters/products' - name: granularity in: query description: Aggregation granularity (daily, weekly, monthly, yearly). schema: type: string - name: flowDirection in: query description: Direction of the flow relative to the point of interest (import/export). schema: type: string - name: split in: query description: Dimension to split the aggregation by (for example product, origin, destination). schema: type: string responses: '200': $ref: '#/components/responses/TabularData' '401': $ref: '#/components/responses/Unauthorized' /v1/vessels: get: operationId: getVessels tags: - Facts summary: List vessels description: >- Returns vessel data for the platform fleet - vessel identity and characteristics as tracked by Kpler. Kpler recommends querying this endpoint no more than once per hour. parameters: - $ref: '#/components/parameters/columns' - $ref: '#/components/parameters/size' responses: '200': $ref: '#/components/responses/TabularData' '401': $ref: '#/components/responses/Unauthorized' components: securitySchemes: basicAuth: type: http scheme: basic description: Encoded Kpler client credentials in the Authorization header. bearerAuth: type: http scheme: bearer description: Token obtained from the /login endpoint. parameters: columns: name: columns in: query description: Comma-separated list of columns to return (for example trade_id,vessel_name,start,end). schema: type: string size: name: size in: query description: Maximum number of rows to return. schema: type: integer fromZones: name: fromZones in: query description: Origin zone filter (for example Europe). schema: type: string toZones: name: toZones in: query description: Destination zone filter (for example Asia). schema: type: string startDate: name: startDate in: query description: Start of the date range. schema: type: string format: date endDate: name: endDate in: query description: End of the date range. schema: type: string format: date products: name: products in: query description: Product filter (for example crude, gasoline, LNG). schema: type: string responses: TabularData: description: >- Tabular result set. Responses are delivered as delimited tabular data (consumed as DataFrames by the official Python SDK); exact response schemas are documented in the customer-gated Direct Access guides. content: text/csv: schema: type: string Unauthorized: description: Missing or invalid Kpler client credentials.