Displacement Service

Monitor refugee flows, IDPs, and population exposure from UNHCR

Overview

The Displacement Service provides APIs for global displacement and refugee data from the United Nations High Commissioner for Refugees (UNHCR). Track refugee flows, internally displaced persons (IDPs), asylum seekers, and population exposure estimates.

Base Path: /api/displacement/v1

---

GetDisplacementSummary

Retrieves global refugee and IDP statistics from UNHCR.

Endpoint: GET /api/displacement/v1/get-displacement-summary

Request Parameters

year · integer

Data year to retrieve (e.g., 2023). Uses latest available if zero or omitted.

country_limit · integer

Maximum number of country entries to return.

flow_limit · integer

Maximum number of displacement flows to return.

Response

summary · object

The displacement summary.

Show DisplacementSummary

year · integer

Data year.

global_totals · object

Global totals across all categories.

Show GlobalDisplacementTotals

refugees · integer

Total recognized refugees worldwide.

asylum_seekers · integer

Total asylum seekers worldwide.

idps · integer

Total internally displaced persons worldwide.

stateless · integer

Total stateless persons worldwide.

total · integer

Grand total of displaced persons.

countries · array

Per-country displacement breakdowns.

Show CountryDisplacement

code · string · required

ISO 3166-1 alpha-2 country code.

name · string

Country name.

refugees · integer

Refugees originating from this country.

asylum_seekers · integer

Asylum seekers from this country.

idps · integer

Internally displaced persons within this country.

stateless · integer

Stateless persons associated with this country.

total_displaced · integer

Total displaced from this country.

host_refugees · integer

Refugees hosted by this country.

host_asylum_seekers · integer

Asylum seekers hosted by this country.

host_total · integer

Total persons hosted by this country.

location · object

Representative location for mapping.

top_flows · array

Top displacement flows between countries.

Show DisplacementFlow

origin_code · string · required

ISO 3166-1 alpha-2 code of the origin country.

origin_name · string

Origin country name.

asylum_code · string · required

ISO 3166-1 alpha-2 code of the asylum country.

asylum_name · string

Asylum country name.

refugees · integer

Number of refugees in this flow.

origin_location · object

Origin country representative location.

asylum_location · object

Asylum country representative location.

Example Request

curl -X GET "https://api.worldmonitor.com/api/displacement/v1/get-displacement-summary?year=2023&country_limit=10&flow_limit=20"

Example Response

{
  "summary": {
    "year": 2023,
    "global_totals": {
      "refugees": 35800000,
      "asylum_seekers": 6400000,
      "idps": 62500000,
      "stateless": 4900000,
      "total": 109600000
    },
    "countries": [
      {
        "code": "SY",
        "name": "Syria",
        "refugees": 6800000,
        "asylum_seekers": 120000,
        "idps": 6900000,
        "stateless": 0,
        "total_displaced": 13820000,
        "host_refugees": 0,
        "host_asylum_seekers": 0,
        "host_total": 0,
        "location": {
          "latitude": 34.8021,
          "longitude": 38.9968
        }
      },
      {
        "code": "TR",
        "name": "Turkey",
        "refugees": 0,
        "asylum_seekers": 0,
        "idps": 0,
        "stateless": 0,
        "total_displaced": 0,
        "host_refugees": 3600000,
        "host_asylum_seekers": 125000,
        "host_total": 3725000,
        "location": {
          "latitude": 38.9637,
          "longitude": 35.2433
        }
      }
    ],
    "top_flows": [
      {
        "origin_code": "SY",
        "origin_name": "Syria",
        "asylum_code": "TR",
        "asylum_name": "Turkey",
        "refugees": 3600000,
        "origin_location": {
          "latitude": 34.8021,
          "longitude": 38.9968
        },
        "asylum_location": {
          "latitude": 38.9637,
          "longitude": 35.2433
        }
      }
    ]
  }
}

---

GetPopulationExposure

Returns country population data or estimates population within a radius.

Endpoint: GET /api/displacement/v1/get-population-exposure

Request Parameters

mode · string

Mode: countries (default) or exposure.

lat · number

Latitude (required for exposure mode). Range: -90 to 90.

lon · number

Longitude (required for exposure mode). Range: -180 to 180.

radius · number

Radius in km (required for exposure mode, defaults to 50).

Response

success · boolean

True if the request succeeded.

countries · array

Countries list (populated in countries mode).

Show CountryPopulationEntry

code · string

ISO 3166-1 alpha-3 country code.

name · string

Country name.

population · integer

Total population.

density_per_km2 · integer

Population density per square kilometer.

exposure · object

Exposure result (populated in exposure mode).

Show ExposureResult

exposed_population · integer

Estimated exposed population.

exposure_radius_km · number

Radius used for the estimate in km.

nearest_country · string

ISO3 code of nearest priority country.

density_per_km2 · integer

Population density used for the estimate.

Example Request (Countries Mode)

curl -X GET "https://api.worldmonitor.com/api/displacement/v1/get-population-exposure?mode=countries"

Example Response (Countries Mode)

{
  "success": true,
  "countries": [
    {
      "code": "CHN",
      "name": "China",
      "population": 1425671352,
      "density_per_km2": 153
    },
    {
      "code": "IND",
      "name": "India",
      "population": 1428627663,
      "density_per_km2": 464
    }
  ]
}

Example Request (Exposure Mode)

curl -X GET "https://api.worldmonitor.com/api/displacement/v1/get-population-exposure?mode=exposure&lat=33.5138&lon=36.2765&radius=100"

Example Response (Exposure Mode)

{
  "success": true,
  "exposure": {
    "exposed_population": 2850000,
    "exposure_radius_km": 100,
    "nearest_country": "SYR",
    "density_per_km2": 91
  }
}

---

Displacement Categories

Refugees

People who have fled their country due to persecution, war, or violence.

Asylum Seekers

People who have applied for international protection but whose claims are pending.

IDPs

Internally Displaced Persons who have fled their homes but remain within their country.

Stateless

People who are not recognized as citizens by any country.

---

Data Source

Displacement data is sourced from:

• UNHCR: United Nations High Commissioner for Refugees
• Global Trends Report: Annual statistical yearbook
• Population Data: World Bank and national statistics
• Updated annually with mid-year estimates available