Comprehensively documenting how to work with IMF data in Python

Announcing a beautiful new documentation website for `imfp`, the leading Python tool for working with International Monetary Fund data

A simple plot of a time series of coal prices available from the Primary Commodity Price System database through imfp

I’m excited to announce a major overhaul of the documentation website for imfp—a Python library we created at Promptly Technologies to help you easily download data from the International Monetary Fund’s (IMF) RESTful JSON API. With this update, we aimed to make imfp much more approachable and usable for analysts, researchers, and data enthusiasts who are not expert programmers.

Why a New Documentation Site?

If you’ve used IMF data before, you know that the hundreds of API endpoints, undocumented rate limits, and dozens of different query parameters can be a little daunting. That’s why we decided to create a comprehensive, visually appealing, and easy-to-navigate documentation website with detailed sample code and an end-to-end example project that uses imfp.

What’s New?

• Best Practices for Querying the API: We’ve broken down each step of querying the IMF API, including discovering available databases, filtering on thousands of indicators, and caching retrieved data to avoid dreaded rate limit errors.

• Detailed Guides for Working with Returned Data: Instead of just returning a DataFrame and leaving you on your own, we walk you through the basics of data cleaning and feature engineering, including how to convert time periods to numeric values, adjust for inflation, convert to US dollars, and normalize for population.

• Improved Navigation and Search: The website is now organized into different pages, with a quickstart guide supplemented by detailed deep dives on different topics. A search function speeds up finding the info you’re looking for. We’ve also provided the full documentation as a single text file that you can provide as context to an AI model like DeepSeek or ChatGPT.

Shout-Out to Jenny Xu

Promptly Technologies intern Jenny Xu, a double major in psychology and statistics at UC Davis, investigated the relationship between GDP growth and a measure of gender equality available through imfp

This overhaul also gives me an opportunity celebrate the outstanding work of our intern, Jenny Xu. Last fall, she carried out a six-week demonstration project using imfp, aimed at exploring the relationship between GDP growth and changes in a measure of gender inequality across countries. Jenny’s statistical tests found no significant relationship between the two (i.e., a null result). I’m very proud of the work she did on this project.

Why celebrate a null finding? Because good research is about transparency and reproducible methods, not forcing a significant p-value. More to the point, the purpose of Jenny’s project was to demonstrate how to use imfp from end to end in a real research project, and she accomplished that goal admirably. Jenny’s Quarto notebook shows exactly how to:

1. Identify the relevant IMF databases and parameters (in her case, the Gender Equality database and the International Financial Statistics).

2. Systematically fetch, clean, and transform the data (inflation adjustment, population normalization, etc.).

3. Produce informative visualizations (bar plots, heatmaps, and line charts).

4. Perform regressions and time-series analyses.

Her project is a perfect example of how imfp can serve real research workflows—whether or not the final results are what you expect. (We strongly believe in the value of publishing null results, which help steer the broader research community toward more accurate or innovative future studies!)

“The point of the project was to show how to do a data analysis project with the library, not to publish a positive finding.”
— My parting words to Jenny when she worried that “no effect” might seem anticlimactic!

Jenny’s full write-up—including code, plots, and analysis—can be found on our Demo page. It’s well worth a look, both for the method and the reproducible Jupyter/Quarto pipelines.

Highlights of the imfp Workflow

If you’re new to imfp, here’s a quick taste:

1. List the IMF databases:

   databases = imfp.imf_databases()

2. View valid parameters (e.g., for the commodity price database, PCPS):

   params = imfp.imf_parameters("PCPS")

3. Request data:

   df = imfp.imf_dataset(database_id="PCPS", freq=["A"], commodity=["PCOAL"], unit_measure=["IX"], start_year=2000, end_year=2015)

That’s really all you need to start accessing data from the IMF! But that just scratches the surface of what’s in the new docs, which cover everything from caching strategies to data cleaning, feature engineering, and merging different data sets.

Try It Out!

Ready to try imfp? It’s as simple as:

pip install --upgrade imfp

Thank You and Next Steps

• To Jenny Xu, for not only her great demo project, but also her helpful user testing and feedback on UX.

• To the open-source community, whose questions and bug reports have helped shape each iteration of imfp.

We hope this documentation site makes your research or analytics journey smoother and more enjoyable. We know there are lots of features still to add and lots of bugs to work out. If you encounter problems using imfp, please feel free to let us know by opening a GitHub issue, or even better—contributing a pull request! We’re excited to see what you’ll create using imfp.

Happy coding, and here’s to furthering open, transparent research—one dataset at a time.