Integrating the World Bank API in Ruby on Rails


As part of a forthcoming data forecasting application, I am integrating the World Bank API. Here is a quick overview of how I went about integrating the API with the Ruby on Rails-based application:

First Things First

Install HTTParty, an awesome gem that allows for consumption of RESTful Web services.

Before diving into my code, let's have a look at an example URL from the World Bank API:

http://api.worldbank.org/countries/usa/indicators/SP.POP.TOTL?date=1990:2013&?per_page=2000&format=json

The URL returns a JSON object of total population in the United States between the years 1990 and 2003. This object, like any other object in Ruby, will be the source of the data.

Working with the World Bank API

Looking back at the API URL, there are four variables that need to be changed as per the end user request: the country, the indicator, the start date, and the end date.

Generating the ISO Country Code Hash

In order to map a given country to its corresponding ISO code, I created a hash which contains a key and a value: country and ISO code, respectively.

@countries_hash = HTTParty.get("http://api.worldbank.org/country?per_page=500&format=json")

This returns a JSON object of all countries and their corresponding ISO codes. The following code generates the hash:

i = 0
@country_iso = []
while i < @countries_hash[1].size
  @country_iso << @countries_hash[1][i]["name"]
  @country_iso << @countries_hash[1][i]["iso2Code"]
  i+= 1
end
@country_iso_hash = Hash[*@country_iso] #=> {"Aruba"=>"AW", "Afghanistan"=>"AF",..}
Generating Indicator ID Hash

The same strategy can be applied to generate the Indicator ID hash.

@indicators_hash = HTTParty.get("http://api.worldbank.org/indicators/?format=json&per_page=100")

This returns a JSON object of all indicators and their corresponding IDs. The following code generates the hash:

@indicator_id_hash = []
i = 0
while i < @indicators_hash[1].size
  @indicator_id << @indicators_hash[1][i]["name"]
  @indicator_id << @indicators_hash[1][i]["id"]
  i+= 1
end
@indicator_id_hash = Hash[*@indicator_id]

Both the country-iso-hash and the indicator-id-hash are now available to work with. Based on the end user inputs, I am able to generate the required query by mapping the input, using the hashes, and then insert the output into the base URL, which is necessary to fetch the data from the World Bank API:

http://api.worldbank.org/countries/#{@iso_code}/indicators/#{@indicator_code}?date=#{@start}:#{@end}&?per_page=200&format=json

In Action

Example end user's inputs:

  • country = United States of America
  • Indicator = GDP (current US$)
  • Start date = 1990
  • End date = 2013

By using the generated hashes we map the given country with its corresponding ISO code and the given indicator with its corresponding ID:

@country_iso_hash.each do |country, code|
  if country == @country
    @iso_code = @country_iso_hash[country]
  end
end

@indicator_id_hash.each do |indicator, id|
  if indicator == @indicator 
    @indicator_id = @indicator_id_hash[indicator]
  end
end

The last step is to put all the pieces together:

@results = http://api.worldbank.org/countries/#{@iso_code}/indicators/#{@indicator_code}?date=#{@start}:#{@end}&?per_page=200&format=json

And that's it! The variable results will include the US GDP for the period form 1990 to 2013.