REST API | OEC - The Observatory of Economic Complexity

Introduction

Welcome to the OEC Pro API. In this document you will learn how to construct a variety of API endpoints to fetch the specific slice of data you need. You will also learn how to use the Data Explorer, a UI to facility constrcuting API queries and easily viewing data right in your browser.

To get started you will first need to subscribe as a Pro User, if you have not done so already. Once you have subscribed successfully and are logged in with your new pro account, you should see the following page, which will contain the token needed to authenticate all of your API requests to the server.

⚠️ Please note: you should treat your API token like a password and make sure not to share it with anyone or post it online where others could use it to make requests on your behalf. If at any point, you need to generate a new token, simply go to your user account page and click the button next to your token to generate a new one.

Make Your First Data Request

Fetching data is easy! The OEC API is designed for interoperability and can be integrated with many different programs. Below is an example showing how you can request the latest month's exports from US customs port-level data.

CURL

Python

PHP

Java

Response

1curl --request GET --url "https://oec.world/olap-proxy/data.jsonrecords?time=time.latest&Trade+Flow=2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_TOKEN"

1import urllib.request, json
2with urllib.request.urlopen("https://oec.world/olap-proxy/data.jsonrecords?time=time.latest&Trade+Flow=2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_TOKEN") as url:
3  data = json.loads(url.read().decode())
4  print(data)

1<?php
2  $url = 'https://oec.world/olap-proxy/data.jsonrecords?time=time.latest&Trade+Flow=2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_KEY' ;
3  $ch = curl_init($url);
4  curl_setopt($ch, CURLOPT_TIMEOUT, 200);
5  curl_setopt($ch, CURLOPT_SSLVERSION, 6);
6  curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 20);
7  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
8  $response = curl_exec($ch);
9  curl_close($ch);
10  $json = json_decode($response, true);
11?>

1URL url = new URL("https://oec.world/olap-proxy/data.jsonrecords?time=time.latest&Trade+Flow=2&cube=trade_s_usa_port_m_hs&drilldowns=Time,Product,Trade+Flow&measures=Trade+Value&token=YOUR_API_KEY");
2HttpURLConnection conn = (HttpURLConnection) url.openConnection();
3conn.setRequestMethod("GET");
4try (var reader = new BufferedReader(
5            new InputStreamReader(conn.getInputStream()))) {
6    for (String line; (line = reader.readLine()) != null; ) {
7        result.append(line);
8    }
9}
10

1{
2  "data": [
3    {
4      "Time": 202102,
5      "Product ID": 1010121,
6      "Product": "Horses: live, pure-bred breeding animals",
7      "Trade Flow ID": 2,
8      "Trade Flow": "Exports",
9      "Trade Value": 7440995
10    },
11    {
12      "Time": 202102,
13      "Product ID": 1010129,
14      "Product": "Horses: live, other than pure-bred breeding animals",
15      "Trade Flow ID": 2,
16      "Trade Flow": "Exports",
17      "Trade Value": 4387319
18    },
19    ...
20  ],
21  "source": [
22    {
23      "name": "trade_s_usa_port_m_hs",
24      "measures": [
25        "Trade Value"
26      ],
27      "annotations": {
28        "source_description": "Monthly trade data for the United States",
29        "dataset_name": "USA Trade® Online",
30        "dataset_link": "https://usatrade.census.gov/index.php",
31        "topic": "National",
32        "source_name": "United States Census Bureau",
33        "table": "Port",
34        "subtopic": "United States"
35      }
36    }
37  ]
38}

Generating API URLs Using The Data Explorer

Let's get started with a few examples to help us learn how to use the Data Explorer. You can access the Data explorer directly from your account page or by going to https://oec.world/en/explorer.

Example 1

Latest monthly product trade data for China

Once you have logged in you should see the following screen. On the left-hand side is where you will begin constructing your queries. So let's dive right in with our first example!

First we need to select the appropriate dataset, in our case this will be the China Regional Cube. Under the 'Dataset' heading select 'National' and then 'China' from the dropdown list.
Second, let's select both Trade Value and Quantity from the list of Measures.
Next, we should select from the Drilldown menu the following dimensions in order:
- Product: At the level of hierarchy we are looking for. In this example, we will select HS4 (referring to Harmonized System Product Classification at the 4-digit level).
- Time: At the Month level of hierarchy.
And finally, let's add a Cut:
- Time: timestamps are formatted as YYYYMM, so if we search for 202012 we'll get data for December of 2020.

Data Table

After clicking the 'Execute query' button you should see the following results. The results will contain any columns we selected as drilldowns or measures from our previous data selection step.

Now that our Data has been retrieved we can sort and format the results. Clicking the arrow button next to any measure column will bring out a pop-up menu allowing us to sort the results on this column or format them.

API Endpoint

Finally, once we are satisfied with our data selection, we can click on the 'API View' tab to find the specific API endpoint URL used to create the data we see in our 'Data Table' view.

Technical Definitions

Now that we've seen our first example of how to generate a data table based on a particular selection of data, let's take a closer look at some technical terms.

Datasets:
Datasets are the fundamental data structure used by the OEC API. A dataset contains all data related to a particular topic from a particular source. For instance: you will see multiple datasets for international trade because we have a variety of different product classifications: SITC (Standard International Trade Classification), HS (Harmonized System) as well as different revisions like HS92 (1992 revision of the Harmonized System), HS96 (1996 revision of the Harmonized System) and so on.
Data in each cube can be disaggregated by dimension. We can imagine a dimension as an edge of a cube, where the edge length depends on the dimension. As you may see a dimension is just a variable by which we can group by.
In conclusion, cubes store a huge amount of data at the most disaggregate level. Storing data in this way allows for the ultimate level flexibility as columns can always be marginalized over and their values aggregated.
Drilldowns:
Drilldowns are dataset dimensions. Thinking of datasets using a cube metaphor, the dimensions would be the edges. By default a dataset would be aggregated by all dimensions, choosing one from the drilldown menu allows us to disaggregate by that dimension.
Taking the German regional dataset as an example, it has Time, Region and Product type as dimensions. Each dimension will appear as a drilldown at OEC API. So, the first step to create a request will be to specify at least one drilldown in order to retrieve data for that specific variable.
Often times there will be a need to group data by different hierarchical levels. Say for instance we start our analysis by retrieving yearly trade data and want to move to a higher level of granulairy, say quarters or months. This is why dimensions also support different levels of hierarchy. Levels of hierarchy are a great way to group data while respecting the inherent hierarchy of the classification. We refer to levels of hierarchy in dimensions that have sub dimensions in their definition. For example, regions can be grouped by country and countries can be grouped by continent.
When we create a query using the Data Explorer we have to decide which level of hierarchy we want to group the data and which levels to include.
Measures:
Every cube contains different measures. This is why depending on the cube and dimensions selected for a query there will be different measures available. Measures are data values which can be aggregated. Measure can support different types of aggregations, such as sum, mean, min or max. Because of this, measures are usually integers, floats or percentages variables. In our case, examples of measures are trade value, weight, quantity, etc.
Cuts:
Cuts allow us to filter the data based on a specific member of a chosen dimension. For example, if we were using the US subnational cube and wanted to see export data from the state of Colorado (instead of showing all states) we would cut on that particular member.
Advanced Options:
1. Debug MDX: This option enables the debug tool, which will indicate where the error is when a query is not working properly.
2. Apply distinct: This option acts as a filter, which will filter duplicated IDs, leaving only unique values.
3. Only return non-empty data: This option will skip results with missing values.
4. Include parents levels: This option will include the parent dimensions in the query, for drilldowns that have a parent dimensions to add.
5. Optimize sparse results: This option will skip rows where the measure is a null value.

OEC Pro API Documentation