IMF API

Part 1

A quick example of requesting, cleaning up, saving to csv, and then plotting a series from IFS using the API.

Part 2

An example of how to find the dimensions and codes which correspond to your data of interest.

Part 3

How to retrieve the metadata for your series of interest and how to make more advanced requests from the API.

IMF API with Python: Finding dimensions and codes

The example presented in part 1 accesses data from the IMF API. Here in part 2, techniques for finding the right codes to make successful API requests are presented, using the requests package and Python 2.7.

The series list

The Dataflow method offers JSON formatted information on which series are available through the API. To find the series of interest (for example Direction of Trade Statistics DOT) with Python, we can search a dictionary with the series names and their IDs.

In[1]:

import requests  # Python 3.6

url = 'http://dataservices.imf.org/REST/SDMX_JSON.svc/'
key = 'Dataflow'  # Method with series information
search_term = 'Trade'  # Term to find in series names
series_list = requests.get(f'{url}{key}').json()\
            ['Structure']['Dataflows']['Dataflow']
# Use dict keys to navigate through results:
for series in series_list:
    if search_term in series['Name']['#text']:
        print(f"{series['Name']['#text']}: {series['KeyFamilyRef']['KeyFamilyID']}")

Out[1]:

Direction of Trade Statistics (DOTS): DOT

Finding the dimensions of the series

The exact format of the key in our API request is determined by the structure of the series. Direction of Trade Statistics, which are grouped by importer and exporter pair rather than by country exemplifies the need to first determine series structure.

The dimensions of the data are found with the DataStructure method and series specific, so that the full key becomes DataStructure/DOT

In[2]:

key = 'DataStructure/DOT'  # Method / series
dimension_list = requests.get(f'{url}{key}').json()\
            ['Structure']['KeyFamilies']['KeyFamily']\
            ['Components']['Dimension']
for n, dimension in enumerate(dimension_list):
    print(f'Dimension {n+1}: {dimension['@codelist']}')

Out[2]:

Dimension 1: CL_FREQ
Dimension 2: CL_AREA_DOT
Dimension 3: CL_INDICATOR_DOT
Dimension 4: CL_COUNTERPART_AREA_DOT

In this case, the dimensions correspond to: 1) frequency, 2) country or reference area 1, 3) indicator (such as total exports), and 4) country or reference area 2. That is, the monthly value of goods exports from Italy to France would be M.IT.TXG_FOB.FR

Finding the codes for each dimension

The codes which correspond to the dimensions identified above are combined, in order, and separated by periods, to complete the API request url. To find the list of possible codes for each dimension, we can use the CodeList method, shown below for dimension 3, indicators CL_INDICATOR_DOT.

In[3]:

# Example: codes for third dimension, which is 2 in python
key = f"CodeList/{dimension_list[2]['@codelist']}"
code_list = requests.get(f'{url}{key}').json()\
	    ['Structure']['CodeLists']['CodeList']['Code']
for code in code_list:
    print(f"{code['Description']['#text']}: {code['@value']}")

Out[3]:

Goods, Value of Exports, Free on board (FOB), US Dollars: TXG_FOB_USD
Goods, Value of Imports, Cost, Insurance, Freight (CIF), US Dollars: TMG_CIF_USD
Goods, Value of Imports, Free on board (FOB), US Dollars: TMG_FOB_USD
All Indicators: All_Indicators

Variations and notes

Once a series has been identified, it can be a challenge to determine which combination of codes returns valid data. Often an indicator has data available at only one frequency--whichever frequency of compilation occurs in the source country, though there are exceptions.

The number of indicators varies by series. In the case of International Financial Statistics (IFS), there are more than 2500 indicators, while there are four indicators in the Direction of Trade Statistics series. The same search technique used to find the series names can be used to filter IFS indicators.

Part 3 shows how to retrieve metadata and make a request with more than one reference area (country).

« Back (Part 1) | Next (Part 3) »