An API to serve open data aggregated by administrative boundaries
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add contributing guidelines placeholder (closes #23) Feb 26, 2018
api merge dev Jul 8, 2018
config adding security settings and changing caching library Aug 3, 2017
public hooli to worldpop May 25, 2018
scripts Add description to tally script Jan 26, 2018
test/api-test Add api test for mobility Jun 13, 2018
utils Fix up multiple countries and data access layer for csv with no azure… Jun 24, 2018
.babelrc adding es6 support with some changes Jun 14, 2017
.deployment Add deployment script Feb 1, 2018
.eslintignore Keep calm and commit Aug 31, 2017
.eslintrc.js Make eslint compatible to Windows OS Jun 8, 2018
.gitignore Add build routines Feb 1, 2018
.travis.yml Add CodeClimate maintainability + test coverage checks to CI Feb 14, 2018
LICENSE.txt Use one license file Jan 12, 2018
POP.csv getting population from worldbank Jun 29, 2017 Add Gitter badge to README Apr 17, 2018
get_population_from_worldbank.js getting population from worldbank Jun 29, 2017
index.js addinv missing file Jul 3, 2017
package-lock.json Fix minor link typos in info/description at top Jun 6, 2018
package.json Mobility matrices stored as CSVs in azure. On fetch, convert to json … May 29, 2018 Rename test suite (, add comments Feb 13, 2018
server.js Fix eslint errors Feb 16, 2018

Magic Box API

Chat on Gitter Build Status Maintainability

Magic Box is an open-source platform that is intended to use real-time information to inform life-saving humanitarian responses to emergency situations. It’s composed of multiple github repositories designed to ingest, aggregate, and serve data.

Install the API that serves the data

Magic Box API serves information useful to the data science team at the Office Of Innovation at UNICEF. This section describes how to install a local instance. It comes with sample data, but you can follow links below for code to download and aggregate many of the open data sets.

Types of data currently available to the public include:

  • population
  • mosquito prevalence
  • Paho Zika case data
  • School location and connectivity

...aggregated at municipal, state, and national levels.



curl -o- | bash


nvm install 8


git clone
cd magicbox-open-api
cp config-sample.js config.js
npm install
npm run build
npm run start

Now browse to: localhost:8000/docs


The first endpoint: /api/v1/population/countries, returns a list of codes for countries for which we have population data:

[ ‘afg’, ‘ago’, ‘arg’ … ‘zwe’]

The second endpoint returns population data for a single country. For instance, to fetch the population for Afghanistan at the district level, browse to: localhost:8000/api/v1/population/countries/afg

  { admin_id: ‘afg_1_5_50_gadm2–8’, value: 165297 },
  { admin_id: ‘afg_1_4_33_gadm2–8’, value: 175117 },
  { admin_id: ‘afg_1_7_57_gadm2–8’, value: 49994},
  { admin_id: ‘afg_1_11_102_gadm2–8’, value: 50304 },

  … 228 more items

What does this mean?

The value points to number of people. But, what swath of land does each admin_id refer to?

Answer: An admin ID points to a specific shape in a shapefile that represents an individual country.


To understand where afg_1_11_102-gadm2–8 points to, first note that Afghanistan has three levels of administrative boundaries:


The admin_id has three integers, one per admin level:


The first integer is 1 because Afghanistan is the first country in the collection of 254 available at


As for the second and third integers, Afghanistan has 34 shapes at admin level one (each shape is assigned an ID), and 320 shapes in admin 2.


Thus, afg_1_11_102-gadm2–8 indicates that any population value attached to it is related to:

  • The first country in the gadm collection.
  • The 11th shape in the admin 1 level shapefile.
  • The 102nd shape in the admin 2 level shapefile.


Mosquito Prevalence (University of Oxford)


  • Currently, the API serves prevalence scores at both a national and district/province level per country. Scores range from 0 to 1. Browse to localhost:8000/api/v1/mosquito/kinds to see what mosquito types we have data for:
[ ‘aegypti’, ‘albopictus’ ]
  • Browse to localhost:8000/api/v1/mosquito/kinds/aegypti for a country by country list:
	  abw: 0.92733,
	  afg: 0.12469,
	  zwe: 0.54493

Similar to Population, you can also use:

  • /api/v1/mosquito/kinds/aegypti/countries to retrieve a list of country_codes
  • /api/v1/mosquito/kinds/aegypti/countries/afg/ to get mosquito prevalence scores per district.

Zika Case Data (Paho)

The API serves Zika case data for the Americas (national level) as published by the Pan American Health Organization in excel files each epi week. In order to overlay with travel data given to us by Amadeus, we’ve also used a really simple algorithm to group the cases by ISO week.


To fetch all zika case data to date for either week type, use these end points:

  • localhost:8000/api/v1/cases/kinds/zika/weekTypes/iso
  • localhost:8000/api/v1/cases/kinds/zika/weekTypes/epi


To serve the same data as the live API, follow the Magic Box Wiki!