This update to the premier source of humanitarian data worldwide will help international aid organizations by simplifying access, improving data flexibility, and improving the system's performance and robustness.
ReliefWeb is a data service created by the United Nations Office for the Coordination of Humanitarian Affairs (OCHA). Their RESTful API delivers both breaking news updates on current disasters and historical information on prior disasters around the world. In addition to 17 years of disaster data, the database includes UN reports on major disasters as far back as the 1980s. The API also provides a clearinghouse for job and training opportunities in the field of humanitarian relief.
This release, identified as version 1, builds off of the former API, now known as version 0. ReliefWeb has greatly improved the developer experience by making significant changes, both on the front end (API layout) and the back end (underlying infrastructure). Primary design goals included flexibility and ease of learning to lower barriers to entry, as well as the ability to scale up as demand grows. In addition, they've adopted Continuous Integration practices with automated build, deployments, and regression testing.
Version 1 of the API is HATEOAS-compliant. In addition to good Swagger-based documentation, there is also an API usage guide. The API includes several advanced query features, such as:
- filtering queries by the contents of an arbitrary field, either by exact match or fuzzy search,
- limiting which fields come down from the server on queries,
- sorting by any number of fields, and
- paging by offset and limit.
The addition of rate limiting prevents the system from being overwhelmed. The API restricts users to 1,000 results per query and 1,000 calls per day. Data from the API is only available in JSON format. An envelope holds the data, links, and other meta-information in all API responses. If an error occurs, a JSON response contains details explaining the cause and possible remedies.
For example, to search for reports on hurricane Katrina's impact on the USA, a user might call
GET http://api.rwlabs.org:80/v1/reports?limit=2&query[value]=katrina&filter[field]=primary_country&filter[value]=usa
to get the first 2 of 571 reports:
{
"href": "http://api.rwlabs.org/v1/reports?limit=2&query%5Bvalue%5D=katrina&filter%5Bfield%5D=primary_country&filter%5Bvalue%5D=usa",
"time": 7,
"version": "1",
"links": {
"self": {
"href": "http://api.rwlabs.org/v1/reports?offset=0&limit=10"
},
"next": {
"href": "http://api.rwlabs.org/v1/reports?offset=10&limit=10"
}
},
"totalCount": 571,
"count": 2,
"data": [
{
"id": "185148",
"score": 4.980242,
"href": "http://api.rwlabs.org/v1/reports/185148",
"fields": {
"title": "Hurricane Katrina"
}
},
{
"id": "416571",
"score": 4.216302,
"href": "http://api.rwlabs.org/v1/reports/416571",
"fields": {
"title": "Katrina Index: Tracking variables of post-Katrina reconstruction"
}
}
]
}
By default, the results are sorted by score, which is determined by the quality of the match on the query fields. It is possible to follow the href URI on any result to drill down and get the details on a report, or follow the next link to get the next page of results.
The ReliefWeb API is a PHP application written using the Klein framework, with Drupal used as the CMS. According to Adam Ross, who worked on the project, it's written as
[...] 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.
ReliefWeb is the leading source of information for the humanitarian community. Many governments and NGOs rely solely on ReliefWeb for their data needs in the humanitarian field. Journalists and media also use ReliefWeb to help them track ongoing disasters. ReliefWeb gathers information from over 4,000 sources worldwide. Their 30 editors review, edit, and tag information from these sources and publish it for the community.