Standard Query Parameters
There is a set of standard query parameters available for each endpoint. The standard query parameters support filtering and sorting of the results, and also support pagination with limit and offset.
Each endpoint can also have additional query parameters specific to it, which are described for each endpoint separately later in this document.
Sorting There can be many sorting conditions applied to one request, provided in a list. Each sorting condition has a by field and an order.
Filtering There can be many filters applied to one request, provided in a list. Each filter condition has a by field, an operator, and a value.
The supported operators are:
Standard Response Envelope
The response for each endpoint will follow a standard pattern.
The data section will contain a list of the response objects, for example a list of historical time series or a list of forecast data points (see their definitions later in the document).
The meta section will contain a standard set of metadata about the request and any endpoint specific query parameters used.
Categories
All Expana data is categorized into 23 main commodity categories. Every historical time series and forecast time series belongs to one main category. Each category has a full name and a short name. You can use the short name to query in the category endpoints.
Historical Data
Expana’s dataset covers 30k+ historical time series. They represent the historical trends of prices, supply, export, import and more for a wide range of commodities.
Historical Series Data Point
Each historical data point contains several pieces of information described below.
All data points are stored with the potential of having a range. All items have Low, High and Mid available. If a data point is not a range, it will have the same value in Low, High and Mid.
A data point can also include additional information from third party sources like the USDA (United States Department of Agriculture) and for some Expana proprietary series - pounds, trades, loads, and a weighted average.
Frequency Conversion
Each historical series in Expana came from its source (internal PRA or external) with a specific frequency. The vast majority of series have one source frequency, however some sources (e.g. USDA) publish their series in more than one frequency.
You can find the available source frequencies in the sourceFrequencies parameter of every Historical Time Series object.
Expana also supports frequency conversion. You can request the historical data points in any frequency that is less frequent than the source frequencies (e.g. ask for Weekly or Monthly if a series came as Daily from source, or ask for Monthly if it came as Weekly and so on).
This is specific to each historical time series, as each series has a different source frequency.
In general, the available frequencies in Expana are Daily, Weekly, Monthly, Quarterly, Semi-Annually, Yearly.
You can provide your chosen frequency as a query parameter in the Get Historical Series By Code endpoint. Please note: Frequency conversion is only available for this endpoint, as available frequencies are series specific (no conversion to more frequent frequency)
Currency Conversion
The Data Direct API allows for conversion between all supported currencies for historical data points. See the full list of supported currencies in the appendix.
You can provide your chosen currency as a query parameter in the get historical series by code endpoint. Please note: Currency conversion is only available for this endpoint, as available frequencies are series specific (not all series have a currency)
Unit Conversion
The Data Direct API allows for conversion between applicable units for historical data points. See the list of units that can be validly converted between each other in the appendix.
You can provide your chosen unit as a query parameter in the get historical series by code endpoint. Please note: Unit conversion is only available for this endpoint, as available units to convert to are series specific. See in the appendix.
If you provide an invalid unit (for example trying to convert kilograms to meters), an appropriate error will be returned.
Forecast Data
Expana’s dataset covers 1k+ forecast time series, generated by Expana’s expert forecasting team. Note that we don’t support frequency, currency, or unit conversions for forecast series.
Forecast Series
Each forecast time series in Expana is based on a historical time series, therefore they share many properties, mostly importantly the code.
Forecast Series Data Point
Each forecast data point contains several pieces of information described below.
The forecast data points produced by our forecasting team are of type target data points. Additionally, we also run an interpolation algorithm to generate forecast data points between target data points. They are of type interpolated.
