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:
After creating a subscription key on https://dtm-apim-portal.iom.int, that key needs to be given to R. There are two main ways to do this.
set_subscription_key() and then typing in
the key.The user will be prompted to input the key into a pop-up field.
If one would like to avoid re-inputting the subscription key for each
R session, an alternative approach is to create the environment variable
DTM_SUBSCRIPTION_KEY, with the subscription key as its
value. Ideally, this should be (a) done in a .Renviron file,
and (b) through the use of R projects or other means of
organising files (e.g. if one is using VS Code:
workspaces).
One quick way to get started is by calling the following line of code, if one is using an R project or equivalent:
Or, if one is not using an R project or equivalent:
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 = 0,
ToRoundNumber = 10)
# Display the first few rows of the data frame
head(idp_admin0_df)
#> operation admin0Name admin0Pcode numPresentIdpInd
#> 1 Countrywide monitoring Ethiopia ETH 7823
#> 2 Countrywide monitoring Ethiopia ETH 21668
#> 3 Countrywide monitoring Ethiopia ETH 15420
#> 4 Countrywide monitoring Ethiopia ETH 772924
#> 5 Countrywide monitoring Ethiopia ETH 308300
#> 6 Countrywide monitoring Ethiopia ETH 6984
#> reportingDate yearReportingDate monthReportingDate roundNumber
#> 1 2017-12-31T00:00:00 2017 12 8
#> 2 2017-12-31T00:00:00 2017 12 8
#> 3 2017-12-31T00:00:00 2017 12 8
#> 4 2017-12-31T00:00:00 2017 12 8
#> 5 2017-12-31T00:00:00 2017 12 8
#> 6 2017-12-31T00:00:00 2017 12 8
#> displacementReason numberMales numberFemales idpOriginAdmin1Name
#> 1 Conflict 4088 3735 Afar
#> 2 Conflict 11490 10178 Amhara
#> 3 Conflict 7046 8374 Gambela
#> 4 Conflict 375655 397269 Oromia
#> 5 Conflict 152469 155831 Somali
#> 6 Conflict 3170 3814 Tigray
#> idpOriginAdmin1Pcode assessmentType
#> 1 ET02 SA
#> 2 ET03 SA
#> 3 ET12 SA
#> 4 ET04 SA
#> 5 ET05 SA
#> 6 ET01 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 4277072 Darfur conflict Sudan SDN Blue Nile SD08
#> 2 4277073 Darfur conflict Sudan SDN Blue Nile SD08
#> 3 4277074 Darfur conflict Sudan SDN Blue Nile SD08
#> 4 4277075 Darfur conflict Sudan SDN Blue Nile SD08
#> 5 4255941 Armed Clashes in Sudan Sudan SDN Blue Nile SD08
#> 6 4255942 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 displacementReason numberMales numberFemales
#> 1 2 Conflict NA NA
#> 2 3 Conflict; Natural disaster NA NA
#> 3 4 Conflict NA NA
#> 4 5 Conflict NA NA
#> 5 2 Conflict NA NA
#> 6 3 Conflict NA NA
#> idpOriginAdmin1Name idpOriginAdmin1Pcode assessmentType
#> 1 Blue Nile SD08 BA
#> 2 Blue Nile SD08 BA
#> 3 Not available Not available BA
#> 4 Blue Nile SD08 BA
#> 5 West Darfur SD04 BA
#> 6 Khartoum SD01 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 17490733 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 2 17491237 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 3 17496916 Displacement due to conflict Lebanon LBN Beirut
#> 4 17498945 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 5 17502015 Displacement due to conflict Lebanon LBN Mount Lebanon
#> 6 17502022 Displacement due to conflict Lebanon LBN El Nabatieh
#> admin1Pcode admin2Name admin2Pcode numPresentIdpInd reportingDate
#> 1 LB3 Baabda LB32 10 2023-10-15T00:00:00
#> 2 LB3 Aley LB31 364 2023-10-15T00:00:00
#> 3 LB1 Beirut LB11 25 2023-10-15T00:00:00
#> 4 LB3 Chouf LB33 41 2023-10-15T00:00:00
#> 5 LB3 Baabda LB32 591 2023-10-15T00:00:00
#> 6 LB4 Hasbaya LB42 150 2023-10-15T00:00:00
#> yearReportingDate monthReportingDate roundNumber displacementReason
#> 1 2023 10 2 Conflict
#> 2 2023 10 2 Conflict
#> 3 2023 10 1 Conflict
#> 4 2023 10 2 Conflict
#> 5 2023 10 1 Conflict
#> 6 2023 10 1 Conflict
#> numberMales numberFemales idpOriginAdmin1Name idpOriginAdmin1Pcode
#> 1 NA NA Mount Lebanon LB3
#> 2 NA NA El Nabatieh LB4
#> 3 NA NA Mount Lebanon LB3
#> 4 NA NA Mount Lebanon LB3
#> 5 NA NA El Nabatieh LB4
#> 6 NA NA El Nabatieh LB4
#> assessmentType
#> 1 BA
#> 2 BA
#> 3 BA
#> 4 BA
#> 5 BA
#> 6 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.