Transforming Data Into Knowledge: Introducing ReliefWeb’s Humanitarian API

Adam Ross, Software Architect
#API | Posted

Today’s the day! We are incredibly excited to announce that our partner ReliefWeb, a global information service of the United Nations Office for the Coordination of Human Affairs (OCHA), has launched its latest initiative to improve information delivery to humanitarians: an API which gives developers open access to nearly two decades of data and analyses on global crises and disasters. Partnering with Development Seed, we created for the specific purpose of empowering humanitarian developers, who can now use the UN’s data to further their own missions. It is the first of many projects in which Phase2 will serve as OCHA’s chief technology partner in improving humanitarian information.

What makes this particular API so ground-breaking? By using an API to open up ReliefWeb’s impressive stockpile of information dating back to 1996, ReliefWeb is empowering the entire humanitarian community to find new ways to coordinate. In other words, they’re crowdsourcing innovation, acknowledging that humanitarians themselves understand the technologies required to advance specific causes, and are best placed to collaborate to find solutions. Furthermore, by releasing community-contributed data created and maintained in the website, ReliefWeb has raised the bar for the quality of data in the humanitarian space.

There will be more to come concerning this project’s potential to transform disaster relief efforts (see my colleague Molly Byrnes’ post on the importance of openness in humanitarian relief efforts). For now, I’ll delve into how Phase2 has streamlined this API for an optimum developer experience. After all, the API’s impact and direction will be determined by the way developers use it.

Introducing the API

The ReliefWeb API is a thin application layer built on top of an ElasticSearch datastore. ElasticSearch provides amazing capabilities in complex data mining and exploration. The application layer on top provides a layer of glossy, positive user experience for the developers who will build great new things with the API.

Enhancing Usability for Developers

Usability for Developers, often called “Developer Experience”, is achieved by creating an intuitive, easy-to-use system that enables innovation. Phase2’s role in the launch of this API was focused in large part on bringing the intuitive Web API conventions that developers have come to expect.

Strong documentation. There’s a detailed manual to orient new developers and get them up to speed on the capabilities of the API and how to use all the different pieces. If you like a more “conversational style” of learning, check out the Swagger documentation. Instead of “reading the book” you can simple start speaking to the API via the browser to see it respond in real time: documentation that cannot be out of date.

Resource-oriented URIs. Every endpoint of the API refers to a distinct resource. While it currently only supports HTTP GET, you know when you are retrieving a collection or an individual item just by glancing at the path, and what type of data it will be.

Hypermedia flavor. Control links facilitate paging, deep cross-linking of content allows navigating between related resources, and all resources can be reached by drilling down from the top of the API at

JSON Payloads. The payload of the API is done up in JSON with special care made for structural consistency across collections, individual items, and different types of content. Developers should face as few special cases as possible.

Browser Friendly. Want to implement your integration via JavaScript in the browser? The ReliefWeb API can accommodate without any special tricks via broad CORS support. As a JSON API, any browser plugin which helps you visualize JSON will help you to read and navigate this API like a blazing fast website.

Caching Guidance.

 Not sure how long to hold onto ReliefWeb data? Since it updates all the time we’ve added Cache-Control headers to point out how often we recommend checking for updates. This is a sweet spot that favors accuracy but still gives the opportunity to save on bandwidth.

Bring Your Next Project

Sound like an API that would benefit your mission? Let us know your thoughts and ideas! We believe the best innovations come from developers like you, and like I said, we’re so excited to see what kinds of innovations this resourceful community creates using ReliefWeb’s data. Get started with ReliefWeb’s developer portal, and tweet us about current or future projects so we can feature you on our website! For more information, check out ReliefWeb's launch announcement or read our case study.

Adam Ross

Software Architect