Welcome to the Kpler API, to help you decide which method of data retrieval to use and how to get started, please see the sections below.
We also have a dedicated API help centre available here, and recordings of how to use the API can be found here.
REST API vs SDK
The two methods of accessing the Kpler API are via our REST API and our Python SDK - the details of both are listed below:
Feature | REST API | SDK |
Language | Any | Python 3.7+ |
Output | Semicolon separated CSV (JSON for /trades/updates) | |
Authentication | Basic or Token | Basic only |
Differences between the REST API and SDK
Most endpoints available on the REST API are or will also be available on the Python SDK, therefore it remains a personal preference; however some of the key differences are:
The SDK has built in helper classes to construct the queries for you
The REST API can be implemented in any language
The SDK can be used alongside Python libraries like NumPy, Matplotlib etc to manipulate Kpler data in situ.
The REST API can be easily plumbed into Excel, PowerBI, Tableau etc.
Getting Started: REST API
The REST API documentation can be found using this link and selecting the relevant commodity you wish to access.
Authentication
There are two ways to authenticate on the Kpler REST API, by token authentication or by basic authentication using the same username and password as you use if you use other Kpler products.
To retrieve your token, following the steps on the API documentation, simply create a POST request to the /v1/login endpoint with your username and password contained in the request body like so:
{
"email": "your_mail@example.com",
"password": "your_password"
}
After creating your token you can include it in the request headers using the format
{
"Authorization" : "Bearer yourToken"
}
Otherwise, to use basic authentication simply add the base64 encoded version of your credentials in the format: your_username:your_password and add the following JSON to your header.
{
"Authorization": "Basic Y3VzdG9tZXJAZW1haWwuY29tOm1Zc3RSb25nUDRzc3cwUmQ="
}
From then you're ready to use the documentation to create the URLs to be pointed at our REST API!
Getting Started - Python SDK
The Kpler SDK documentation can be accessed using this link.
First things first, let's get the SDK installed using pip (follow this link if you need help with getting your environment created) using the code:
pip install kpler.sdk
Then, using basic authentication, set up your config at the top of your script or Jupyter notebook.
from kpler.sdk.configuration import Configuration
from kpler.sdk import Platform
config = Configuration(Platform.Liquids, "<your email>", "<your password>")
Note: you can select other platforms using Platform.LNG, Platform.LPG or Platform.Dry
Note: It is not required to include the <> in your credentials.
Now you're ready to use the documentation to create your first query - don't forget to use the output from the helper class - a little tip, you can use import pandas as pd after installing Pandas to use all of the native Pandas methods on the returned DataFrame - otherwise you can simply print the DataFrame to see the results.
Security
In order to use the Excel add-in or the API/Python SDK, your IT must allow HTTPS requests (port 443) to the following addresses/IPs:
api.kpler.com : 13.248.154.30/76.223.25.242
api-lng.kpler.com : 13.248.192.13/76.223.83.202
api-lpg.kpler.com : 13.248.194.59/76.223.79.241
api-dry.kpler.com : 75.2.83.42/99.83.252.221
Once this is completed, you should be able to use the Kpler API, SDK or Excel Add-In as usual. If you're still faced with error messages after completing these steps, please reach out to cs@kpler.com with the query you're using and any error messages to allow us to investigate further for you.
Notes and FAQ
If you require a mapping document for geographical entities or our commodity, products and grades tree please reach out to the Customer Success team on cs@kpler.com as these cannot currently be queried through the API or SDK.
There is a returned record limit of 100,000 records on LNG, LPG and Dry, 200,000 on Liquids.
There is a query rate limit of 300/minute - please ensure adequate timing breaks to ensure all queries stay under this limit.
You can select your preferred language from the top of the REST API docs to see example code in your language - this might make it easier for you to get started!
For a list of Frequently Asked Questions on our API endpoints please check out this article.
In order to upgrade the Python SDK you can use the code:
pip install kpler.sdk --upgrade
To be automatically informed of updates, simply add:
log_level="INFO"
to the end of your config object, otherwise Kpler will notify you about new SDK releases.Tokens for authentication periodically expire, you can repeat the steps listed above to generate a new token.
If you have any questions or need help getting set up, just give our Customer Success team an email to cs@kpler.com and someone will be happy to lend a hand.