Share

Jun 06 2024 Print

Overview

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.

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

API_field_name field_name_label
Operation Operation name
CountryName Country name
admin0Pcode Country code ( ISO 3166-1 alpha-3)
NumPresentIdpInd Number of IDP Individuals
ReportingDate fromDate: Data reporting starting date/snapshot date
toDate: Data reporting starting date/snapshot date
RoundNumber Data collection round number
API_field_name field_name_label
CountryName Country name
admin0Pcode Country code ( ISO 3166-1 alpha-3)
Admin1Name Administrative level 1 Name
Admin1Pcode Administrative level 1 OCHA P-code (Place-code)
Admin2Name Administrative level 2 Name
Admin2Pcode Administrative level 2 OCHA P-code (Place-code)
Operation Operation name
NumPresentIdpInd Number of IDP Individuals
ReportingDate Data reporting date/snapshot date
Year Data reporting year
Month Data reporting month
RoundNumber Data collection round number
AssessmentType Type of the assessment

Available API Endpoints

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.

Global IDP Data Country Level

This level will return information aggregated at country level to provide a broad snapshot of displacement dynamics.

POSThttps://dtmapi.iom.int/api/IdpAdmin0Data/GetAdmin0Data

Validation Rules

Request Field Type Value Business Rule Validation Message
CountryName string Text If country name is not present in country master.
If country name is blank and round number is not blank		 Kindly provide correct country name
Kindly provide correct country name along
with round number
       
Operation string Text If operation name is not present in operation master. Kindly provide correct operation
       
Admin0Pcode string Text   Kindly provide correct ISO Country Code
       
ReportingDate        
From Date string Text If From date is not in yyyy-mm-dd format Kindly provide FromDate in yyyy-mm-dd
format in ReportingDate
To Date string Text If From date is not in yyyy-mm-dd format Kindly provide FromDate in yyyy-mm-dd
format in ReportingDate
       
ReportMonthRange        
MonthFrom - Year Integer Number If Year is more than 4 digit Kindly provide valid year,
Year must be 4 digit
MonthFrom - Month string Text If Quarter is not having value Q1,Q2,Q3,Q4 In ReportMonthRange,
Kindly provide valid Monthin MonthFrom
MonthTo - Year integer Number If Year is more than 4 digit Kindly provide valid year,
Year must be 4 digit
MonthTo - Month integer Text If Month is not between 1 & 12 In ReportQMonthRange,
Kindly provide valid Month in MonthTo
       
Round Number        
From Integer Number If round number having value less than 0 Kindly provide valid round number in From
From Integer Number If round number having value less than 0 Kindly provide valid round number in To

Sample Request Header

{
	"operation":"",
	"countryName":"Afghanistan",
	"admin0Pcode":"",
	"reportingDate":{
		"fromDate":"2018-12-31",
		"toDate":null
	},
	"reportMonthRange":{
		"monthFrom":{
			"year":2000,
			"month":"1"
		},
		"monthTo":{
			"year":2024,
			"month":"12"
		}
	},
	"roundNumber":{
		"from":0,
		"to":0
	}
}

Response Body

The response body will return the following information:

Response Field Data type/ expected value Description
ID BigInt  
Operation String  
DateAssessment dateTime – yyy-mm-dd Assessment date
Admin0Name String Country Name
Admin0Pcode String (ISO3) Country code
NumPresentIdpInd Int Number of IDPs in selected country
ReportingDate Datetime - yyyy-mm-dd Number of IDPs in selected country
Year Int Year – YYYY
Month Int Month – MM
RoundNumber Int Internal collection round number
Assessment Type String BA – Baseline Assessment SA – Site Assessment
NumPresentIdpHh Int Number of IDP individuals internally displaced

Global IDP Data at Admin 1 Level

This level will return information aggregated at the administrative boundaries level 1, states, provinces and equivalent, still providing high-level information, but that drills down past country-level.

POSThttps://dtmapi.iom.int/api/IdpAdmin1Data/GetAdmin1Data

Validation Rules

Request Field Type Value Business Rule Validation Message
CountryName string Text If country name is not present in country master.
If country name is blank and round number is not blank		 Kindly provide correct country name
Kindly provide correct country name along
with round number
       
Operation string Text If operation name is not present in operation master. Kindly provide correct operation
       
Admin0Pcode string Text   Kindly provide correct ISO Country Code
       
ReportingDate        
From Date string Text If From date is not in yyyy-mm-dd format Kindly provide FromDate in yyyy-mm-dd
format in ReportingDate
To Date string Text If From date is not in yyyy-mm-dd format Kindly provide FromDate in yyyy-mm-dd
format in ReportingDate
       
ReportMonthRange        
MonthFrom - Year Integer Number If Year is more than 4 digit Kindly provide valid year,
Year must be 4 digit
MonthFrom - Month string Text If Quarter is not having value Q1,Q2,Q3,Q4 In ReportMonthRange,
Kindly provide valid Monthin MonthFrom
MonthTo - Year integer Number If Year is more than 4 digit Kindly provide valid year,
Year must be 4 digit
MonthTo - Month integer Text If Month is not between 1 & 12 In ReportQMonthRange,
Kindly provide valid Month in MonthTo
       
Round Number        
From Integer Number If round number having value less than 0 Kindly provide valid round number in From
From Integer Number If round number having value less than 0 Kindly provide valid round number in To

Sample Request Header

{
	"operation":"",
	"countryName":"Afghanistan",
	"admin0Pcode":"",
	"reportingDate":{
		"fromDate":"2018-12-31",
		"toDate":null
	},
	"reportMonthRange":{
		"monthFrom":{
			"year":2000,
			"month":"1"
		},
		"monthTo":{
			"year":2024,
			"month":"12"
		}
	},
	"roundNumber":{
		"from":0,
		"to":0
	}
}

Response Body

The response body will return the following information:

Response Field Data type/ expected value Description
ID BigInt  
Operation String  
DateAssessment dateTime – yyy-mm-dd Assessment date
Admin0Name String Country Name
Admin0Pcode String (ISO3) Country code
NumPresentIdpInd Int Number of IDPs in selected country
ReportingDate Datetime - yyyy-mm-dd Number of IDPs in selected country
Year Int Year – YYYY
Month Int Month – MM
RoundNumber Int Internal collection round number
Assessment Type String BA – Baseline Assessment SA – Site Assessment
NumPresentIdpHh Int Number of IDP individuals internally displaced

Global IDP Data at Admin 2 Level

This level will return information aggregated at the administrative boundaries level 2, the lowest level available on the API, to provide information on smaller administrative areas than states, provinces and equivalent.

POSThttps://dtmapi.iom.int/api/IdpAdmin2Data/GetAdmin2Data

Validation Rules

Request Field Type Value Business Rule Validation Message
CountryName string Text If country name is not present in country master.
If country name is blank and round number is not blank		 Kindly provide correct country name
Kindly provide correct country name along
with round number
       
Operation string Text If operation name is not present in operation master. Kindly provide correct operation
       
Admin0Pcode string Text   Kindly provide correct ISO Country Code
       
ReportingDate        
From Date string Text If From date is not in yyyy-mm-dd format Kindly provide FromDate in yyyy-mm-dd
format in ReportingDate
To Date string Text If From date is not in yyyy-mm-dd format Kindly provide FromDate in yyyy-mm-dd
format in ReportingDate
       
ReportMonthRange        
MonthFrom - Year Integer Number If Year is more than 4 digit Kindly provide valid year,
Year must be 4 digit
MonthFrom - Month string Text If Quarter is not having value Q1,Q2,Q3,Q4 In ReportMonthRange,
Kindly provide valid Monthin MonthFrom
MonthTo - Year integer Number If Year is more than 4 digit Kindly provide valid year,
Year must be 4 digit
MonthTo - Month integer Text If Month is not between 1 & 12 In ReportQMonthRange,
Kindly provide valid Month in MonthTo
       
Round Number        
From Integer Number If round number having value less than 0 Kindly provide valid round number in From
From Integer Number If round number having value less than 0 Kindly provide valid round number in To

Sample Request Header

{
	"operation":"",
	"countryName":"Afghanistan",
	"admin0Pcode":"",
	"reportingDate":{
		"fromDate":"2018-12-31",
		"toDate":null
	},
	"reportMonthRange":{
		"monthFrom":{
			"year":2000,
			"month":"1"
		},
		"monthTo":{
			"year":2024,
			"month":"12"
		}
	},
	"roundNumber":{
		"from":0,
		"to":0
	}
}

Response Body

The response body will return the following information:

Response Field Data type/ expected value Description
ID BigInt  
Operation String  
DateAssessment dateTime – yyy-mm-dd Assessment date
Admin0Name String Country Name
Admin0Pcode String (ISO3) Country code
NumPresentIdpInd Int Number of IDPs in selected country
ReportingDate Datetime - yyyy-mm-dd Number of IDPs in selected country
Year Int Year – YYYY
Month Int Month – MM
RoundNumber Int Internal collection round number
Assessment Type String BA – Baseline Assessment SA – Site Assessment
NumPresentIdpHh Int Number of IDP individuals internally displaced
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).