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()
The dtmapi package is available on CRAN and can be
installed using the following command: :
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 BDIThe 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 BHSThe 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
#> 1 824 Countrywide monitoring Ethiopia ETH
#> 2 148 Countrywide monitoring Ethiopia ETH
#> 3 834 Countrywide monitoring Ethiopia ETH
#> 4 869 Ethiopia - Gedeo and West Guji Rapid Response Ethiopia ETH
#> 5 293 Northern Ethiopia Crisis Ethiopia ETH
#> 6 300 Northern Ethiopia Crisis Ethiopia ETH
#> numPresentIdpInd reportingDate yearReportingDate monthReportingDate
#> 1 1696145 2017-12-31T00:00:00 2017 12
#> 2 1742461 2018-02-28T00:00:00 2018 2
#> 3 1613436 2018-04-30T00:00:00 2018 4
#> 4 359113 2018-07-30T00:00:00 2018 7
#> 5 131590 2021-01-31T00:00:00 2021 1
#> 6 378392 2021-02-28T00:00:00 2021 2
#> roundNumber assessmentType
#> 1 8 SA
#> 2 9 SA
#> 3 10 SA
#> 4 1 SA
#> 5 2 SA
#> 6 3 SAThe 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 1663 Darfur conflict Sudan SDN Blue Nile SD08
#> 2 1664 Darfur conflict Sudan SDN Blue Nile SD08
#> 3 1665 Darfur conflict Sudan SDN Blue Nile SD08
#> 4 1666 Darfur conflict Sudan SDN Blue Nile SD08
#> 5 6290 Armed Clashes in Sudan Sudan SDN Blue Nile SD08
#> 6 6291 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 BAThe 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 48424 Displacement due to conflict Lebanon LBN Baalbek-El Hermel
#> 2 48425 Displacement due to conflict Lebanon LBN Baalbek-El Hermel
#> 3 48486 Displacement due to conflict Lebanon LBN Beirut
#> 4 48487 Displacement due to conflict Lebanon LBN Beirut
#> 5 48488 Displacement due to conflict Lebanon LBN Beirut
#> 6 48455 Displacement due to conflict Lebanon LBN Baalbek-El Hermel
#> 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 LB1 Baabda LB32 10 2023-10-15T00:00:00
#> 4 LB1 Beirut LB11 1854 2023-10-15T00:00:00
#> 5 LB1 Beirut LB11 1758 2023-10-15T00:00:00
#> 6 LB8 El Hermel LB22 45 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 1 BA
#> 5 2023 10 2 BA
#> 6 2023 10 1 BAHere 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.
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.