Direct Access REST API for Kpler Freight analytics across the Liquids, Gas, and Dry platforms - freight metrics, fleet metrics, congestion, and ballast capacity aggregations for tanker, gas carrier, and bulker fleets. Served from the same per-platform hosts (api.kpler.com, api-lng.kpler.com, api-lpg.kpler.com, api-dry.kpler.com).
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.