---
title: "dtmapi"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(httr2)
```

## Introduction

The `dtmapi` package provides functions to interact with the Displacement Tracking Matrix (DTM) API. This vignette demonstrates how to use the package's functions to fetch data from the API. The functions covered include:

-   `get_all_countries()`

-   `get_all_operations()`

-   `get_idp_admin0_data()`

-   `get_idp_admin1_data()`

-   `get_idp_admin2_data()`


## Install Package

The `dtmapi` package is available on CRAN and can be installed using the following command: :
```{r install , eval = FALSE}
install.packages("dtmapi")
```

## Load Package

After installation, load the package using library():
```{r setup}
library(dtmapi)
```

## Get All Countries

The `get_all_countries()` function retrieves a list of all countries from the DTM API.

```{r get_country}
# Fetch all countries
countries_df <- get_all_countries()

# Display the first few rows of the data frame
head(countries_df)
```

## Get All Operations

The `get_all_operations()` function retrieves a list of all operations from the DTM API.

```{r get_operations}
# Fetch all operations
operations_df <- get_all_operations()

# Display the first few rows of the data frame
head(operations_df)
```

## Get IDP Data at Admin Level 0

The `get_idp_admin0_data()` function retrieves Internally Displaced Persons (IDP) data aggregated at the country level.

```{r get_idp_admin0}
# Fetch IDP data at Admin Level 0
idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10)

# Display the first few rows of the data frame
head(idp_admin0_df)
```

## Get IDP Data at Admin Level 1

The get_idp_admin1_data() function retrieves IDP data aggregated at Admin Level 1.

```{r get_idp_admin1}
# Fetch IDP data at Admin Level 1
idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile", FromReportingDate='2020-01-01', ToReportingDate='2024-08-15')

# Display the first few rows of the data frame
head(idp_admin1_df)
```

## Get IDP Data at Admin Level 2

The get_idp_admin2_data() function retrieves IDP data aggregated at Admin Level 2
```{r get_idp_admin2}
# Fetch IDP data at Admin Level 2
idp_admin2_df <- get_idp_admin2_data(Operation="Displacement due to conflict", CountryName='Lebanon')

# Display the first few rows of the data frame
head(idp_admin2_df)
```
## Function Arguments

Here are the descriptions for the arguments used in the functions of the `dtmapi` package to get IDP data. At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode.

### Arguments

- **Operation**: Optional; Name of the DTM operation for which the data was collected.

- **CountryName**: Optional; Name of the country where the data was collected.

- **Admin0Pcode**: Optional; Country code (ISO 3166-1 alpha-3).

- **Admin1Name**: Optional; Name of level 1 administrative boundaries.

- **Admin1Pcode**: Optional; Place code of level 1 administrative boundaries.

- **Admin2Name**: Optional; Name of level 2 administrative boundaries.

- **Admin2Pcode**: Optional; Place code of level 2 administrative boundaries.

- **FromReportingDate**: Optional; Start date for the reporting period (format: 'YYYY-MM-DD').

- **ToReportingDate**: Optional; End date for the reporting period (format: 'YYYY-MM-DD').

- **FromRoundNumber**: Optional; Starting round number for the data collection range.

- **ToRoundNumber**: Optional; Ending round number for the data collection range.