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 Benin BEN
#> 5 Bolivia (Plurinational State of) BOL
#> 6 Burkina Faso BFAThe 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 numPresentIdpInd
#> 1 209494 Countrywide monitoring Ethiopia ETH 1696145
#> 2 209495 Countrywide monitoring Ethiopia ETH 1742461
#> 3 209496 Countrywide monitoring Ethiopia ETH 1613436
#> 4 209715 Northern Ethiopia Crisis Ethiopia ETH 131590
#> 5 209716 Northern Ethiopia Crisis Ethiopia ETH 378392
#> 6 209717 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 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', 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 1709593 Darfur conflict Sudan SDN North Darfur SD02
#> 2 1710019 Darfur conflict Sudan SDN South Darfur SD03
#> 3 1712235 Darfur conflict Sudan SDN East Darfur SD05
#> 4 1711984 Darfur conflict Sudan SDN Central Darfur SD06
#> 5 1710547 Darfur conflict Sudan SDN West Darfur SD04
#> 6 1710053 Darfur conflict Sudan SDN South Kordofan SD07
#> numPresentIdpInd reportingDate yearReportingDate monthReportingDate
#> 1 503200 2020-01-30T00:00:00 2020 1
#> 2 793328 2020-01-30T00:00:00 2020 1
#> 3 99697 2020-01-30T00:00:00 2020 1
#> 4 377209 2020-01-30T00:00:00 2020 1
#> 5 335301 2020-01-30T00:00:00 2020 1
#> 6 217683 2020-01-30T00:00:00 2020 1
#> roundNumber assessmentType
#> 1 1 BA
#> 2 1 BA
#> 3 1 BA
#> 4 1 BA
#> 5 1 BA
#> 6 1 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 11556526 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 2 11556527 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 3 11556448 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 4 11556449 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 5 11556604 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 6 11556605 Displacement due to conflict Lebanon LBN Mount Lebanon
#> admin1Pcode admin2Name admin2Pcode numPresentIdpInd reportingDate
#> 1 LB3 Jbeil LB34 15 2023-10-15T00:00:00
#> 2 LB3 Jbeil LB34 86 2023-10-15T00:00:00
#> 3 LB3 El Meten LB36 75 2023-10-15T00:00:00
#> 4 LB3 El Meten LB36 125 2023-10-15T00:00:00
#> 5 LB3 Kesrwane LB35 35 2023-10-15T00:00:00
#> 6 LB3 Kesrwane LB35 35 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 2 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.