openapi: 3.0.3
info:
  title: Kpler Direct Access Aggregations 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: Aggregations
  description: Flows and other aggregated series.
paths:
  /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'
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/