Introduction

This is a REST API provided by SparkCommodities. it has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON API responses, and uses standard HTTP response codes, authentication, and verbs.

Language bindings in Shell(curl) and Python are provided; you can view code examples on the right.

Authentication

Spark Commodities uses API tokens to allow access to the API.

You can retrieve your API token from the user profile menu (top right of your screen) . By default, the API token has limited access to our data, please contact us if you need more privileges.

Spark Commodities expects that the API token is included in all API requests to the server in a header that looks like the following:

Authorization: Token {your-api-token}

Please replace {your-api-token} with your API token.

JSON:API

JSON:API response example:

{
    "data": [
        {
            "id": "spark25",
            "type": "contract",
            "attributes": {
                "fullName": "Spark25 Pacific 160 TFDE",
                "tickerSymbol": "Spark25",
            },
            "links": [
                {
                    "href": "https://api.sparkcommodities.com/v1/contracts/spark25",
                    "rel": "self"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "https://api.sparkcommodities.com/v1/contracts/",
            "rel": "self"
        }
    ]
}

JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.

JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

JSON:API requires the use of the JSON:API media type (application/vnd.api+json) for exchanging data.

A JSON object MUST be at the root of every JSON:API request and response containing data. This object defines a document’s “top level”.

A response may contain at one of the following top-level members:

data: the document’s “primary data”
errors: an array of error objects

A response may also contain a links object related to the primary data.

Errors

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

Some 4xx errors that could be handled programmatically (e.g., an invalid token was provided) include an error code that briefly explains the error reported.

Error example:

{
    "errors": [
        {
            "code": "invalid-token",
            "message": "token provided is invalid."
        }
    ]
}

HTTP Status Code

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- You don't have access permission to the requested resource.
404	Not Found -- The requested resource could not be found.
405	Method Not Allowed -- You tried to access with an invalid method.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Error Types

Error Code	Meaning
bad-request	Bad Request Error.
no-token-provided	Token was not provided.
invalid-token	Provided token is invalid.
permission-denied	You do not have permission to perform this action.
resource-not-found	Requested resource not found.
invalid-accept-header	Clients that include the JSON:API media type in their Accept header MUST specify the media type there at least once without any media type parameters.

Contracts

A JSON API endpoint provides Spark contracts info. Please refer to our Methodology and Specifications Guide for more details.

Please note that we don't update contracts frequently. lastUpdatedAt can be used to detect changes.

Get Contracts

Returns the list of all Spark contracts.

curl "http://api.sparkcommodities.com/v1/contracts" \
--header "Authorization: Token ${SP_API_TOKEN}"

import os
import urllib.request

token = os.getenv("SP_API_TOKEN", "please-set-your-api-token")

url = "http://api.sparkcommodities.com/v1/contracts"
http_headers = {'Authorization': f"Token {token}"}

request = urllib.request.Request(url, headers=http_headers)
with urllib.request.urlopen(request) as response:
    print(f"Response: {response.read()}")

Response example:

{
  "data": [
    {
      "attributes": {
          "commodity": "lng",
          "description": "Pacific 160 TFDE",
          "freightDuration": "25",
          "fullDescription": "* 160,000m3 TFDE\r\n* 25 days duration\r\n* Cold delivery\r\n* Within basin re-delivery\r\n* 100% fuel for ballast bonus\r\n* 0.1% boil off\r\n* 17 knots\r\n* Max 20 years",
          "fullName": "Spark25 Pacific 160 TFDE",
          "lastUpdatedAt": "2019-04-17T07:39:04+0000",
          "tickerSymbol": "Spark25",
          "type": "freight"   
      },
      "id": "spark25",
      "links": [
        {
          "href": "https://api.sparkcommodities.com/v1/contracts/spark25",
          "rel": "self"
        },
        {
          "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases",
          "rel": "priceReleases"
        },
        {
          "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/first",
          "rel": "firstPriceRelease"
        },
        {
          "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/last",
          "rel": "lastPriceRelease"
        }
      ],
      "type": "contract"
    }
  ],
  "links": [
      {
          "href": "https://api.sparkcommodities.com/v1/contracts",
          "rel": "self"
      }
  ]
}

HTTP Request

GET http://api.sparkcommodities.com/v1/contracts

Get Contract Details

Returns the details of the requested contract.

curl 'http://api.sparkcommodities.com/v1/contracts/{contract-id}' \
--header "Authorization: Token ${SP_API_TOKEN}"

import os
import urllib.request

token = os.getenv("SP_API_TOKEN", "please-set-your-api-token")

contract_id = "spark25"

url = f"http://api.sparkcommodities.com/v1/contracts/{contract_id}"
http_headers = {'Authorization': f"Token {token}"}

request = urllib.request.Request(url, headers=http_headers)
with urllib.request.urlopen(request) as response:
    print(f"Response: {response.read()}")

Response example:

{
  "data": {
    "attributes": {
        "commodity": "lng",
        "description": "Pacific 160 TFDE",
        "freightDuration": "25",
        "fullDescription": "* 160,000m3 TFDE\r\n* 25 days duration\r\n* Cold delivery\r\n* Within basin re-delivery\r\n* 100% fuel for ballast bonus\r\n* 0.1% boil off\r\n* 17 knots\r\n* Max 20 years",
        "fullName": "Spark25 Pacific 160 TFDE",
        "lastUpdatedAt": "2019-04-17T07:39:04+0000",
        "tickerSymbol": "Spark25",
        "type": "freight"  
    },
    "id": "spark25",
    "links": [
      {
        "href": "https://api.sparkcommodities.com/v1/contracts/spark25",
        "rel": "self"
      },
      {
        "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases",
        "rel": "priceReleases"
      },
      {
        "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/first",
        "rel": "firstPriceRelease"
      },
      {
        "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/last",
        "rel": "lastPriceRelease"
      }
    ],
    "type": "contract"
  },
  "links": [
    {
      "href": "https://api.sparkcommodities.com/v1/contracts/spark25",
      "rel": "self"
    }
  ]
}

HTTP Request

GET http://api.sparkcommodities.com/v1/contracts/{contract-id}

Paths

Path	Description
contract-id	a Spark contract id from the `contracts` API, e.g. 'spark25'

Price Releases

Spark Commodities releases prices several times per week, which is called Price Release. Please read our Methodology and Specifications Guide for more details.

Get Prices Releases

Returns a list of price release summaries.

curl 'http://api.sparkcommodities.com/v1/contracts/{contract-id}/price-releases' \
--header "Authorization: Token ${SP_API_TOKEN}"

import os
import urllib.request

token = os.getenv("SP_API_TOKEN", "please-set-your-api-token")

contract_id = "spark25"

url = f"http://api.sparkcommodities.com/v1/contracts/{contract_id}/price-releases"
http_headers = {'Authorization': f"Token {token}"}

request = urllib.request.Request(url, headers=http_headers)
with urllib.request.urlopen(request) as response:
    print(f"Response: {response.read()}")

Response example:

{
  "data": [
    {
      "attributes": {
        "nextReleaseDate": "2019-06-04",
        "previousReleaseDate": "2019-05-28",
        "publishedAt": "2019-05-30",
        "submissionsCloseAt": "2019-05-30T10:00:00+0000",
        "submissionsOpenAt": "2019-05-30T08:00:00+0000"
      },
      "id": "2019-05-30",
      "links": [
        {
          "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/2019-05-30",
          "rel": "self"
        },
        {
          "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/2019-06-04",
          "rel": "next"
        },
        {
          "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/2019-05-28",
          "rel": "prev"
        }
      ],
      "type": "priceRelease"
    }
  ]
}

HTTP Request

GET http://api.sparkcommodities.com/v1/contracts/{contract-id}/price-releases

Paths

Path	Description
contract-id	a Spark contract id from the `contracts` API, e.g. 'spark25'

Get Price Release Details

Returns the details of a price release.

A PriceRelease includes one or more Segments(choices are: spot, frontMonth, forward).

Each Segment might have one or more Dimensions. Dimension is a collection of categorized Prices, such as: Spark Prices, Previous Spark Prices etc,.

A PriceRelease includes a list of Legend. A Legend contains the description of Dimension.

Premium Access

One of the first premium offerings is the PriceRelease API which provides access to the full Spark data history.

Non premium user can only fetch the latest PriceRelease dataset.

Please contact us to enquire about premium access.

curl 'http://api.sparkcommodities.com/v1/contracts/{contract-id}/price-releases/{release-date}' \
--header "Authorization: Token ${SP_API_TOKEN}"

import os
import urllib.request

token = os.getenv("SP_API_TOKEN", "please-set-your-api-token")

contract_id = "spark25"
release_date = "2019-11-29"

url = f"http://api.sparkcommodities.com/v1/contracts/{contract_id}/price-releases/{release_date}"
http_headers = {'Authorization': f"Token {token}"}

request = urllib.request.Request(url, headers=http_headers)
with urllib.request.urlopen(request) as response:
    print(f"Response: {response.read()}")

Simplified response example:

{
  "data": {
    "attributes": {
      "legends": [
        {
          "description": "Spark Price for Spark25S Pacific 160 TFDE contract",
          "name": "Spark25",
          "type": "spark_prices"
        },
        {
          "description": "Previous Spark25 release (Tuesday, November 26, 2019)",
          "name": "Prev",
          "type": "previous_spark_prices"
        }
      ],
      "nextReleaseDate": null,
      "previousReleaseDate": "2019-11-26",
      "publishedAt": "2019-11-29T10:02:34+0000",
      "segments": {
        "forward": null,
        "frontMonth": null,
        "spot": {
          "deliveryPeriods": [
            { "dayFrom": "2019-12-14", "dayTo": "2020-01-13", "monthIndex": 0 }
          ],
          "dimensions": [
            {
              "liquidity": null,
              "name": "Spark25S",
              "rank": 0,
              "type": "spark_prices",
              "values": [
                {
                  "freight": { "mmbtu": "0.12", "usdPerDay": "123456.00" },
                  "monthIndex": 0
                }
              ]
            },
            {
              "liquidity": null,
              "name": "PrevS",
              "rank": 1,
              "type": "previous_spark_prices",
              "values": [
                {
                  "freight": { "mmbtu": "0.12", "usdPerDay": "123456.00" },
                  "monthIndex": 0
                }
              ]
            }
          ],
          "isSubmitter": false,
          "periodType": "days",
          "releaseDate": "2019-11-29"
        }
      },
      "submissionsCloseAt": "2019-11-29T10:00:00+0000",
      "submissionsOpenAt": "2019-11-29T08:00:00+0000",
    },
    "id": "2019-11-29",
    "type": "priceRelease"
  },
  "links": [
    {
      "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/2019-11-29",
      "rel": "self"
    },
    {
      "href": "https://api.sparkcommodities.com/v1/contracts/spark25/price-releases/2019-11-26",
      "rel": "prev"
    }
  ]
}

HTTP Request

GET http://api.sparkcommodities.com/v1/contracts/{contract-id}/price-releases/{release-date}

Paths

Path	Description
contract-id	a Spark contract id from the `contracts` API, e.g. 'spark25'
release-date	an actual release date from the `price-releases` API or shortcut `first`, `last` (to get the first/last released data)

Spark premium APIs

We're excited to introduce Spark premium APIs.

Our new premium APIs bring the reliability, stability and access of our enterprise APIs to our broader developer ecosystem for the first time.

At this stage, the first premium offerings include full access to Spark historical data.

Please contact us to enquire about premium access.

Support

If you need help, please contact us.