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:
- 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.