imfFetcher

Interacts with the International Monetary Fund API (SDMX 3.0) to retrieve macroeconomic data.

Requirements & Installation:

• Dependencies: httpx, pandas, nest_asyncio

• To install, run:

  pip install imfFetcher==1.0.0
  

Example:

An IMFInstance is the entry point for accessing IMF datasets:

import imfFetcher

# Create an instance of IMFInstance:
instance = imfFetcher.IMFInstance()
# <IMFInstance object>

Each dataset provided by the IMF (e.g., CPI, National Economic Accounts, World Economic Outlook) is represented by a distinct dataflow. You can list available dataflows via the dataflows attribute:

# List available dataflows:
dataflows = instance.dataflows

Once you’ve chosen a dataflow, initialize a Dataflow object:

# Select the Consumer Price Index (CPI) dataflow:
dataflow = instance.Dataflow('CPI')
# <Dataflow object>

This object exposes all relevant metadata, including available dimensions (e.g., country, index type, frequency) for refining queries. Retrieve dimensions via:

# Get dimensions metadata:
dimensions = dataflow.dimensions

For each dimension, fetch valid values—use both dimensions_available_values (a pandas.DataFrame) and _dimensions_available_values (a dict):

avail = dataflow._dimensions_available_values

{
  'COICOP_1999': [
    {'ID': 'CP01', 'Name': 'Food and non-alcoholic beverages'},
    ...
    {'ID': '_T',   'Name': 'All Items'}
  ],
  'COUNTRY': [
    {'ID': 'USA', 'Name': 'United States'},
    {'ID': 'CAN', 'Name': 'Canada'},
    {'ID': 'GBR', 'Name': 'United Kingdom'},
    ...
  ],
  'FREQUENCY': [
    {'ID': 'A', 'Name': None},
    {'ID': 'M', 'Name': None},
    {'ID': 'Q', 'Name': None}
  ],
  'INDEX_TYPE': [
    {'ID': 'CPI',  'Name': 'Consumer Price Index'},
    {'ID': 'HICP', 'Name': 'Harmonised Index of Consumer Prices'}
  ],
  'TYPE_OF_TRANSFORMATION': [
    {'ID': 'IX',          'Name': 'Index'},
    {'ID': 'YOY_PCH_PA_PT','Name': 'Year-over-year percent change'},
    ...
  ]
}

Copy and adjust the query template:

# Build query parameters template:
qpar = dataflow.query_params_dict_template.copy()
# {
#   'COUNTRY': '*',
#   'INDEX_TYPE': '*',
#   'COICOP_1999': '*',
#   'TYPE_OF_TRANSFORMATION': '*',
#   'FREQUENCY': '*'
# }

Set filters:

qpar['COUNTRY']              = ['USA', 'CAN', 'GBR']  # United States, Canada, United Kingdom
qpar['INDEX_TYPE']           = 'CPI'                   # Consumer Price Index
qpar['COICOP_1999']          = '_T'                    # All items
qpar['TYPE_OF_TRANSFORMATION']= 'IX'                    # Index transformation
qpar['FREQUENCY']            = 'M'                     # Monthly frequency

Execute the query and clean results:

data = dataflow.query(qpar).dropna()

Shape: 844 rows × 3 columns

Note: If the IMF API returns multiple tables, the query method outputs a dict of DataFrames, one per table.