README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```



# Wrapper for the UN OCHA ReliefWeb Disaster Events API

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version-last-release/disastr.api)](https://CRAN.R-project.org/package=disastr.api/)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable/)
[![Travis build status](https://travis-ci.com/chris-dworschak/disastr.api.svg?branch=master)](https://travis-ci.com/gitlab/chris-dworschak/disastr.api/)
[![License: GPL-3](https://img.shields.io/badge/License-GPLv3-lightgrey.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![CRANlogs](http://cranlogs.r-pkg.org/badges/grand-total/disastr.api)](https://CRAN.R-project.org/package=disastr.api/)
<!-- badges: end -->

This package provides functionality to access and manage the application programming interface (API) of the [United Nations Office for the Coordination of Humanitarian Affairs' (OCHA) ReliefWeb disaster events](https://reliefweb.int/disasters). It requires a minimal number of dependencies. The function `disastr.api()` makes it easy to retrieve a user-defined sample of disaster events from ReliefWeb, enabling a seamless integration of regular data updates into the research work flow.




## Installation

You can install the released version of disastr.api from [CRAN](https://CRAN.R-project.org/) with: 

``` r
install.packages("disastr.api") # downloads and installs the package from CRAN
```

You can install the development version from [GitLab](https://gitlab.com/chris-dworschak/) with: 

``` r
remotes::install_gitlab("chris-dworschak/disastr.api") # downloads and installs the package from GitLab
```


## Example

Using `disastr.api` is straight forward. To download data on, for example, the last 20 disaster events, you can supply:


```{r example}
library(disastr.api) # loads the package

my.data.frame <- disastr.api( # stores retrieved disaster events in object my.data.frame
  limit = 20)

head(my.data.frame) # returns the first five observations of the ACLED sample
```