The Internation Organization for Migration IOM provides a publicly accessible API specifically for the Displacement Tracking Matrix (DTM). It is designed to allow humanitarian organizations, researchers, and developers to programmatically access displacement data.

As of early 2026, the system has moved toward API Version 3 (v3), which offers more granular data than previous versions.

Key Features of the DTM API

Data Sensitivity Note

It is important to note that for protection reasons, the API does not provide sensitive individual-level data or biometrics. If you require highly detailed or sensitive datasets for humanitarian response, you must contact the DTM Global Support team directly to establish a formal Data Sharing Agreement (DSA).

The API

How to Access the API

To use the official IOM DTM API, you typically follow these steps:

  1. Registration: Visit the DTM API Registration Portal to sign up for an account.
  2. Subscription: Select the API version (v3 is recommended) and click Subscribe to generate a Primary Key.
  3. Authentication: Include your subscription key in the request header (usually as Ocp-Apim-Subscription-Key) for all API calls.

Accessing the API Using R

To analyze IOM DTM data in R, you will need a setup that handles API authentication, JSON parsing, and geospatial mapping. Since the DTM API delivers data in a structured format, R’s “Tidyverse” ecosystem is the most efficient choice for this workflow.

1. Essential R Libraries

You should install and load the following packages to manage the data pipeline:

  • httr2 or httr: For making the GET requests to the IOM API and passing your subscription key in the header.
  • jsonlite: To flatten the JSON responses into R data frames.
  • tidyverse (dplyr, ggplot2, tidyr): For cleaning the data and creating visualizations.
  • sf: Essential if you plan to join the displacement metrics with shapefiles for spatial analysis.
# Installation
install.packages(c("httr2", "jsonlite", "tidyverse", "sf"))

2. API Authentication Setup

The IOM API requires an Ocp-Apim-Subscription-Key. For security, do not hardcode this key into your scripts. Instead, use an .Renviron file:

  1. In your R console, run usethis::edit_r_environ().
  2. Add the line: IOM_API_KEY="your_key_here".
  3. Restart R.
  4. Access it in your script using Sys.getenv("IOM_API_KEY").

3. Constructing the Request

The DTM API v3 uses specific endpoints for different data types (e.g., IDP estimates vs. Flow Monitoring). A standard setup to fetch country-level data looks like this:

library(httr2)
library(jsonlite)

# Define the base URL for DTM API v3
base_url <- "https://api.dtm.iom.int/v3/GetIDPData"

# Create and perform the request
req <- request(base_url) %>%
  req_headers("Ocp-Apim-Subscription-Key" = Sys.getenv("IOM_API_KEY")) %>%
  req_perform()

# Parse the JSON response
dtm_data <- resp_body_json(req, simplifyVector = TRUE)

4. Data Workflow Logic

When analyzing displacement data, your R script should follow a specific logical flow to ensure the metrics are interpreted correctly:

  • Temporal Alignment: Displacement data is often updated in “rounds.” Ensure you are filtering for the most recent round to avoid double-counting.

  • Spatial Joining: Use the sf package to join DTM metrics with administrative boundaries (Admin 1 or Admin 2) downloaded from sources like GADM or Humanitarian Data Exchange (HDX).

  • Handling Nulls: DTM datasets often contain “No Data” or “0” values for specific sectors; your R code must explicitly handle these to avoid skewing averages.