Magic Box API

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.

Dependencies:

NVM

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.32.1/install.sh | bash

Node.js

nvm install 8

Setup

git clone https://github.com/unicef/magicbox-open-api.git
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 gadm.org.

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!