R package to access the Global Internal Displacement Database

This package idmcapi happens to be my first and complete attempt to write an API package with R. And I was submitting the package on CRAN. Many in R community have done that, and I’ve learnt a ton of good practices from them. It’s probably that idmcapi won’t have a large number of users; that’s fine, because it’s not my initial intention at all.

I came up with the project last night while I was looking for a ‘cool’ data set for the next DataTalk meetup. DuckDuckGo sent me to this site - The Humanitarian Data Exchange - a platform for sharing humanitarian data. You should definitely take a loot at that site if you are passionate about doing good with data.

My first search gave me a result of a data set about Vietnam’s Internally Displaced Persons (IDPs) who are forced to flee their homes because of conflict, violence and disasters. It seems good for analysis, let see if there’s something else. It turns out that IDMC, the data contributor, maintains a database of worldwide country profiles of IDPs and their team are kind enough to provide REST API for public access. So I asked myself why not build an R package for this. And here you are:

devtools::install_github("chuvanan/idmcapi")

It covers all of the public API endpoints:

• get_countries: Returns a list of countries in the database
• get_overview: Returns a country displacement information, including population and refugee numbers
• get_conflict_data: Returns all available conflict displacement data
• get_disaster_data: Returns all available disaster displacement data by event and includes hazard type information
• get_aggregated_disaster_data: Returns all available disaster displacement data by country aggregating all the events
• get_displacement_data: Returns all available displacement data for both disaster and conflict by year and country
• get_strata_data: Returns the strata data for a country by type of displacement and fact type
• get_figure_analysis: Returns the figure analysis for a country
• get_confidence_assessment: Returns the confidence assessment data for a country by type of displacement and fact type
• get_disaster_events: Returns events associated with an ISO code

Here’s a bit of it in action:

get_countries()          # output truncated

#     iso3                       geo_name
# 1    AB9                     Abyei Area
# 2    AFG                    Afghanistan
# 3    ALB                        Albania
# 4    DZA                        Algeria
# 5    AGO                         Angola
# 6    AIA                       Anguilla
# 7    ATG            Antigua and Barbuda
# 8    ARG                      Argentina
# 9    ARM                        Armenia
# 10   AUS                      Australia

get_overview('VNM')

#                               fields                       values
# 1                               iso3                          VNM
# 2                           geo_name                      Vietnam
# 3                  population.figure                     95414640
# 4                    population.year                         2017
# 5                  population.source       UN Population Division
# 6                     refugee.figure                       329331
# 7                       refugee.year                         2016
# 8                     refugee.source                        UNHCR
# 9                    conflict.source                         IDMC
# 10                     disaster.year                         2017
# 11        disaster.new_displacements                       633463
# 12  disaster.new_displacements_since 1 January - 31 December 2017
# 13 disaster.new_displacements_source                         IDMC
# 14                   disaster.source                         IDMC

get_conflict_data(iso3 = 'RUS', year = 2015)

#   iso3 iso           geo_name year stock_displacement stock_displacement_source new_displacements
# 1  RUS  RU Russian Federation 2015              26607                      IDMC                 0
#   new_displacements_source
# 1                     IDMC

get_conflict_data(iso3 = 'RUS', year = c(2011, 2015))

#   iso3 iso           geo_name year stock_displacement_source new_displacements new_displacements_source
# 1  RUS  RU Russian Federation 2011                      IDMC                 0                     IDMC
# 2  RUS  RU Russian Federation 2012                      IDMC                 0                     IDMC
# 3  RUS  RU Russian Federation 2013                      IDMC                 0                     IDMC
# 4  RUS  RU Russian Federation 2014                      IDMC                 0                     IDMC
# 5  RUS  RU Russian Federation 2015                      IDMC                 0                     IDMC
#   stock_displacement
# 1                 NA
# 2              29000
# 3              34900
# 4              25378
# 5              26607