About
dtmapi is an R package developed by Displacement Tracking Matrix (DTM). This package allows the humanitarian community, academia, media, government, and non-governmental organizations to utilize the data collected by DTM. It provides non-sensitive Internally Displaced Person (IDP) figures, aggregated at the country, Admin 1 (states, provinces, or equivalent), and Admin 2 (smaller subnational administrative areas) levels. Country Names and Operations can be found in this data coverage matrix.
Please note that despite the overarching term DTM API, there are, in fact, two distinct APIs which are currently available. These are the Baseline API (which is what simply “the DTM API” USED to refer to) and the Household Needs Assessment (HNA) API. Reflecting this, the functions in dtmapi are clearly named so as to distinguish between these two APIs: those prefixed with baseline_ and those prefixed with hna_.
Please find more information about DTM API here.
Installation
The latest version of the dtmapi package can be installed directly from GitHub as follows (make sure the remotes package is installed):
remotes::install_github("Displacement-Tracking-Matrix/dtmapi-R")Pre-Requisites
Using dtmapi requires a subscription key. To obtain one, register with the DTM API Portal and follow the instructions there.
As a consequence of there being two distinct APIs, there are also two distinct subscription keys: the baseline_ functions use the BASELINE_DTM_SUBSCRIPTION_KEY environment variable, and the hna_ functions use the HNA_DTM_SUBSCRIPTION_KEY environment variable.
The subscription key is secret and should not be exposed. Once it is obtained, the subscription key should be set for your current R session, assuming that the dtmapi package is installed. To do this, the relevant environment variable needs to be defined. This can be done either interactively or non-interactively. The examples below use the Baseline key; the HNA key works the same way, with hna_set_subscription_key() in place of baseline_set_subscription_key().
The interactive option is to call baseline_set_subscription_key(), like so:
dtmapi::baseline_set_subscription_key()At this point, the user will be prompted to input the key (hidden) into a pop-up field.
Some environments are non-interactive, and so running the above will likely result in an error. In such a case, the subscription key may be set non-interactively, by specifying the key parameter, like so:
# Specifying `key` is required for non-interactive use.
dtmapi::baseline_set_subscription_key(key = "mysubscriptionkey")However, this option is discouraged and should be avoided as much as possible, because it blatantly exposes the subscription key. The best option would be to engage in good secrets management practices, such as by using a .Renviron file (if applicable). Basic secrets management, and the issue of setting the subscription key in general, is elaborated on in more detail in vignette("user_guide").
Usage
When the Baseline subscription key is set, data on internal displacement may be retrieved through any of the following functions:
These all retrieve data from the DTM API and return said data in the form of data frames.
Certain parameters have to be specified to any of these, the most important of which are either the admin0_name or the operation. For information on the other parameters and indeed all functions in dtmapi, see the documentation here.
As a representative example of the earlier mentioned functions, see the following use of baseline_get_admin1():
# Load the package
library(dtmapi)
idp_admin1_df <- baseline_get_admin1(admin0_name = "Sudan",
from_reporting_date = "2020-01-01",
to_reporting_date = "2024-08-15")
# Display the first few rows of the data frame
head(idp_admin1_df)
#> id operation admin0Name admin0Pcode admin1Name admin1Pcode
#> 1 20177 Darfur conflict Sudan SDN Central Darfur SD06
#> 2 20178 Darfur conflict Sudan SDN Central Darfur SD06
#> 3 29481 Darfur conflict Sudan SDN South Kordofan SD07
#> 4 20254 Darfur conflict Sudan SDN East Darfur SD05
#> 5 20255 Darfur conflict Sudan SDN East Darfur SD05
#> 6 20256 Darfur conflict Sudan SDN East Darfur SD05
#> numPresentIdpInd reportingDate yearReportingDate monthReportingDate
#> 1 349709 2020-01-30T00:00:00 2020 1
#> 2 27500 2020-01-30T00:00:00 2020 1
#> 3 217683 2020-01-30T00:00:00 2020 1
#> 4 92867 2020-01-30T00:00:00 2020 1
#> 5 6230 2020-01-30T00:00:00 2020 1
#> 6 600 2020-01-30T00:00:00 2020 1
#> roundNumber displacementReason numberMales numberFemales idpOriginAdmin1Name
#> 1 1 Conflict NA NA Central Darfur
#> 2 1 Conflict NA NA North Darfur
#> 3 1 Conflict NA NA South Kordofan
#> 4 1 Conflict NA NA East Darfur
#> 5 1 Conflict NA NA North Darfur
#> 6 1 Conflict NA NA South Darfur
#> idpOriginAdmin1Pcode assessmentType
#> 1 SD06 BA
#> 2 SD02 BA
#> 3 SD07 BA
#> 4 SD05 BA
#> 5 SD02 BA
#> 6 SD03 BASince the available country names or operation names are often necessary to know of, they can be obtained by using the baseline_get_countries() and baseline_get_operations() functions, which do not take any arguments.
# Load the package
library(dtmapi)
countries_df <- baseline_get_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 Bangladesh BGD
#> 5 Benin BEN
#> 6 Bolivia (Plurinational State of) BOL
# Load the package
library(dtmapi)
operations_df <- baseline_get_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 As-Sweida Conflict Active Syrian Arab Republic
#> admin0Pcode
#> 1 IDN
#> 2 SDN
#> 3 SDN
#> 4 SDN
#> 5 ARM
#> 6 SYRWhen the HNA subscription key is set, HNA data at Admin Level 2 may be retrieved through hna_get_admin2(). Unlike the baseline_ functions, it returns a list of two elements: data, a data frame holding the requested data, and pagination, a list containing metadata on pagination. This metadata is relative to the data returned, of course, rather than being about the API’s pagination in general.
# Load the package
library(dtmapi)
hna_admin2 <- hna_get_admin2(
admin0_name = "Mozambique",
year = 2025
)
# Compare the data frame, previewed here:
head(hna_admin2$data)
#> id m3693_meta_adm0_name m0302_meta_adm0_pcode m3694_meta_adm1_name
#> 1 59 Mozambique MOZ Cabo Delgado
#> 2 66 Mozambique MOZ Cabo Delgado
#> 3 118 Mozambique MOZ Cabo Delgado
#> 4 121 Mozambique MOZ Cabo Delgado
#> 5 176 Mozambique MOZ Nampula
#> 6 208 Mozambique MOZ Niassa
#> m0303_meta_adm1_pcode m3695_meta_adm2_name m0304_meta_adm2_pcode year
#> 1 MZ01 Ibo MZ0105 2025
#> 2 MZ01 Mocimboa Da Praia MZ0110 2025
#> 3 MZ01 Ancuabe MZ0101 2025
#> 4 MZ01 Metuge MZ0109 2025
#> 5 MZ07 Cidade De Nampula MZ0702 2025
#> 6 MZ08 Mecula MZ0814 2025
#> m2788_loc_assessment_strata num_households num_m2661_hh_members
#> 1 Non displaced 265 1126
#> 2 IDP 200 755
#> 3 Non displaced 282 1184
#> 4 Non displaced 287 1223
#> 5 IDP 256 1134
#> 6 Non displaced 269 1047
#> mean_num_m26611_hh_members mean_num_m3674_hh_num_female_0_17
#> 1 4.2 0.8
#> 2 3.8 0.7
#> 3 4.2 1.0
#> 4 4.3 1.3
#> 5 4.4 1.1
#> 6 3.9 0.3
#> mean_num_m3677_hh_num_male_0_17 mean_num_m3675_hh_num_female_18_59
#> 1 0.9 1.1
#> 2 0.7 1.1
#> 3 1.0 1.1
#> 4 0.8 1.2
#> 5 0.8 1.4
#> 6 0.5 1.3
#> mean_num_m3678_hh_num_male_18_59 mean_num_m3676_hh_num_female_60_plus
#> 1 1.1 0.1
#> 2 1.1 0.0
#> 3 0.9 0.1
#> 4 0.8 0.1
#> 5 0.9 0.0
#> 6 1.3 0.2
#> mean_num_m3679_hh_num_male_60_plus mean_num_m3680_hh_num_female
#> 1 0.2 2.0
#> 2 0.1 1.9
#> 3 0.1 2.2
#> 4 0.1 2.5
#> 5 0.1 2.6
#> 6 0.3 1.8
#> mean_num_m3681_hh_num_male pct_hh_m2671_hh_ddc_disp_reason_primary_conflict
#> 1 2.2 NA
#> 2 1.9 NA
#> 3 2.0 NA
#> 4 1.8 NA
#> 5 1.8 NA
#> 6 2.1 NA
#> pct_hh_m2671_hh_ddc_disp_reason_primary_disaster_climate
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2671_hh_ddc_disp_reason_primary_disaster_non_climate
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2671_hh_ddc_disp_reason_primary_other mean_i0001_hh_fcs_score
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_i0002_hh_fcs_category_acceptable
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_i0002_hh_fcs_category_borderline pct_hh_i0002_hh_fcs_category_poor
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> mean_i0007_hh_hhs_score pct_hh_i0008_hh_hhs_category_none
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_i0008_hh_hhs_category_little pct_hh_i0008_hh_hhs_category_moderate
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_i0008_hh_hhs_category_severe pct_hh_i0008_hh_hhs_category_very_severe
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> mean_i0001_hh_rcsi_score pct_hh_i0002_hh_rcsi_category_phase1
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_i0002_hh_rcsi_category_phase2 pct_hh_i0002_hh_rcsi_category_phase3
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_i0002_hh_rcsi_category_phase4 pct_hh_i0004_hh_lcs_category_none
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_i0004_hh_lcs_category_stress pct_hh_i0004_hh_lcs_category_crisis
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_i0004_hh_lcs_category_emergency num_hh_m2879_hh_shelter_damage_type
#> 1 NA 261
#> 2 NA 192
#> 3 NA 280
#> 4 NA 287
#> 5 NA 256
#> 6 NA 246
#> pct_hh_m2879_hh_shelter_damage_type_floor
#> 1 4.598
#> 2 23.438
#> 3 9.643
#> 4 13.240
#> 5 6.641
#> 6 5.285
#> pct_hh_m2879_hh_shelter_damage_type_none
#> 1 42.912
#> 2 23.958
#> 3 48.571
#> 4 25.436
#> 5 60.547
#> 6 39.024
#> pct_hh_m2879_hh_shelter_damage_type_walls
#> 1 16.475
#> 2 51.042
#> 3 23.571
#> 4 8.014
#> 5 17.969
#> 6 7.317
#> pct_hh_m2879_hh_shelter_damage_type_windows_doors
#> 1 14.176
#> 2 10.938
#> 3 4.286
#> 4 12.195
#> 5 1.563
#> 6 21.545
#> pct_hh_m2879_hh_shelter_damage_type_roof
#> 1 3.448
#> 2 5.729
#> 3 7.500
#> 4 16.028
#> 5 0.781
#> 6 19.512
#> pct_hh_m2879_hh_shelter_damage_type_roof_partial
#> 1 31.034
#> 2 26.042
#> 3 30.357
#> 4 33.798
#> 5 21.875
#> 6 31.707
#> num_hh_m2880_hh_shelter_enclosure_issues
#> 1 261
#> 2 192
#> 3 280
#> 4 287
#> 5 256
#> 6 246
#> pct_hh_m2880_hh_shelter_enclosure_issues_ventilation
#> 1 0.000
#> 2 5.729
#> 3 10.714
#> 4 3.484
#> 5 1.172
#> 6 0.813
#> pct_hh_m2880_hh_shelter_enclosure_issues_none
#> 1 46.360
#> 2 33.854
#> 3 17.143
#> 4 27.178
#> 5 69.922
#> 6 42.276
#> pct_hh_m2880_hh_shelter_enclosure_issues_privacy
#> 1 22.989
#> 2 39.063
#> 3 12.143
#> 4 14.634
#> 5 2.344
#> 6 39.024
#> pct_hh_m2880_hh_shelter_enclosure_issues_insulation
#> 1 13.027
#> 2 13.542
#> 3 9.643
#> 4 19.164
#> 5 7.422
#> 6 5.285
#> pct_hh_m2880_hh_shelter_enclosure_issues_leakage_rain
#> 1 14.176
#> 2 30.208
#> 3 36.786
#> 4 16.725
#> 5 24.609
#> 6 3.659
#> pct_hh_m2880_hh_shelter_enclosure_issues_dnk
#> 1 0.383
#> 2 5.208
#> 3 0.357
#> 4 0.000
#> 5 0.000
#> 6 3.252
#> pct_hh_m2880_hh_shelter_enclosure_issues_pnta
#> 1 0.000
#> 2 3.125
#> 3 0.000
#> 4 0.000
#> 5 0.000
#> 6 1.220
#> pct_hh_m2880_hh_shelter_enclosure_issues_flooding
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2880_hh_shelter_enclosure_issues_space
#> 1 18.391
#> 2 20.833
#> 3 13.571
#> 4 13.240
#> 5 4.297
#> 6 21.138
#> pct_hh_m2880_hh_shelter_enclosure_issues_lock
#> 1 1.533
#> 2 7.292
#> 3 2.500
#> 4 0.697
#> 5 0.391
#> 6 0.000
#> num_hh_m2954_health_barriers_encountered
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_documentation
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_fear_deportation
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_other
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_legal
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_insecurity
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_language
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_dnk
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_transport
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_distance
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_discrimination
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_access_intermittent
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_insurance
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_finances
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_none
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_pnta
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_female_staff
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2954_health_barriers_encountered_dnk_where
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> num_hh_m2938_sanitation_problems pct_hh_m2938_sanitation_problems_drainage
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2938_sanitation_problems_discrimination
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_no_segregation
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_security
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_distance
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_no_privacy
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_crowded
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_unclean
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_not_functioning
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_garbage_collection
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2938_sanitation_problems_dnk pct_hh_m2938_sanitation_problems_other
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2938_sanitation_problems_pnta num_hh_m2730_hh_priority_needs
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2730_hh_priority_needs_none pct_hh_m2730_hh_priority_needs_sanitation
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2730_hh_priority_needs_access_market
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2730_hh_priority_needs_food pct_hh_m2730_hh_priority_needs_education
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2730_hh_priority_needs_shelter pct_hh_m2730_hh_priority_needs_health
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2730_hh_priority_needs_nfi pct_hh_m2730_hh_priority_needs_water
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2730_hh_priority_needs_security
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2730_hh_priority_needs_return_support
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2730_hh_priority_needs_pss pct_hh_m2730_hh_priority_needs_cash
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2730_hh_priority_needs_legal_consular
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2730_hh_priority_needs_reunification
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2730_hh_priority_needs_livelihood
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
#> pct_hh_m2730_hh_priority_needs_other pct_hh_m2730_hh_priority_needs_pnta
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA
#> 6 NA NA
#> pct_hh_m2730_hh_priority_needs_dnk
#> 1 NA
#> 2 NA
#> 3 NA
#> 4 NA
#> 5 NA
#> 6 NA
# With the pagination metadata:
print(hna_admin2$pagination)
#> $currentPage
#> [1] 1
#>
#> $totalPages
#> [1] 1
#>
#> $totalItems
#> [1] 97
#>
#> $hasNextPage
#> [1] FALSE
#>
#> $hasPreviousPage
#> [1] FALSEThe countries covered by the HNA API, and the indicators available in it, can be obtained by using the hna_get_countries() and hna_get_catalog() functions, which do not take any arguments.
User Guide
The information given here is further elaborated on in the user guide to getting started with dtmapi, which is accessible through vignette("user_guide").
Source Code
The source code for dtmapi is available on GitHub.
Feel free to explore the repository, contribute, or raise any issues you may encounter.
Contact
For any questions or feedback, please reach out to us at dtmdataconsolidation@iom.int.