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 Inactive 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 501655 Countrywide monitoring Ethiopia ETH 1696145
#> 2 501656 Countrywide monitoring Ethiopia ETH 1742461
#> 3 501657 Countrywide monitoring Ethiopia ETH 1613436
#> 4 502162 Northern Ethiopia Crisis Ethiopia ETH 131590
#> 5 502163 Northern Ethiopia Crisis Ethiopia ETH 378392
#> 6 502164 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', 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 4129123 Darfur conflict Sudan SDN Blue Nile SD08
#> 2 4129124 Darfur conflict Sudan SDN Blue Nile SD08
#> 3 4129125 Darfur conflict Sudan SDN Blue Nile SD08
#> 4 4129351 Darfur conflict Sudan SDN Blue Nile SD08
#> 5 4132013 Armed Clashes in Sudan Sudan SDN Blue Nile SD08
#> 6 4132014 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 27484430 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 2 27484431 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 3 27484256 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 4 27484257 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 5 27475266 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 6 27475267 Displacement due to conflict Lebanon LBN Mount Lebanon
#> admin1Pcode admin2Name admin2Pcode numPresentIdpInd reportingDate
#> 1 LB3 El Meten LB36 75 2023-10-15T00:00:00
#> 2 LB3 El Meten LB36 125 2023-10-15T00:00:00
#> 3 LB3 Baabda LB32 671 2023-10-15T00:00:00
#> 4 LB3 Baabda LB32 916 2023-10-15T00:00:00
#> 5 LB3 Aley LB31 427 2023-10-15T00:00:00
#> 6 LB3 Aley LB31 776 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.