dtmapi

In dtmapi: Fetching Data from the 'Displacement Tracking Matrix'

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: :

install.packages("dtmapi")

Load Package

After installation, load the package using library():

library(dtmapi)

Get All Countries

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

# 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.

# 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.

# 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.

# 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

# 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.

dtmapi documentation built on June 23, 2025, 5:08 p.m.