API documentation

Introduction

IDMC provides APIs to make the data in our Global Internal Displacement Database (GIDD) and Internal Displacement Updates (IDU) directly available to developers and analysts. This page has detailed descriptions of the databases and how to use the APIs. For feedback or technical questions contact ch.datainfo@idmc.ch.

Our API documentation also includes widgets that allow users to embed data visualization products directly into their websites. Additionally, users can access datasets with various levels of geospatial disaggregation, along with contextual information detailing the sources, methodologies, and caveats associated with the figures reported by IDMC in the GIDD.

Table of Contents

  • Introduction
  • Overview of IDMC and the Global Internal Displacement Database (GIDD)
  • IDMC's Main Data Products
  • Definitions
  • Accessing the API
  • Authentication
  • Endpoints
  • Fields Description
  • GIDD disaggregated data
  • Context of Displacement
  • Sex and Age Estimates for the Total Number of IDPs
  • GIDD Disasters Dataset
  • Internal Displacement Updates (IDU)
  • Caveats and Limitations of the IDU Dataset
  • Widgets
  • Code Sample to Read and Export the IDU API as a GeoJSON File for GIS Applications
  • Copy rights and citation of the data
  • Citation
  • Support
  • Other tools to access and process the IDU

Overview of IDMC and the Global Internal Displacement Database (GIDD)

IDMC established the Global Internal Displacement Database (GIDD) which stands as the only harmonised global repository for data on internal displacement due to conflicts and disasters since 2008. IDMC work focuses on aggregating, curating, analyzing, and standardizing data from a diverse array of sources including United Nations agencies, governmental entities, and non-governmental organizations (NGOs).

While IDMC does not collect primary data directly, it leverages data from these primary collectors and various secondary sources such as media outlets to fill data gaps and provide a holistic view of internal displacement worldwide. Data from different formats, languages, and terminologies are harmonized and meticulously processed. Each figure reported in the GIDD undergoes a rigorous quality control process involving consultations and partnerships with primary data providers and key stakeholders in the monitored countries’ data ecosystems. Furthermore, our analysis and figures are regularly reviewed with different UN partners to ensure transparency and consistency in our reporting methodologies.

IDMC's main data products

IDMC offers two primary data products: the Global Internal Displacement Database (GIDD) and the Internal Displacement Updates (IDU) each catering to distinct needs and audiences:

  • Global Internal Displacement Database (GIDD): This database is the product of an annual process that involves collecting, harmonizing, and validating data followed by a thorough peer review. We engage with primary data providers and relevant actors at various levels—national, regional, and global. Published annually, the GIDD has been acknowledged by several UN resolutions for its significance. The GIDD data is detailed by country and year for conflict-induced displacement, while disaster-induced displacement is recorded at the event level. Additional disaggregated data is also available since 2023.
  • Internal Displacement Updates (IDU): IDMC's IDU offers preliminary, timely, and detailed insights into new displacement events reflecting our ongoing daily monitoring efforts. This event-based dataset provides initial snapshots of displacement trends which may later be refined and consolidated in the GIDD. It's important to note that these figures do not undergo the same level of quality control as the GIDD data, as the IDU data reflects timely updates that are subject to change as more information becomes available following a displacement event.

For further details on IDMC's methodology please visit our website or our monitoring tools page.

This documentation will guide you through accessing and making the most of IDMC’s APIs, helping you to effectively integrate and utilize our data in your applications and analyses.

Definitions

  • Internally displaced persons (IDPs): Defined according to the 1998 Guiding Principles on Internal Displacement as people or groups of people who have been forced or obliged to flee or to leave their homes or places of habitual residence in particular as a result of armed conflict or 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 international border.
  • Internal Displacements (flows): Represents the number of internal displacements or internal displacement population flows reported from January 1st to December 31st of a reporting year. This figure may include individuals who are displaced multiple times during the year by different events.
  • Total number of Internally Displaced Persons (IDPs) (stocks): Represents the total number of people living in situations of internal displacement as of the end of the reporting year, specifically on December 31st of each year.
  • Conflict displacement: Refers to situations where people are forced to leave their homes or places of habitual residence as a result or in order to avoid the impact of armed conflict and other situations of violence including communal violence, criminal violence and civilian-state violence.
  • Disaster displacement: Refers to situations where people are forced to leave their homes or places of habitual residence as a result or in anticipation of the negative impact of natural hazards.
  • Disaster: A serious disruption of the functioning of a community or a society involving widespread human, material, economic, or environmental losses and impacts which exceeds the ability of the affected community or society to cope using its own resources.

Accessing the API

In order to access the APIs, please request an API key by emailing ch.datainfo@idmc.ch. Briefly describe your intended use case for the data in your email. You will receive an API key via email.

Authentication

API requests require authentication through a client_id parameter. This parameter must be included in every request to access the data.

GET https://helix-tools-api.idmcdb.org/external-api/gidd/displacements/?client_id=YOUR_API_KEY

Endpoints

Global Internal Displacement Database (GIDD)

This endpoint provides quality-controlled, annually validated data on internal displacement due to conflicts and disasters.

  • Endpoint URL: https://helix-tools-api.idmcdb.org/external-api/gidd/displacements/ 
    https://helix-tools-api.idmcdb.org/external-api/gidd/displacements/?client_id=YOUR_API_KEY&format=json
  • Data Format: JSON
  • Parameters:
    • client_id (required): Your API key.
    • limit (optional): Number of records to return. Default is 20.
    • start_year (optional): Filter by start year.
    • end_year (optional): Filter by end year.
    • iso3__in (optional): Filter by ISO 3166-1 alpha-3 code.
    • offset (optional): The initial index from which to return the results.
  • Example request: 
    GET https://helix-tools-api.idmcdb.org/external-api/gidd/displacements/?client_id=YOUR_API_KEY&end_year=2023&format=json&limit=15&offset=2
  • Fields description:
    Label (excel file) API field name (json) Definition
    ISO3 iso3 Represents the ISO 3166-1 alpha-3 code. The code 'AB9' is assigned to the Abyei Area.
    Country / Territory country_name Short name of the country or territory.
    Year year Indicates the year for which displacement data are reported.
    Conflict Total number of IDPs conflict_total_displacement_rounded Total number of IDPs (rounded figures at the national level) as a result of conflict and violence as of the end of the reporting year. Units are recorded as 'People'.
    Conflict Total number of IDPs raw conflict_total_displacement Total number of IDPs (not rounded) as a result of conflict and violence as of the end of the reporting year. Units are recorded as 'People'.
    Conflict Internal Displacements conflict_new_displacement_rounded Total number of internal displacements reported (rounded figures at national level) as a result of conflict and violence over the reporting year. Units are recorded as 'internal displacement flows' or 'internal displacement movements.'
    Conflict Internal Displacements raw conflict_new_displacement Total number of internal displacements reported (not rounded) as a result of conflict and violence over the reporting year. Units are recorded as 'internal displacement flows' or 'internal displacement movements.'
    Disaster Internal Displacements disaster_new_displacement_rounded Total number of internal displacements reported (rounded figures at national level) as a result of disasters over the reporting year. Units are recorded as 'internal displacement flows' or 'internal displacement movements.'
    Disaster Internal Displacements raw disaster_new_displacement Total number of internal displacements reported (not rounded) as a result of disasters over the reporting year. Units are recorded as 'internal displacement flows' or 'internal displacement movements.'
    Disaster Total number of IDPs disaster_total_displacement_rounded Total number of IDPs (rounded figures at national level) as a result of disasters as of the end of the reporting year. Units are recorded as 'People'.
    Disaster Total number of IDPs raw disaster_total_displacement Total number of IDPs (not rounded) as a result of disasters as of the end of the reporting year. Units are recorded as 'People'.

GIDD disaggregated data

This endpoint provides quality-controlled, annually validated data on internal displacement due to conflicts and disasters, disaggregated by caseload. This dataset is disaggregated by caseload, location and event.

  • Data format: GEOJSON
  • Fields description:
    Field Description
    ID IDMC figure unique identifier.
    ISO3 Represents the ISO 3166-1 alpha-3 code. The code 'AB9' is assigned to the Abyei Area.
    Country / Territory Short name of the country or territory.
    Geographical region Corresponds to IDMC's geographical regions.
    Figure cause Identifies the trigger of displacement such as conflict or disasters.
    Year Indicates the year for which displacement data are reported.
    Figure category Categorizes the type of displacement metric. It details values for Internal Displacements (internal displacement flows) and Total Number of IDPs (internal displacement stocks) as defined earlier in this document.
    Total figures Represents the total number of internal displacements or IDPs. For internal displacements, units are recorded as 'internal displacement flows' or 'internal displacement movements.' For the total number of IDPs, units reflect the total number of people living in displacement.
    Reported figures This field represents the values reported by the original source. Figures can be reported either in terms of households or individual counts.
    Figure unit This field specifies the type of unit reported in the 'Reported' column. Possible values include 'households' or 'people'. The category people includes 'internal displacement flows' or 'internal displacement movements.'
    Household size This metric represents the average number of individuals per household. It is calculated using data from various sources including the United Nations Department of Economic and Social Affairs (UNDESA), national statistical offices, and estimates from local primary data providers shared with IDMC.
    Hazard Category Hazard category based on the CRED EM-DAT classification.
    Hazard sub category Hazard sub category based on the CRED EM-DAT classification.
    Hazard Type Hazard type as categorized by CRED EM-DAT.
    Hazard Sub-Type Specific sub-type of the hazard based on CRED EM-DAT.
    Start date Start date of displacement flow.
    Start date accuracy Uncertainty or accuracy of start date.
    End date End date of the displacement flow.
    End date accuracy Uncertainty or accuracy of end date.
    Stock date This field indicates the year in which the data for the IDP metric (total number of internally displaced persons or stocks) was collected.
    Stock date accuracy Uncertainty or accuracy of stock date.
    Stock reporting date This field reflects the year IDMC uses to report the total number of internally displaced persons (IDPs). It represents the IDMC reporting year, which may not coincide with the actual data collection year. Given the protracted nature of displacement, annual updates on the total number of IDPs may not always be available. To maintain accuracy in reporting, IDMC relies on the most recent verified data until evidence shows that the displaced population has achieved a durable solution.
    Publishers Organizations responsible for distributing and disseminating internal displacement data. This field lists the names of the primary data providers or the original sources for the internal displacement data reported by IDMC.
    Sources Sources type: This field categorizes the type of source as defined by IDMC.
    Event ID Unique identifier for events as assigned by IDMC.
    Event name This field includes the event's coded name which is based on the country, type of hazard, location, and start date. It also incorporates the common or official name of the event when available.
    Event cause Identifies the trigger of displacement such as conflict or disasters.
    Event main trigger This field identifies the primary hazard subtype or violence type that initiated the event, serving as the main driver of a disaster or conflict. For disasters, associated fields such as "Hazard Category," "Hazard Subcategory," "Hazard Type," and "Hazard Sub-Type" detail the cascading impacts stemming from this main trigger. For instance, a tropical storm identified as the main driver of displacement might lead to reports in "Hazard Sub-Type" of floods, landslides, and other related disaster types arising from the initial hazard.
    Event start date Event or hazard start date.
    Event end date Event or hazard end date.
    Event start date accuracy Uncertainty or accuracy of event start date.
    Event end date accuracy Uncertainty or accuracy of event end date.
    Is housing destruction This field indicates whether the displacement data includes individuals displaced by housing destruction. Values are "Yes" if the data reflects households whose homes were destroyed, and "No" otherwise. This field relies on the data specified in "Reported Figures" and is linked to the "Unit" of measurement used, which in this context refers to houses destroyed.
    Violence type This field categorizes the type of violence using IDMC's typology, which aligns with international classifications. The categories include:
    • International Armed Conflict (IAC): Refers to armed conflict between two or more states.
    • Non-International Armed Conflict (NIAC): Refers to armed conflict occurring within the territory of a single state between its government and non-state armed groups or between such groups themselves.
    • Unclear/Unknown: Indicates situations where the type of violence is not definitively categorized due to limited information.
    • Other situations of violence (OSV): Refers to cases of communal violence, civilian-state violence and crime-related violence.
    Event codes (Code:Type) Unique codes such as the GLIDE number and other database-specific codes used to identify and track specific events across various databases.
    Locations name This field indicates the names of locations where displacement incidents have been reported. It's important to note that this field may exhibit a many-to-one relationship signifying that multiple location names could be associated with a single reported figure preventing disaggregation by individual location. This becomes particularly relevant in geospatial analysis where Geographic Information System (GIS) software may interpret these multi-point entities as single data points, potentially leading to the inadvertent double-counting of figures. To mitigate this issue, it's advisable to preprocess the dataset by either dividing the total figure by the number of locations or distributing the "Total figures" values based on a weighting factor such as population density. This ensures a more accurate representation of the displacement data across individual locations and prevents duplication of figures during analysis.
    Locations coordinates This field contains geographic coordinates representing the reported locations. Please note that this field contains multipoints, meaning that multiple locations may represent one figure. It's important to note that this field may exhibit a many-to-one relationship signifying that multiple location names could be associated with a single reported figure preventing disaggregation by individual location. This becomes particularly relevant in geospatial analysis where Geographic Information System (GIS) software may interpret these multi-point entities as single data points, potentially leading to the inadvertent double-counting of figures. To mitigate this issue, it's advisable to preprocess the dataset by either dividing the total figure by the number of locations or distributing the "Total figures" values based on a weighting factor such as population density. This ensures a more accurate representation of the displacement data across individual locations and prevents duplication of figures during analysis.
    Locations accuracy This field indicates the estimated precision of the reported locations. It serves as a clue to the likely administrative unit level (e.g. country, state, district) used for reporting.
    Locations type This field specifies the type of displacement location within a reported event. It can indicate:
    • Origin: The place where people were displaced from.
    • Destination: The location where displaced people arrived.
    • Both: In some cases both origin and destination information might be included.
    It's crucial to note that different locations reported for a single figure may pertain to both the origin and destination of displacement incidents. This distinction is particularly salient in geospatial analysis where Geographic Information System (GIS) software may interpret these multi-point entities as singular data points, potentially resulting in inadvertent double-counting of figures.To mitigate this issue, it is recommended to preprocess the dataset prior to GIS analysis to ensure accurate representation and avoid duplication of figures.
    Displacement occurred This field contains values that represent if preventive evacuations were reported. These evacuations are the result of existing early warning systems.

Context of displacement

This dataset provides contextual information and analysis documented by IDMC analysts. It captures flags related to methodology, caveats, sources, and challenges identified for each metric, reporting year, and country.

  • Endpoint URL: https://www.internal-displacement.org/database/displacement-data/ 
    				https://helix-tools-api.idmcdb.org/external-api/gidd/public-figure-analyses/?client_id=YOUR_API_KEY&end_year=2023&limit=15&offset=2&start_year=2022
    		https://helix-tools-api.idmcdb.org/external-api/gidd/public-figure-analyses/?client_id=YOUR_AOI_KEY&FORMAT=JSON
  • Parameters:
    • client_id (required): Your API key.
    • limit (optional): Number of records to return. Default is 20.
    • start_year (optional): Filter by start year.
    • end_year (optional): Filter by end year.
    • iso3__in (optional): Filter by ISO 3166-1 alpha-3 code.
    • offset(optional): The initial index from which to return the results.
  • Example request:  
    		https://helix-tools-api.idmcdb.org/external-api/gidd/public-figure-analyses/?client_id=YOUR_API_KEY&end_year=2023&limit=15&offset=2&start_year=2022
  • Fields description:
    Label (excel file) API field name (json) Definition
    ISO3 iso3 Represents the ISO 3166-1 alpha-3 code. The code 'AB9' is assigned to the Abyei Area.
    Year year Indicates the year for which displacement data are reported.
    Figure cause Figure_Cause_Name Identifies the trigger of displacement such as conflict or disasters.
    Figure category Figure_Category_Name Categorizes the type of displacement metric. It details values for "Internal Displacements" (internal displacement flows) and Total Number of IDPs, "Total number of IDPs" as defined earlier in this document.
    Description description Provides contextual information about the data including sources and data limitations. It is essential for representing the analysis conducted by IDMC analysts. This field also details the methodology used, descriptions of sources, and outlines any caveats and challenges identified with the displacement figures reported.
    Figures figures Represents the total number of internal displacements or IDPs. For internal displacements, units are recorded as 'internal displacement flows' or 'internal displacement movements.' For the total number of IDPs, units reflect the total number of people living in displacement.
    Figures rounded figures_rounded Displays rounded figures to provide a simplified view of the data that matches the figures reported in the Global Report on Internal Displacement (GRID).

Sex and age estimates for the total number of IDPs estimates

Sex and Age Disaggregated Data (SADD) for displacement associated with conflict or disasters is often scarce. One way to estimate it is to use SADD available at the national level. IDMC employs United Nations Population Estimates and Projections to break down the number of internally displaced people by sex and age. The methodology and limitations of this approach are described on IDMC’s website at: https://www.internal-displacement.org/monitoring-tools

  • URL (excel file): https://www.internal-displacement.org/database/displacement-data/
  • Data format: excel
  • Fields description:
    Label (excel file) API field name Definition
    ISO3 iso3 Represents the ISO 3166-1 alpha-3 code. The code 'AB9' is assigned to the Abyei Area.
    Country country_name Short name of the country or territory.
    Year year Indicates the year for which displacement figures are reported.
    Sex sex This field contains information on Female, Male, and Both Sexes categories following the United Nations Department of Economic and Social Affairs (UN DESA) classifications.
    Cause cause Identifies the trigger of displacement such as conflict or disasters.
    Age_0_4 age_0_4 Represents the age cohort from newborns to 4 years old.
    Age_5_11 age_5_11 Represents children aged 5 to 11 years.
    Age_12_17 age_12_17 Represents adolescents aged 12 to 17 years.
    Age_18_59 age_18_59 Represents adults aged 18 to 59 years.
    Age_60_plus age_60_plus Represents the population aged 60 years and older.

GIDD disasters dataset

This dataset provides a JSON endpoint or an excel download with disaster data

  • Endpoint URL: https://helix-tools-api.idmcdb.org/external-api/gidd/disasters/ 
    https://helix-tools-api.idmcdb.org/external-api/gidd/disasters/?client_id=YOUR_API_KEY&format=json
    • Data format: JSON
    • Parameters:
      • client_id (required): Your API key.
      • limit (optional): Number of records to return. Default is 20.
      • start_year (optional): Filter by start year.
      • end_year (optional): Filter by end year.
      • iso3__in (optional): Filter by ISO 3166-1 alpha-3 code.
      • offset(optional): The initial index from which to return the results.
    • Fields description:
      Label (excel file) API field name Definition
      ISO3 iso3 Represents the ISO 3166-1 alpha-3 code. The code 'AB9' is assigned to the Abyei Area.
      Country / Territory country_name Short name of the country or territory.
      Year year Indicates the year for which displacement data are reported.
      Event Name event_name Common or official event name for the event if available. Otherwise events are coded based on the country type of hazard location and event start date.
      Date of Event (Start) start_date Approximated start date of the event.
        start_date_accuracy This field describes the potential timeframe within which the event likely occurred. The values indicate the period around the date.
        end_date Approximated end date of the event.
        end_date_accuracy This field describes the potential timeframe within which the event likely ended. The values indicate the period around the date.
      Disaster Internal Displacements new_displacement_rounded Total number of internal displacements reported (rounded figures at national level) as a result of disasters over the reporting year. Units are recorded as 'internal displacement flows' or 'internal displacement movements.'
      Disaster Internal Displacements raw new_displacement Total number of internal displacements reported (not rounded) as a result of disasters over the reporting year. Units are recorded as 'internal displacement flows' or 'internal displacement movements.'
      Hazard Category hazard_category Hazard category based on the CRED EM-DAT classification.
      Hazard Type hazard_type Hazard type as categorized by CRED EM-DAT.
      Hazard Sub-Type hazard_sub_type Specific sub-type of the hazard based on the CRED EM-DAT classification.
      Event Codes (Code event_codes Unique codes such as the GLIDE number and other database-specific codes used to identify and track specific events across various databases.
      Event ID   Unique identifier for events as assigned by IDMC.
      Displacement Occurred   This field contains values that represent if preventive evacuations were reported. These evacuations are the result of existing early warning systems.

    Internal Displacement Updates (IDU)

    This dataset provides the most up-to-date estimates of new occurrences of internal displacement triggered by conflicts and disasters. It encompasses data on internal displacements (or population movements) which are obtained through event-based monitoring. The IDU figures are likely to change over time as more information is available. Curated figures are published as part of the GIDD dataset.

    Figures from the IDU may differ from GIDD estimates.

    • Endpoint URL 
      https://helix-tools-api.idmcdb.org/external-api/idus/last-180-days/?client_id=YOUR_API_KEY
    • Data format: JSON
    • Parameters: This end point does not have parameters
    • Fields description:
      Label API field name Definition
      Id id IDMC figure unique identifier.
      Country country Short name of the country or territory.
      Iso3 iso3 Represents the ISO 3166-1 alpha-3 code. The code 'AB9' is assigned to the Abyei Area.
      Latitude latitude Geographic coordinate in decimal degrees (latitude).
      Longitude longitude Geographic coordinate in decimal degrees (longitude).
      Centroid centroid Geographical center point of the data's location.
      Role role The field of data delineates the most reliable figure accessible as determined by the primary data source, the methodology employed in data collection, the scope of coverage, and the promptness of the reported information. This framework is essential in understanding two key types of figures:
      • Recommended Figure: This is the figure that has been identified with the highest level of confidence or robustness to represent the population flow. It is selected based on thorough evaluation and is recommended for inclusion in our official estimates for a specific event. Such figures are crucial as they can be aggregated to facilitate detailed analysis. The role of a figure can change over time. As new data becomes available, a figure that was once a "Recommended Figure" may become outdated and be reclassified as a "Triangulation Figure".
      • Triangulation Figure: For the purposes of the IDU dataset, these entries represent often the first estimates of the magnitude of a displacement situation. These are provisional estimates reflect various updates regarding displacement situations. They are utilized until a more solid or robust estimate becomes available, especially as more data is gathered by local primary data sources.
      Displacement_type displacement_type Identifies the trigger of displacement such as conflict or disasters.
      Conflict conflict New displacements due to conflict and violence (Color code: #EF7D04).
      Disasters disasters New displacements due to natural hazards (Color code: #008ECA).
      Qualifier qualifier Indicates the level of uncertainty or accuracy associated with the figure.
      Figure figure Total number of internal displacements (flows).
      Displacement_date displacement_date Initial date when the displacement flow began.
      Displacement_Start_date displacement_start_date Approximate date when the displacement flow started.
      Displacement_end_date displacement_end_date Approximate date when the displacement flow ended.
      Year year Year in which the displacement occurred.
      Event_id event_id Unique identifier for events as assigned by IDMC.
      Event_name event_name This field includes the event's coded name which is based on the country, type of hazard, location, and start date. It also incorporates the common or official name of the event when available.
      Event_start_date event_start_date Date when the event or hazard began.
      Event_end_date event_end_date Date when the event or hazard concluded.
      Category category Natural Hazard category that triggered displacement based on the IRDR Peril Classification and Hazard Glossary.
      Subcategory subcategory Hazard category based on the CRED EM-DAT classification.
      Type type Hazard type as categorized by CRED EM-DAT.
      Subtype subtype Specific sub-type of the hazard based on the CRED EM-DAT.
      Standard_popup_text standard_popup_text Standard text from the IDMC website for the data entry.
      Standard_info_text standard_info_text Additional standard information provided by IDMC.
      Old_Id old_id Legacy identifier for the data entry.
      Sources sources This field lists the names of the primary data providers or the original sources for the internal displacement data reported by IDMC.
      Source_url source_url URL of the source reported.
      Locations_name locations_name This field indicates the names of locations where displacement incidents have been reported. It's important to note that this field may exhibit a many-to-one relationship signifying that multiple location names could be associated with a single reported figure preventing disaggregation by individual location. This becomes particularly relevant in geospatial analysis, where Geographic Information System (GIS) software may interpret these multi-point entities as single data points, potentially leading to the inadvertent double-counting of figures. To mitigate this issue, it's advisable to preprocess the dataset by either dividing the total figure by the number of locations or distributing the "Total figures" values based on a weighting factor such as population density. This ensures a more accurate representation of the displacement data across individual locations and prevents duplication of figures during analysis.
      Locations_coordinates locations_coordinates This field contains geographic coordinates representing the reported locations. Please note that this field contains multipoints, meaning that multiple locations may represent one figures. It's important to note that this field may exhibit a many-to-one relationship signifying that multiple location names could be associated with a single reported figure preventing disaggregation by individual location. This becomes particularly relevant in geospatial analysis, where Geographic Information System (GIS) software may interpret these multi-point entities as single data points, potentially leading to the inadvertent double-counting of figures. To mitigate this issue, it's advisable to preprocess the dataset by either dividing the total figure by the number of locations or distributing the "Total figures" values based on a weighting factor such as population density. This ensures a more accurate representation of the displacement data across individual locations and prevents duplication of figures during analysis.
      Locations_accuracy locations_accuracy This field indicates the estimated precision of the reported locations. It serves as a clue to the likely administrative unit level (e.g. country, state, district) used for reporting.
      Locations_type locations_type This field specifies the type of displacement location within a reported event. It can indicate:
      • Origin: The place where people were displaced from.
      • Destination: The location where displaced people arrived.
      • Both: In some cases both origin and destination information might be included.
      It's crucial to note that different locations reported for a single figure may pertain to both the origin and destination of displacement incidents. This distinction is particularly salient in geospatial analysis where Geographic Information System (GIS) software may interpret these multi-point entities as singular data points potentially resulting in inadvertent double-counting of figures. To mitigate this issue, it is recommended to preprocess the dataset prior to GIS analysis to ensure accurate representation and avoid duplication of figures.
      Displacement_occurred displacement_occurred This field contains values that represent if preventive evacuations were reported. These evacuations are the result of existing early warning systems.
      Created_at created_at Date when the data entry was created.

    Caveats and limitations of the IDU dataset

    • These figures depict reported internal displacement flows and may change as displacement situations evolve and more information emerges. For curated and validated estimates refer to the Global Internal Displacement Database (GIDD) accessible at GIDD: https://www.internal-displacement.org/database/displacement-data/. The IDU dataset provides the most recent updates on internal displacement events (population flows).
    • Important considerations: When analyzing the IDU data, it's imperative to exercise caution in certain situations. Specifically, if multiple IDU entries share identical flow dates, eventID, and locations, we advise against summing up the figures. This is because such data might represent varying estimates of population flows rather than distinct population movements. This distinction is crucial to avoid misinterpretation of the data and ensure accurate representation of displacement situations. Hence, please include the following preprocessing considerations per event, i.e. after grouping the figures per "eventID", in the analysis:
      • Prioritization of figures: For any given event with multiple updates, it is imperative to utilize the “Recommended figure” over “Triangulation figure” whenever these are available. This approach ensures the most accurate reflection of the total number of internal displacements resulting from the event.
      • Aggregating recommended figures: When encountering multiple recommended figures, per event aggregation is possible even if they come from different locations with identical flow, as these figures represent disaggregated data. Figures pertaining to the same location can also be aggregated. Such cases are often reported when the names of settlements cannot be located in IDMC geocoders. In these scenarios, analysts will refer to the last well-known higher administrative unit, although the data actually describes disaggregated figures within this higher unit. In these instances, the “Standard_popup_text” field will include the settlement name.
      • Triangulation figures with same locations: In the absence of recommended figures and when multiple triangulation figures exist for the same location for an event, only the most recently updated figure should be used. This recommendation is made to avoid the risk of double counting and is based on the assumption that the latest update offers a more comprehensive estimate than earlier ones.
      • Triangulation figures with different locations: For an event, in the absence of recommended figures and the presence of multiple triangulation figures sharing the same flow dates but referring to different locations, these figures are to be combined. This method enables the representation of the total number of internal displacements arising from an event across various locations.

    Widgets

    IDMC offers widgets that can be embedded into websites to display displacement data. These widgets are configurable and can be tailored to show specific data subsets.

    • Conflict widget: Visualizes internal displacements and the total number of IDPs by country and year.
    • Disasters widget: Displays disaster events disaggregated by country, hazard type, and year.
    • IDU widget: Shows IDU map data with filters for monthly queries and a carousel for latest updates.
    • GIDD widget: Shows the GIDD data with charts and filters.

    To integrate a widget, include the provided HTML snippet into your webpage.

    https://release-website-components.idmcdb.org/?page=conflict-widget&iso3=AFG&clientCode=YOUR_API_KEY

    Example:

    <div class="container"> <iframe src="https://release-website-components.idmcdb.org/?page=conflict-widget&iso3=AFG&clientCode=YOUR_API_KEY" title="Conflict Widget for Afghanistan" allowfullscreen> </iframe> </div>

    Code sample to read and export the IDU API as a geojson file for GIS applications

    Obtaining API keys

    1. To get an API key, please contact ch.datainfo@idmc.ch. The key will be sent to your email, enabling access to IDMC's API. Create and save the Python script in a file, navigate to its directory in a terminal, run it with python export_geojson.py, and check for the IDMC_IDU.geojson output. 
      import requests
import json
 
# URL of the JSON API
url = "LINK TO THE API END POINT"
 
response = requests.get(url).json()  # Assumes successful response and valid JSON
 
geojson = {
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "properties": {k: v for k, v in item.items() if k != "latitude" and k != "longitude"},
        "geometry": {"type": "Point", "coordinates": [item["longitude"], item["latitude"]]}
    } for item in response]
}
 
# Define the path where you want to save the file
# Adjust the path as needed for your specific requirements
file_path = "C:\\path\\to\\your\\folder\\IDMC_IDU.geojson"  # Update this path for windows environments
# file_path = "/path/to/your/folder/displacements.geojson"  # Update this path for Linux/MacOS environments
 
 
with open(file_path, "w") as f:
    f.write(json.dumps(geojson, indent=4))
 
print("GeoJSON file created successfully.")
    2. For QGIS, drag and drop the file into QGIS.
    3. For ArcGIS Pro, use the JSON to Features tool to read the geojson file and open it as a shapefile.

      ArcGIS Pro geoprocessing

    "General caveats and limitations of the datasets

    • The IDU dataset provides preliminary estimates and is updated daily. It may not align perfectly with the annually consolidated GIDD dataset and does not undergo the same quality control process.
    • When analyzing data with identical dates and locations, avoid summing figures to prevent overestimation unless these figures are labeled with role "Recommended Figure".
    • Use the "Recommended Figure" over "Triangulation Figure" for the most accurate data.
    • For spatial analysis, preprocess multi-location data to avoid double counting.

    Copy rights and citation of the data

    • Non-Commercial Use: Data is available under the Creative Commons Attribution-Non-Commercial-Share Alike 3.0 IGO license.
    • Attribution: Proper attribution to IDMC is required when using the data.
    • Derived Works: Must be shared under the same license terms.

    Citation

    All derived work from IDMC data could cite IDMC following this example:

    Internal Displacement Monitoring Centre. Global Internal Displacement Database. IDMC (2023). Available at: https://www.internal-displacement.org/database/displacement-data/ (Accessed: [date of access]).

    Support

    For feedback or technical questions contact ch.datainfo@idmc.ch.

    For additional tools and resources visit the IDMC monitoring tools page.