dtmapi

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

dtmapi

Introduction

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()

Install Package

The dtmapi package is available on CRAN and can be installed using the following command: :

install.packages("dtmapi")

Load Package

After installation, load the package using library():

library(dtmapi)

Get All Countries

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         BDI

Get All Operations

The 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         BHS

Get IDP Data at Admin Level 0

The 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             SA

Get IDP Data at Admin Level 1

The 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             BA

Get IDP Data at Admin Level 2

The 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             BA

Function Arguments

Here 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.

Arguments

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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.