How to use PIP’s API

This blog is the fifth of a series of blogs showcasing the different features of the Poverty and Inequality Platform (PIP).

What’s an API anyway?

In this week’s blog, we review PIP’s data API. API stands for Application Programming Interface, a very generic, and somewhat intimidating terminology. In practice though, a data API is just a way to access data via a URL, not so dissimilar to downloading a .csv file from the Web. However, with a data API, you get extra powers that allow you to slice and dice a dataset at will before downloading it.

Let’s take a toy example to illustrate this point:

• Data available via .csv file: https://worldbank.org/fake-data.csv

Using this URL, you can quickly access the complete dataset.

• Data available via data API: https://worldbank.org/fake-api?year=2020

Using a data API however, you can add “parameters” to only download the subset of data you are interested in. Additional parameters are typically placed after a question mark in the URL. 

PIP data is so big and rich that a powerful API has been implemented for users to obtain access to the World Bank’s poverty and inequality data.

PIP API documentation: Get familiar with the PIP data API

Direct access to the API’s documentation and examples is available from PIP’s top menu bar, under the “Resources” drop-down menu.

Figure 1. PIP API documentation page

via GIPHY

Each of the blue boxes beginning with “GET” (Figure 1) is an API endpoint, referring to different functionalities. By clicking on any of the endpoints and, then on the “Try it out” box, the different parameters in the endpoint will be activated for use. For example, to access the PIP’s main poverty and inequality statistics, use the pip/v1/pip endpoint and click on “Try out”. After selecting a particular country, year, and poverty line value (followed by other optional parameters below), click on “Execute”. Scroll down to see the results in the black boxes under “Responses” (See Figure 2).

Figure 2: Executing an API endpoint in PIP

The text that appears under “Request URL” is the actual URL used to fetch the data that was requested. Note that the last parameter in this endpoint, “format”, offers three different options to render your results (csv, json & rds). If, for instance, “csv” is selected, and then “execute”, the URL from the “Request URL” box can be copied and pasted into an internet browser to obtain a CSV file with the data requested.

Example: https://api.worldbank.org/pip/v1/pip?country=COL&format=csv

Figure 3: Breaking down a URL

Using the PIP data API in practice

One of the big advantages of data APIs is that you can interact with them programmatically by writing a few scripts using your preferred programming language. The good news is that if you are a Stata or R user, those scripts have already been developed for PIP users.

• Stata client for the PIP API is available here
• R client for the PIP API is available here

An upcoming Python client will also be released in the coming weeks.

Hot tip!

As a user, you will typically use the PIP API to retrieve data you are interested in. Since the PIP dataset is quite big, the number of API parameters that can be used to slice and dice it is also quite significant. Another powerful feature of a data API is that it can return information about itself! The PIP API provides helper endpoints such as the one below, that returns all valid parameters and parameter values that can be used for a given endpoint: http://pip.worldbank.org/api/v1/valid-params?endpoint=aux

Figure 4: Sample API response for valid parameters and values

We hope this API review was helpful to expand your PIP experience.

We gratefully acknowledge financial support from the UK government through the Data and Evidence for Tackling Extreme Poverty (DEEP) Research Programme. This work has also been supported by the World Bank’s Partnership Fund for Sustainable Development Goals (SDG Fund) and a World Bank trust fund with the Republic of Korea, acting through the Korea Development Institute School of Public Policy and Management (KDIS), for the KDI School Partnership for Knowledge Creation and Sharing.

---

Previous PIP blogs:

• How to use PIP’s Homepage

• How to use PIP’s Country Profiles page

• How to use PIP’s Poverty Calculator page

• How to use PIP’s Statistics Online (SOL)