API Request

Overview of Functionality

To access the data, you will need to provide the correct credentials using an OAuth2 client (like a key or password). To create your client credentials, visit our Guide on the platform or in the API documentation.

Currently, there are four main access points for the API:

• Contracts (Cargo and Freight)
• Routes (Freight)
• Netbacks (Cargo)
• Access

Each of these access points have a unique URL associated with them, which is used to call the according data. These URLs all have the same base

https://api.sparkcommodities.com

denoted from hereon as ~.

Spark offers a wide range of data products within these categories, and so parameters can be added to each of these access point URLs to specify the exact data required. As such, the API provides all the customisability of the Spark platform in terms of optional parameters (e.g. contract type, vessel type etc.). Each access point, and their associated parameters, will be explained in-depth in this guide.

It should be noted that trial users can only access 2 weeks worth of historical data. To get full access to the Spark Historical dataset, please contact us at info@sparkcommodities.com to discuss upgrading to Premium.

NOTE

From hereon, the {} included in URLs in this document are to highlight where to insert custom parameters (e.g. vessel type, congestion delays etc.) and should be omitted in the actual URL

---

Authentication

To interact with the Spark Commodities API, your application must authenticate. You should use OAuth v2.0 to authenticate to the Spark REST API. Authenticating requires the following steps:

1. Create an OAuth2 Client

You must first create an OAuth2 client. This is a one-time operation, and each OAuth2 client provides you with a Client ID and a Client Secret. Visit our application to manage your clients. Once your OAuth2 client is set up, you can download your Client ID and Client Secret as a CSV.

Note 1

Client ID and Client Secret must be kept confidential in storage.

Note 2

OAuth2 clients are owned by an organisation and not a user. This is to ensure that personnel changes are easier to manage in the future.

2. Generate an Access Token

TLDR

Create an Access Token with querying /oauth/token

Detailed version

After obtaining a Client ID and a Client Secret, you can make an API call to obtain an access token using the Create an Access Token endpoint.

To create an access token, you will have to specify a scope: this is a list of permissions your application requires.

An access token is an opaque string that denotes who has authorized which permissions to the Spark API. This access token has short-lived access (30 minutes).

When the Spark API issues a new access token, it also generates a refresh token that expires after a very long time (this is also returned in the API response). When your access token expires, your application can use the refresh token to obtain a new access token. It can do this behind the scenes, and without the user’s involvement, so that it’s a seamless process to the user.

Available scopes

• read:prices: Reading Spark contracts and price releases. Requires an LNG Freight or an LNG Cargo subscription.
• read:routes: Reading Spark routes. Requires an LNG Freight subscription.
• read:access: Reading Spark Access data. Requires an Access subscription.
• read:netbacks: Reading Spark Netbacks data. Requires an LNG Cargo subscription.

Deprecation note

Scope read:lng-freight-prices is now deprecated. It has been replaced by read:prices. You can still use it, but its support will be dropped at the latest on 2022-12-31.

3. Make Authenticated Requests

To authenticate subsequent API requests, you have to provide a valid access token in an HTTP header:

GET https://api.sparkcommodities.com/v1.0/contracts/ HTTP/1.1
HOST: my-server
Accept: application/json
Authorization: Bearer <access_token>

Note

All requests must be made over HTTPS.