openapi: 3.0.3
info:
  title: Kpler Direct Access Aggregations Facts 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
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: Facts
  description: Trades, vessels, and other observed fact data.
paths:
  /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/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:
  parameters:
    startDate:
      name: startDate
      in: query
      description: Start 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
    toZones:
      name: toZones
      in: query
      description: Destination zone filter (for example Asia).
      schema:
        type: string
    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
    endDate:
      name: endDate
      in: query
      description: End of the date range.
      schema:
        type: string
        format: date
  responses:
    Unauthorized:
      description: Missing or invalid Kpler client credentials.
    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
  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.
externalDocs:
  description: Kpler Developer Portal
  url: https://developers.kpler.com/