Advanced Parameters

Advanced Parameters

The API supports a number of advanced parameters that allow you to filter and sort the data.

1. Include Members

The include parameter allows you to specify the unique members of a dimension that should be considered when calculating measures. Users can specify one or more members to include, separated by commas (,). The format is as follows:

&include=<level_name>:<member_key>,<member_key>,<member_key>

You can specify one or more include parameters in the request, either in different keys or in the same key separated by semicolons (;).

&include=<level1>:<level1_member1>&include=<level2>:<level2_member1>,<level2_member2>
&include=<level1>:<level1_member1>;<level2>:<level2_member1>,<level2_member2>

For example, the following API call will include data only for the year 2020 and for the product code of Section 1 HS2 05:

https://api-v2.oec.world/tesseract/data.jsonrecords?cube=trade_i_baci_a_96&drilldowns=HS2&measures=Trade+Value&include=HS2:105;Year:2020

2. Exclude Members

In the same way that include specifies the unique members that should be considered, the exclude parameter specifies that all available members except those mentioned should be considered in the aggregation. The format is the same:

&exclude=<level1>:<level1_member1>&exclude=<level2>:<level2_member1>,<level2_member2>
&exclude=<level1>:<level1_member1>;<level2>:<level2_member1>,<level2_member2>

For example, the following API call will return data for all available products except for the product code Section 1 HS2 05:

https://api-v2.oec.world/tesseract/data.jsonrecords?cube=trade_i_baci_a_96&drilldowns=HS2&measures=Trade+Value&exclude=HS2:105

3. Parents

The parents parameter allows you to include parent members in hierarchical dimensions. You can either specify specific levels to include parents for, or use a boolean value to include all parents. The format is as follows:

&parents=<level1>,<level2>
&parents=true

For example, the following API call will include parent members for the HS4 level (e.g. Section and HS2) when querying US export data:

https://api-v2.oec.world/tesseract/data.jsonrecords?cube=trade_i_baci_a_96&drilldowns=HS4,Exporter+Country&measures=Trade+Value,Quantity&parents=HS4

4. Filters

The filters parameter allows you to filter results based on measure values using various comparison operations. The basic format is:

&filters=<measure>.<operation>

Null Operations

You can filter for null or non-null values using:

&filters=Trade+Value.isnull
&filters=Trade+Value.isnotnull

Comparison Operations

The following comparison operations are supported:

• gt – Greater Than (>)
• gte – Greater Than or Equal (>=)
• lt – Less Than (<)
• lte – Less Than or Equal (<=)
• eq – Equal (==)
• neq – Not Equal (!=)

For example, to filter for Trade Values greater than 800 billion USD:

&filters=Trade+Value.gt.800000000000

You can also combine multiple conditions using .and./.or.. For example, to filter for trade values between 250,000 and 750,000:

&filters=Trade+Value.gt.250000.and.lt.750000

5. Ranking and Sort

The API provides two parameters for ordering results: ranking and sort.

Ranking

The ranking parameter allows you to rank results based on a measure. You can specify the measure name with an optional minus sign for descending order, or use a boolean value. The format is:

&ranking=<measure>
&ranking=-<measure>
&ranking=<measure1>,-<measure2>
&ranking=true

Sort

The sort parameter allows you to sort results by either a measure or a level (dimension). You can specify ascending or descending order. The format is:

&sort=<measure or level>.asc
&sort=<measure or level>.desc

For example, to sort trade data by Trade Value in ascending order:

https://api-v2.oec.world/tesseract/data.jsonrecords?cube=trade_i_baci_a_96&drilldowns=Year,HS4&measures=Trade+Value,Quantity&include=Year:2021&sort=Trade+Value.asc&ranking=Trade+Value

Or, to fetch the top exporters above a threshold of 800 billion USD sorted by year:

https://api-v2.oec.world/tesseract/data.jsonrecords?cube=trade_i_baci_a_96&drilldowns=Exporter+Country,Year&measures=Trade+Value&locale=en&filters=Trade+Value.gt.800000000000&sort=Year.desc

6. TopK

The TopK parameter allows you to get the top N records for each unique combination of specified levels, sorted by a measure or level. The format is:

&top=<amount>.<level1>[,<level2>].<measure or level>.<order>

For example, to get the year of the highest trade value for each country:

https://api-v2.oec.world/tesseract/data.jsonrecords?cube=trade_i_baci_a_96&drilldowns=Exporter+Country,Year&measures=Trade+Value&locale=en&top=1.Exporter+Country.Trade+Value.desc

Or, to get the 2 years with the highest trade values for each country:

https://api-v2.oec.world/tesseract/data.jsonrecords?cube=trade_i_baci_a_96&drilldowns=Exporter+Country,Year&measures=Trade+Value&locale=en&include=Year:2020,2021,2022&top=2.Exporter+Country.Trade+Value.desc

⚠️ Note: All columns mentioned in the parameter must be present in the request, either in drilldowns or measures.

7. Time

The time parameter provides special filtering capabilities for time-based dimensions. It supports two main formats:

Latest/Oldest Format

This format allows you to fetch the most recent or oldest data points available in the dataset:

&time=<dimension>.latest[.amount]
&time=<dimension>.oldest[.amount]

Trailing/Leading Format

This format allows you to set a time frame relative to the most/least recent record available in the dataset. Works similarly to the latest/oldest format, but is strictly time-based:

&time=<dimension>.trailing[.amount]
&time=<dimension>.leading[.amount]