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:
Install Package
The dtmapi package is available on CRAN and can be
installed using the following command: :
install.packages("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)
#> admin0Name admin0Pcode
#> 1 Afghanistan AFG
#> 2 Antigua and Barbuda ATG
#> 3 Bahamas (the) BHS
#> 4 Bolivia (Plurinational State of) BOL
#> 5 Burkina Faso BFA
#> 6 Burundi BDIGet 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)
#> operation operationStatus admin0Name
#> 1 Aceh earthquake Inactive Indonesia
#> 2 Armed Clashes in Sudan Active Sudan
#> 3 Armed Clashes in Sudan (Monthly) Active Sudan
#> 4 Armed Clashes in Sudan (Overview) Active Sudan
#> 5 Arrivals in Armenia Active Republic of Armenia
#> 6 Bahamas (the) - Hurricane Dorian Response Inactive Bahamas (the)
#> admin0Pcode
#> 1 IDN
#> 2 SDN
#> 3 SDN
#> 4 SDN
#> 5 ARM
#> 6 BHSGet 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)
#> id operation admin0Name admin0Pcode numPresentIdpInd
#> 1 9217 Countrywide monitoring Ethiopia ETH 1696145
#> 2 9218 Countrywide monitoring Ethiopia ETH 1742461
#> 3 9219 Countrywide monitoring Ethiopia ETH 1613436
#> 4 8427 Northern Ethiopia Crisis Ethiopia ETH 131590
#> 5 8428 Northern Ethiopia Crisis Ethiopia ETH 378392
#> 6 8429 Northern Ethiopia Crisis Ethiopia ETH 1025676
#> reportingDate yearReportingDate monthReportingDate roundNumber
#> 1 2017-12-31T00:00:00 2017 12 8
#> 2 2018-02-28T00:00:00 2018 2 9
#> 3 2018-04-30T00:00:00 2018 4 10
#> 4 2021-01-31T00:00:00 2021 1 2
#> 5 2021-02-28T00:00:00 2021 2 3
#> 6 2021-03-31T00:00:00 2021 3 4
#> assessmentType
#> 1 SA
#> 2 SA
#> 3 SA
#> 4 SA
#> 5 SA
#> 6 SAGet 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)
#> id operation admin0Name admin0Pcode admin1Name admin1Pcode
#> 1 58149 Darfur conflict Sudan SDN Blue Nile SD08
#> 2 58150 Darfur conflict Sudan SDN Blue Nile SD08
#> 3 58151 Darfur conflict Sudan SDN Blue Nile SD08
#> 4 58152 Darfur conflict Sudan SDN Blue Nile SD08
#> 5 66550 Armed Clashes in Sudan Sudan SDN Blue Nile SD08
#> 6 66551 Armed Clashes in Sudan Sudan SDN Blue Nile SD08
#> numPresentIdpInd reportingDate yearReportingDate monthReportingDate
#> 1 81693 2021-03-30T00:00:00 2021 3
#> 2 130958 2021-12-31T00:00:00 2021 12
#> 3 151156 2022-01-31T00:00:00 2022 1
#> 4 152656 2022-03-30T00:00:00 2022 3
#> 5 260 2023-04-28T00:00:00 2023 4
#> 6 715 2023-05-07T00:00:00 2023 5
#> roundNumber assessmentType
#> 1 2 BA
#> 2 3 BA
#> 3 4 BA
#> 4 5 BA
#> 5 2 BA
#> 6 3 BAGet 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)
#> id operation admin0Name admin0Pcode admin1Name
#> 1 401077 Displacement due to conflict Lebanon LBN Baalbek-El Hermel
#> 2 401078 Displacement due to conflict Lebanon LBN Baalbek-El Hermel
#> 3 401118 Displacement due to conflict Lebanon LBN Baalbek-El Hermel
#> 4 401119 Displacement due to conflict Lebanon LBN Baalbek-El Hermel
#> 5 409095 Displacement due to conflict Lebanon LBN Beirut
#> 6 409096 Displacement due to conflict Lebanon LBN Beirut
#> admin1Pcode admin2Name admin2Pcode numPresentIdpInd reportingDate
#> 1 LB8 Baalbek LB21 18 2023-10-15T00:00:00
#> 2 LB8 Baalbek LB21 903 2023-10-15T00:00:00
#> 3 LB8 El Hermel LB22 45 2023-10-15T00:00:00
#> 4 LB8 El Hermel LB22 100 2023-10-15T00:00:00
#> 5 LB1 Baabda LB32 10 2023-10-15T00:00:00
#> 6 LB1 Beirut LB11 1854 2023-10-15T00:00:00
#> yearReportingDate monthReportingDate roundNumber assessmentType
#> 1 2023 10 1 BA
#> 2 2023 10 2 BA
#> 3 2023 10 1 BA
#> 4 2023 10 2 BA
#> 5 2023 10 1 BA
#> 6 2023 10 1 BAFunction 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.