Primary Commodity Prices API
About the API
The Intratec Primary Commodity Prices API provides direct access to the prices released under the Intratec Primary Commodity Prices subscription.
This RESTful API provides a simple interface for a timely and efficient retrieval of the most current data available.
The results from Primary Commodity Prices API data queries will return in JavaScript Object Notation (JSON) format, that can be easily plugged into the formatting file or graphic of choice.
API Core Concepts
Price Assessment
Price Assessment is a specific monthly time-series comprising prices since Jan/2007 for a given commodity in a location under specific terms. A price assessment comprises historical values and price forecasts when available.
Price assessment description example: "Diammonium Phosphate, export spot price, fob, US Gulf"
Price Assessment Code
Each price assessment is associated with a unique identifier code, which is used to retrieve the price assessment data in the Intratec Primary Commodity Prices API.
Price assessment code example: "91201-1-5"
Intratec team continuously works to add new price assessments to Intratec Primary Commodity Prices. New price assessments may approach the same commodity and location, but different markets or negotiation terms, thus having a different code.
Intratec suggests that the price assessment code is used to identify the price assessment at the user end to ensure consistency of data as new price assessments come out.
If a price series basis significantly changes, the price assessment will be discontinued, and another price assessment will be created with a new assessment code.
There can be, however, changes that will not result in the creation of a new assessment, such as specific data points revision or minor value revisions throughout the entire series due to methodology adjustments.
Price Data Request
A price data request is the act of requesting data from a price assessment through the API. It is important to note that a price data request is different from an API call.
One API call may include multiple price data requests. In a single API call, the user can specify multiple price assessment codes to retrieve data from various price assessments.
Understanding the difference between a price data request and an API call is key, as some API limits are based on the number of price data requests rather than the number of API calls.
Available Datasets
Intratec Primary Commodity Prices are accessible via an annual subscription in which subscribers have access to trustworthy and independent pricing data of 210+ commodities, grouped into 7 datasets based on industry sectors:
- Alcohols & Organics Acids
- Aromatics & Derivatives
- Fertilizers & Gases
- Inorganic Chemicals
- Metals & Mining
- Olefins & Derivatives
- Polymers
The API will only access datasets included in the user's subscription. The list of available price assessments under the user's subscription can be retrieved via Intratec Primary Commodity Prices API.
Data Releases
New data points are released monthly according to the schedule provided at Intratec Data Release Schedule.
Intratec recommends scheduling the client application to query values once a month on a predefined date.
For selecting the date that best fits the company's needs, mind the Scheduled Maintenance section.
Getting Started with APIs
This section gives the basic information needed to start working with the Intratec Primary Commodity Prices API.
The use of Intratec Primary Commodity Prices API is subject to having a user set with the Developer role, which is the one that has access to the API. Learn how to set user with the Developer role.
Intratec strongly recommends that the developer role is assigned to a shared corporate email address, ensuring that (i) the API access can be shared among multiple team members and (ii) API access is not interrupted if a team member leaves the company.
Available APIs
The following public APIs are available for use to authorized accounts:
Access Token API
This API is used to authenticate the calling service. It will also generate an access token needed when calling other Intratec APIs for authorization purposes. The access token is a JSON Web Token (JWT).
This API comprises a single operation:
Intratec Primary Commodity Prices API
The base URL for the Primary Commodity Prices API is https://intratec.azure-api.net/commodity_price
It comprises the following operations:
API Flow
Follow the steps below to use the Intratec Primary Commodity Prices API effectively. The steps cover everything from authentication to making requests. Adhering to this structured approach guarantees optimal performance and reliable access to data.
Need help? Have any issues setting up the API or find any error? Please contact us.
Step 1: Generate an Access Token
Use the Access Token API to authenticate the account credentials and generate the access token needed to use the Intratec Primary Commodity Prices API.
Intratec APIs access tokens have a limited lifetime of two hours. After this time, the user must obtain a new access token by executing the Access Token API again.
Step 2: List Available Price Assessments
Use the Series Info operation from Intratec Primary Commodity Prices API to list the available price assessments and their respective metadata. Additionally, the list includes the price assessment codes, which are required to query prices.
The price assessment metadata comprises, for instance, complete description; currency and unit of measurement in which data is displayed by default; other available currencies and units of measurement for retrieving data; and availability of data forecasts. It also informs whether historical data has been revised.
This operation also provides the date of the most recent update to the price assessment data. This information can be used to determine if new price data is available and whether new price data requests should be made.
Tip 1: Utilize the price assessment code to distinguish price assessments at the user end, ensuring data consistency if new price assessments are created. There's also the option to link this code to an internal description to better suit the company's requirements.
Tip 2: Use this operation to check for changes to existing price assessments or new price assessment additions.
Step 3: Query Price Assessment Values
After selecting the assessment codes, use the Intratec Primary Commodity Prices API to query the price assessment values. There are two different operations for that purpose:
Series Values: This operation retrieves prices for the most recently concluded month, as well as for the previous 12 months, totaling 13 months of historical data. Additionally, it provides price forecasts for the subsequent 6 months (when provided by Intratec). It is advisable to use this operation after each new data release to ensure access to the latest information, as it is generally faster than Series Values History.
Series Values History: This operation's availability is subject to the Data Automation Option of the API plan. It retrieves monthly historical prices up to the most recently concluded month. It also includes price forecasts for the subsequent 6 months when available. It should be used when initially setting up data in the client application or when historical data is reviewed by Intratec.
Both operations support up to 40 price assessment codes and customization of both currency and unit of measurement for data display.
Tip 3: Use the Series Info operation to check for any revisions to the price assessment data. Based on this information, choose between using Series Values or Series Values History to retrieve data from a specific price assessment.
Query Limits
Understanding the query limits of the API is essential to efficiently manage usage and avoid interruptions. This section outlines the daily and monthly quotas for various operations, as well as specific restrictions on price data series requests based on the Data Automation Option.
Need help? Have any issues setting up the API or find any error? Please contact us.
Daily Quotas
All operations performed using the API are subject to a daily quota of 8,000 requests.
Monthly Quotas
In addition to the daily quota, some operations have additional monthly limits. The "Series Info" operation is limited to 10,000 requests per month.
The operations Series Values and Series Values History are also restricted based on the number of price data requests that can be made per dataset in a month. This limit is based on the selected Data Automation Option.
All monthly quotas are reset when new data are released at the beginning of each month, according to the Intratec Release Schedule. Attempting to request more codes than the plan allows will result in an error.
Monitoring Usage
To help stay within the plan's limits, the user can monitor the usage via the Data Limits operation. This will provide information on the current data series requests usage, as shown in the Examples section.
Handling Quota Exceedances
If the user exceeds the monthly quota or requests more price data series than allowed by the plan, the user will receive an error response indicating the quota limit has been reached. Here are some best practices to manage and optimize the usage:
- Monitor Usage via Data Limits operation: Regularly check the usage to stay within the limits.
- Data Automation Option: If the usage frequently exceeds the monthly limits, consider upgrading the plan to accommodate higher demand.
By understanding and adhering to these query limits, users can ensure seamless and uninterrupted access to the API services.
Price Data Requests Limit Example
Consider the following scenario:
Total Request Limit:
- 500 price data requests for the 'Polymers' dataset.
- 500 price data requests for the 'Inorganic Chemicals' dataset.
The user then proceeds to make the following requests:
Series Values Operation:
- 10 price data requests of the 'Polymers' dataset.
- 5 price data requests of the 'Inorganic Chemicals' dataset.
Series Values History Request:
- 15 price data requests of the 'Inorganic Chemicals' dataset.
After these requests, the user will have 490 remaining price data requests in the 'Polymers' dataset and 480 remaining in the 'Inorganic Chemicals' dataset.
Rate limiting also applies to API requests. Users can make up to 10 requests per second per operation.
API Sandbox
The Primary Commodity Prices API Sandbox environment enables developers to use the API without any monthly restrictions on the number of requested codes.
The API Sandbox comprises different end points that will process requests exactly like the actual API providing responses with the exact same format, allowing developers to make tests and configure their applications.
The monthly prices returned by the API Sandbox are dummy negative values.
The API Sandbox is subject to the following daily quotas:
- Sandbox – Series Info: 8,000 requests/day
- Sandbox – Series Values: 16,000 requests/day
- Sandbox – Series Values History: 16,000 requests/day
Example API Queries
The examples below are based on the Intratec Primary Commodity Prices API Sandbox.
To query actual values, simply remove /sandbox from the URL in the example.
This section aims to provide simple usage examples of Intratec Primary Commodity Prices API. Users can test and use APIs productively in their own instances using a REST API client of choice.
For detailed mapping information and Python implementation examples, please refer to the Developer Portal. Links are provided after each example.
Generating Access Token
To generate this token, the user should send a POST request like the following:
Example Request:
POST https://intratec.azure-api.net/access_token/v1 HTTP/1.1
Host: intratec.azure-api.net
Content-Type: application/json
{"password":"password","username":"john.doe@intratec.us"}Example Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6Nfg"
}For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Listing Available Price Assessments
To send a request to obtain the available assessments codes and details.
Example Request:
GET https://intratec.azure-api.net/commodity_price/v1/sandbox/export/series HTTP/1.1
Host: intratec.azure-api.net
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6NfgExample Response:
[{
"area": "US Gulf",
"assessment": "Diammonium Phosphate, export spot price, fob, US Gulf",
"available_currencies": "USD, USD cent, EUR, CNY, JPY, GBP",
"available_units": "mt, kg, lb, st",
"code": "91201-1-5",
"commodity": "Diammonium Phosphate",
"coverage": "Fertilizers & Gases",
"default_currency": "USD",
"default_unit": "mt",
"details": "N/A",
"has_forecast": true,
"has_preliminary": true,
"last_available_final": "2024-03-01",
"location": "United States",
"product": "Primary Commodity Prices",
"remark_1": "lag: 0",
"remark_2": "N/A",
"series_hist_changed": false,
"specification": "standard (18% N, 46-53% P2O5)",
"updated_at": "2024-04-09"
},
...
]For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Need help? Have any issues setting up the API or find any error? Please contact us.
Querying Values for a Single Price Assessment
Example Request:
GET https://intratec.azure-api.net/commodity_price/v1/sandbox/export/series/91201-1-5 HTTP/1.1
Host: intratec.azure-api.net
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6NfgBefore trying the example request, please make sure it includes codes of price assessments available under the subscription.
Example Response:
[{
"assessment": "Diammonium Phosphate, export spot price, fob, US Gulf",
"code": "91201-1-5",
"coverage": "Fertilizers & Gases",
"currency": "USD",
"product": "Primary Commodity Prices",
"remark_1": "lag: 0",
"remark_2": "N/A",
"series_final_values": [{
"date": "2024-03-01",
"value": -555
},
...
{
"date": "2023-03-01",
"value": -555
}],
"series_forecast_values": [{
"date": "2024-09-01",
"value": -555
},
...
{
"date": "2024-04-01",
"value": -555
}],
"unit": "mt",
"updated_at": "2024-04-09"
}]For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Querying Values in Another Currency
Specify a different output currency by adding &c= after the code. The example request queries values in British Pounds (GBP) - =9.
Example Request:
GET https://intratec.azure-api.net/commodity_price/v1/sandbox/export/series/91201-1-5&c=9 HTTP/1.1
Host: intratec.azure-api.net
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6Nfg- Find available currencies and respective in the Currency Reference section.
- If invalid is provided values will be displayed in the default currency.
Before trying the example request, please make sure it includes codes of price assessments available under the subscription.
Example Response:
[{
"assessment": "Diammonium Phosphate, export spot price, fob, US Gulf",
"code": "91201-1-5",
"coverage": "Fertilizers & Gases",
"currency": "GBP",
"product": "Primary Commodity Prices",
"remark_1": "lag: 0",
"remark_2": "N/A",
"series_final_values": [{
"date": "2024-03-01",
"value": -436.7730576532258
},
...
{
"date": "2023-03-01",
"value": -457.07214434032255
}],
"series_forecast_values": [{
"date": "2024-09-01",
"value": -438.17749741435796
},
...
{
"date": "2024-04-01",
"value": -437.60743065302074
}],
"unit": "mt",
"updated_at": "2024-04-09"
}]For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Querying Values in Another Unit of Measurement
Specify a different output unit by adding &u= after the code. The example request queries values in kilograms (kg) - =6.
Example Request:
GET https://intratec.azure-api.net/commodity_price/v1/sandbox/export/series/91201-1-5&u=6 HTTP/1.1
Host: intratec.azure-api.net
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6Nfg- Find units of measurement and respective in the Unit Reference section.
- Find available units of measurement for each assessment with Series Info operation.
- If invalid is provided values will be displayed in the default unit of measurement.
Before trying the example request, please make sure it includes codes of price assessments available under the subscription.
Tip: Users can specify both unit and currency for the same code, no matter the order of the parameters.
91201-1-5&u=6&c=9 is equivalent to 91201-1-5&c=9&u=6
Example Response:
[{
"assessment": "Diammonium Phosphate, export spot price, fob, US Gulf",
"code": "91201-1-5",
"coverage": "Fertilizers & Gases",
"currency": "USD",
"product": "Primary Commodity Prices",
"remark_1": "lag: 0",
"remark_2": "N/A",
"series_final_values": [{
"date": "2024-03-01",
"value": -0.555
},
...
{
"date": "2023-03-01",
"value": -0.555
}],
"series_forecast_values": [{
"date": "2024-09-01",
"value": -0.555
},
...
{
"date": "2024-04-01",
"value": -0.555
}],
"unit": "kg",
"updated_at": "2024-04-09"
}]For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Need help? Have any issues setting up the API or find any error? Please contact us.
Querying Values for Multiple Price Assessments
Example Request:
GET https://intratec.azure-api.net/commodity_price/v1/sandbox/export/series/91201-1-5,18203-1-5 HTTP/1.1
Host: intratec.azure-api.net
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6Nfg- Users can request up to 40 codes per data query.
- Codes must be separated by comma.
- Users can make queries of multiple codes with specific currencies and units of measurement. E.g.:
...series/91201-1-5&c=9&u=6,18203-1-5&c=9&u=6 - Before trying the example request, please make sure it includes codes of price assessments available under the subscription.
Example Response:
[{
"assessment": "Diammonium Phosphate, export spot price, fob, US Gulf",
"code": "91201-1-5",
"coverage": "Fertilizers & Gases",
"currency": "USD",
"product": "Primary Commodity Prices",
"remark_1": "lag: 0",
"remark_2": "N/A",
"series_final_values": [...],
"series_forecast_values": [...],
"unit": "mt",
"updated_at": "2024-04-09"
}, {
"assessment": "Diammonium Phosphate (granular), domestic spot price, exw, China",
"code": "18203-1-5",
"coverage": "Fertilizers & Gases",
"currency": "USD",
"product": "Primary Commodity Prices",
...
}]For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Querying Price Assessment Historical Values
Example Request:
GET https://intratec.azure-api.net/commodity_price/v1/sandbox/export/series_hist/91201-1-5 HTTP/1.1
Host: intratec.azure-api.net
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6NfgBefore trying the example request, please make sure it includes codes of price assessments available under the subscription.
Example Response:
[{
"assessment": "Diammonium Phosphate, export spot price, fob, US Gulf",
"code": "91201-1-5",
"coverage": "Fertilizers & Gases",
"currency": "USD",
"product": "Primary Commodity Prices",
"remark_1": "lag: 0",
"remark_2": "N/A",
"series_final_values": [{
"date": "2024-03-01",
"value": -555
},
...
{
"date": "2014-03-01",
"value": -555
}],
"series_forecast_values": [{
"date": "2024-09-01",
"value": -555
},
...
{
"date": "2024-04-01",
"value": -555
}],
"unit": "mt",
"updated_at": "2024-04-09"
}]For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Need help? Have any issues setting up the API or find any error? Please contact us.
Verifying Data Request Limits
To check the total and remaining requests for each subscribed dataset of Series Values and Series Values History operations.
Example Request:
GET https://intratec.azure-api.net/commodity_price/v1/data_limits HTTP/1.1
Host: intratec.azure-api.net
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI ... SpvL9ZfVEGwch6Nfg- Only industries users are subscribed to appear in the response.
- The remaining requests are reset when new data are released, according to Intratec Data Release Schedule.
Example Response:
{
"Fertilizers & Gases": {
"remaining_requests": 572,
"total_requests": 600
},
"Inorganic Chemicals": {
"remaining_requests": 556,
"total_requests": 600
},
"Polymers": {
"remaining_requests": 516,
"total_requests": 600
},
"Metals & Mining": {
"remaining_requests": 594,
"total_requests": 600
},
...
}For detailed data mapping, as well as python and VBA implementation examples, please refer to the developer portal.
Need help? Have any issues setting up the API or find any error? Please contact us.
Scheduled Maintenance
Intratec Primary Commodity Prices API goes unavailable during regular maintenance procedures from 6 am to 10 pm (US Central Time) on the following days:
- 15th day of the month
- 25th day of the month
On the day when monthly data is released, the API becomes unavailable at 6 am and becomes available again once the new data is released. The deadline for releasing the new data is 10 pm (US Central Time). Users can find the release date in the Intratec Data Release Schedule.
API Versioning
Versioning of Intratec Primary Commodity Prices API follows widely accepted concepts to differentiate between breaking and non-breaking changes. In case of breaking changes, the recent API version is still available but marked as deprecated. Deprecated APIs and API versions will be supported for at least 3 months from the date of deprecation. However, we highly recommend that users migrate to the most recent APIs as soon as possible.
Any modifications, improvements and corrections to the API will be documented and published on the Release Notes page.
The following are examples of breaking (incompatible) and non-breaking (also known as "compatible" or "smooth") changes in REST APIs.
Examples of breaking changes:
- Deleting an operation
- Deleting or renaming parameters
- Changing the type of a parameter
Examples of non-breaking changes:
- Adding an operation
- Adding a non-mandatory parameter
- Adding non-mandatory properties to a resource
As APIs do not remain fixed and unchanged within the same API version, API consumers must prepare their client-side implementation to handle non-breaking changes.