As of 15 August 2024 DTM has introduced a new version of our API Library based on feedback from version 1 users. We have now introduced GET methods to allow users that cannot use a 3rd party API tool to be able to directly call the API from within a Browser. In addition, we have improved the parameter validation, updated some return types (for consistency) and simplified the parameters you need to pass.
The below documentation describes how to use the GET methods. In order to help you build your requests you can refer to the sample requests below or use our API Query Builder tool here or use the sample code templates in the API Endpoint section
Note: we still support the API version 1 POST methods for which you can find the documentation here
Metadata
You can use the metadata listed below to understand data shared via the API. Each of the variables used in the API are described in the table
DTM API Parameter Matrix
The below table outlines the combination of parameters that can be used together.
| Operation | CountryName | Admin0Code | FromReportingDate | ToReportingDate | FromRoundNumber | ToRoundNumber |
|---|---|---|---|---|---|---|
|
|
||||||
|
|
|
|||||
|
|
|
|
||||
|
|
|
|
|
|||
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||||
|
|
|
|
||||
|
|
|
|
|
|||
|
|
|
|
|
|
||
|
|
|
|||||
|
|
|
|
||||
|
|
|
|||||
|
|
|
|
||||
|
|
|
|
|
|||
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|||||
|
|
|
|
||||
|
|
|
|
|
|||
|
|
|
|
|
|
||
|
|
|
|||||
|
|
|
|
||||
|
|
||||||
|
|
|
|||||
|
|
|
|
||||
|
|
|
|
|
|||
|
|
|
|
|
|
||
|
|
|
|||||
|
|
|
|
||||
|
|
|
|
|
|||
|
|
|
|
|
|
||
|
|
|
|||||
|
|
|
|
Validation Rules
The following validation rules are in place for the API.
| Request Field | Type | Value | Business Rule | Validation Message |
|---|---|---|---|---|
| No parameters entered | string | Text | At lease one of the following parameters need to be included:
|
Please provide either the Country Name, Admin0 Pcode or Operation |
| Operation | string | Text | If Operation entered is not present in the dataset | No Operation found matching your query |
| CountryName | string | Text | If the Country Name entered is not in the dataset | No Country found matching your query |
| Admin0Pcode | string | Text | If Admin0Pcode entered is not present in the dataset | No Admin0Pcode found matching your query |
| Admin1Name | string | Text | If Admin1Name entered is not present in the dataset
If the Country Name and Admin1Pcode is blank and Admin1Name is not blank |
No Admin1Name found matching your query
No Admin 1 Name found in this country. Please try again. |
| Admin1Pcode | string | Text | If Admin1Pcode entered is not present in the dataset
If the Country Name and Admin1Pcode is blank and Admin1Pcode is not blank |
No Admin1Pcode found matching your query
No Admin 1 Pcode found in this country. Please try again |
| Admin2Name | string | Text | If Admin2Name entered is not present in the dataset
If the Country Name and Admin1Pcode is blank and Admin2Name is not blank |
No Admin2Name found matching your query
No Admin 2 Name found in this country. Please try again. |
| Admin2Pcode | string | Text | If Admin2Pcode entered is not present in the dataset
If the Country Name and Admin1Pcode is blank and Admin1Pcode is not blank |
No Admin2Pcode found matching your query
No Admin 2 Pcode found in this country. Please try again |
| Reporting Date Range | ||||
| FromReportingDate | string | Text | If FromReportingDate is not in yyyy-mm-dd format If FromReportingDate is greater than ToReportingDate |
Kindly provide FromReportingDate in yyyy-mm-dd format.
From Reporting Date should not be greater than To Reporting Date |
| ToReportingDate | string | Text | If ToReportingDate not in yyyy-mm-dd format
If ToReportingDate is less than FromReportingDate |
Kindly provide ToReportingDate in yyyy-mm-dd format.
From Reporting Date should not be greater than To Reporting Date |
| Round Number Range | ||||
| FromRoundNumber | Integer | Number | If FromRoundNumber is greater than ToRoundNumber
If FromRoundNumber is not a number |
From Round Number should not be greater than To Round Number
Value |
| ToRoundNumber | Integer | Number | If ToRoundNumber is less than FromRoundNumber
If ToRoundNumber is not a number |
From Round Number should not be greater than To Round Number
Value |
Available API Endpoints
- Get All Countries List
This endpoint will provide a list of countries covered by the API.
Note: Admin0 and Admin1 datasets will contain all countries in this list, but for Admin2 we suggest you check the data coverage page here if you get an empty dataset for your query
- Get All Operations List
This endpoint will provide a list of DTM Operations covered by the API.
Note: some operations span multiple countries so you can expect a record for each country as the operation may be active in one country and no longer active in another
- Get IDP Data at Country and Admin level
The API provides three endpoints at three different Administrative Boundary levels: Global IDP Data Country Level, Global IDP Data at Admin 1 Level and Global IDP Data at Admin 2 Level.
DTM API Toolkit
The following tools can assist you while using the API by providing data coverage and making the API call seamless and easy
Use the following frameworks to test the DTM api.
List of Frameworks
- Python
- R
- Javascript
- PHP (coming soon)
- PowerBi (coming soon)
To simplify and modernize the data-sharing platform for IDPs, DTM has created a publicly accessible API. This API allows the humanitarian community, academia, media, government, and non-governmental organizations to utilize the data collected by DTM. The DTM API only provides non-sensitive IDP figures, aggregated at the country, Admin 1 (states, provinces, or equivalent), and Admin 2 (smaller subnational administrative areas) levels.
Scope and Data Availability Level
The DTM API shares data stored at the country, Admin 1 (states, provinces or equivalent) and Admin 2 (smaller subnational administrative areas) levels. Greater detail and disaggregation is available in other formats, while the API streamlines data sharing with a focus on simplicity and security to share relevant data with the public.
DTM Assessment Types
Data from two of DTM’s components are included in the API – baseline assessments and multi-sectoral location assessments. A baseline assessment gauges population presence in an administrative area, as well as identifying sub-areas for further assessment such as camps and camp-like settings, or villages and neighbourhoods. Data from these assessments cover sudden onset disasters and share key information on displacement in different contexts. More detailed data are available through the multi-sectoral location assessment, which addresses living conditions and needs of populations in locations identified through the baseline assessments. More information on DTM components is available in the Methodological Framework.
Frequency
DTM gathers data across all stages of a humanitarian response, from the immediate emergency phase to the pathway toward durable solutions to displacement. Throughout these phases and the transitions between them, data gathering is carried out in rounds deployed with different frequencies depending on the needs of each context – some yearly, quarterly, or more often. This API shares data that show revelatory snapshots of a displacement situation captured at each round.
Definitions:
Internally displaced persons (IDPs):Persons or groups of persons who have been forced or obliged to flee or to leave their homes or places of habitual residence, in particular as a result of or in order to avoid the effects of armed conflict, situations of generalized violence, violations of human rights or natural or human-made disasters, and who have not crossed an internationally recognized State border [Guiding Principles on Internal Displacement, UN Doc E/CN.4/1998/53/Add.2.] (IOM, 2016). Returnee: any person who was displaced internally or across an international border, but has since returned to his/her place of habitual residence (IOM, 2004).
