The Magic Box API Wiki

Magic Box is an open-source platform 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.


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

Now browse to: localhost:8000/docs

Expand ‘population’ and you’ll see two end points.

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

This returns:

{ 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:

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

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.