NAV Navbar
shell python

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}

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:

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.