# UNHCR Refugee Data

> Get the UN Refugee Agency's official statistics on people forced to flee: refugees, asylum-seekers, internally displaced and stateless people by country of origin and asylum since 1951, their age and sex, asylum applications and decisions with recognition rates, returns, resettlement and naturalisation, and this year's estimates. No account or API key required.

App · 12 actions. Web page: https://docs.lodol.com/docs/integrations/unhcr

## Actions

### Get asylum applications

Get how many asylum applications were made in a year, by country of origin and country of asylum: new applications, appeals and repeat applications. Available from 2000.

**Inputs**

- Country of origin (`origin`, text): The country the applicants come from. Pick one, or type several ISO3 codes separated by commas (SYR, AFG). Leave empty for every country.
- Country of asylum (`asylum`, text): The country the applicants are in. Pick one, or type several ISO3 codes separated by commas (DEU, FRA). Leave empty for every country.
- Year (`year`, number): The year, or the first of several. Figures count what happened during the year. Leave empty for the latest year UNHCR has published. From 2000 to 2026.
- To year (`to_year`, number): For several years, the last one. Leave empty for just the one year. From 2000 to 2026.
- Break down by (`break_down_by`, text): One total per year, or a row for each country of origin, each country of asylum, or each pair of them. One of: `none` (No breakdown: one total per year), `origin` (Country of origin), `asylum` (Country of asylum), `both` (Both: each pair of origin and asylum). Default: `none`.
- Most rows (`limit`, number): The most rows to list, largest first (up to 1,000). Totals still count every one. From 1 to 1000. Default: `100`.

**Outputs**

- `asylum_filter` (list): The countries of asylum the figures were narrowed to; empty for every country.
- `break_down_by` (text): How the rows are split: none (one total per year), origin, asylum or both.
- `count` (number): How many rows are listed.
- `download_url` (text): A link that downloads the same figures, with UNHCR's footnotes, as a zip of CSV files a spreadsheet can open.
- `latest_year` (number): The latest year UNHCR has published asylum applications for. A year left empty means this one.
- `origin_filter` (list): The countries of origin the figures were narrowed to; empty for every country.
- `rows` (list): The figures, newest year first and largest first.
- `total_rows` (number): How many rows there are before the row limit.
- `totals` (list): Every row added up, one line per year (newest first), including rows left out by the row limit.
- `truncated` (true/false): Whether rows were left out to keep to the row limit.
- `year_from` (number): The first year of asylum applications asked for.
- `year_to` (number): The last year of asylum applications asked for.

**Example output**

```json
{
  "asylum_filter": [
    {
      "country": "United States of America",
      "iso3": "USA"
    }
  ],
  "break_down_by": "none",
  "count": 2,
  "download_url": "https://api.unhcr.org/population/v1/asylum-applications/?cf_type=ISO&coa=USA&yearFrom=2025&yearTo=2025&download=true",
  "latest_year": 2025,
  "origin_filter": [],
  "rows": [
    {
      "appeals": 0,
      "applications": 629358,
      "asylum_country": "United States of America",
      "asylum_iso3": "USA",
      "counted_in": "persons",
      "new_applications": 629358,
      "origin_country": null,
      "origin_iso3": null,
      "other_applications": 0,
      "repeat_applications": 0,
      "year": 2025
    },
    {
      "appeals": 0,
      "applications": 282594,
      "asylum_country": "United States of America",
      "asylum_iso3": "USA",
      "counted_in": "cases",
      "new_applications": 282594,
      "origin_country": null,
      "origin_iso3": null,
      "other_applications": 0,
      "repeat_applications": 0,
      "year": 2025
    }
  ],
  "total_rows": 2,
  "totals": [
    {
      "appeals": 0,
      "applications": 629358,
      "asylum_country": "United States of America",
      "asylum_iso3": "USA",
      "counted_in": "persons",
      "new_applications": 629358,
      "origin_country": null,
      "origin_iso3": null,
      "other_applications": 0,
      "repeat_applications": 0,
      "year": 2025
    },
    {
      "appeals": 0,
      "applications": 282594,
      "asylum_country": "United States of America",
      "asylum_iso3": "USA",
      "counted_in": "cases",
      "new_applications": 282594,
      "origin_country": null,
      "origin_iso3": null,
      "other_applications": 0,
      "repeat_applications": 0,
      "year": 2025
    }
  ],
  "truncated": false,
  "year_from": 2025,
  "year_to": 2025
}
```

### Get asylum decisions

Get the decisions made on asylum claims in a year, by country of origin and country of asylum: granted refugee status, granted another form of protection, rejected and otherwise closed, with UNHCR's refugee recognition rate and total recognition rate. Available from 2000.

**Inputs**

- Country of origin (`origin`, text): The country the applicants come from. Pick one, or type several ISO3 codes separated by commas (SYR, AFG). Leave empty for every country.
- Country of asylum (`asylum`, text): The country the applicants are in. Pick one, or type several ISO3 codes separated by commas (DEU, FRA). Leave empty for every country.
- Year (`year`, number): The year, or the first of several. Figures count what happened during the year. Leave empty for the latest year UNHCR has published. From 2000 to 2026.
- To year (`to_year`, number): For several years, the last one. Leave empty for just the one year. From 2000 to 2026.
- Break down by (`break_down_by`, text): One total per year, or a row for each country of origin, each country of asylum, or each pair of them. One of: `none` (No breakdown: one total per year), `origin` (Country of origin), `asylum` (Country of asylum), `both` (Both: each pair of origin and asylum). Default: `none`.
- Most rows (`limit`, number): The most rows to list, largest first (up to 1,000). Totals still count every one. From 1 to 1000. Default: `100`.

**Outputs**

- `asylum_filter` (list): The countries of asylum the figures were narrowed to; empty for every country.
- `break_down_by` (text): How the rows are split: none (one total per year), origin, asylum or both.
- `count` (number): How many rows are listed.
- `download_url` (text): A link that downloads the same figures, with UNHCR's footnotes, as a zip of CSV files a spreadsheet can open.
- `latest_year` (number): The latest year UNHCR has published asylum decisions for. A year left empty means this one.
- `origin_filter` (list): The countries of origin the figures were narrowed to; empty for every country.
- `rows` (list): The figures, newest year first and largest first.
- `total_rows` (number): How many rows there are before the row limit.
- `totals` (list): Every row added up, one line per year (newest first), including rows left out by the row limit.
- `truncated` (true/false): Whether rows were left out to keep to the row limit.
- `year_from` (number): The first year of asylum decisions asked for.
- `year_to` (number): The last year of asylum decisions asked for.

**Example output**

```json
{
  "asylum_filter": [
    {
      "country": "Germany",
      "iso3": "DEU"
    }
  ],
  "break_down_by": "none",
  "count": 1,
  "download_url": "https://api.unhcr.org/population/v1/asylum-decisions/?cf_type=ISO&coo=SYR&coa=DEU&yearFrom=2024&yearTo=2024&download=true",
  "latest_year": 2025,
  "origin_filter": [
    {
      "country": "Syrian Arab Rep.",
      "iso3": "SYR"
    }
  ],
  "rows": [
    {
      "asylum_country": "Germany",
      "asylum_iso3": "DEU",
      "complementary_protection": 70836,
      "counted_in": "persons",
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "otherwise_closed": 24804,
      "recognized": 7291,
      "refugee_recognition_rate": 9.0,
      "rejected": 3197,
      "total_decisions": 106128,
      "total_recognition_rate": 96.1,
      "year": 2024
    }
  ],
  "total_rows": 1,
  "totals": [
    {
      "asylum_country": "Germany",
      "asylum_iso3": "DEU",
      "complementary_protection": 70836,
      "counted_in": "persons",
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "otherwise_closed": 24804,
      "recognized": 7291,
      "refugee_recognition_rate": 9.0,
      "rejected": 3197,
      "total_decisions": 106128,
      "total_recognition_rate": 96.1,
      "year": 2024
    }
  ],
  "truncated": false,
  "year_from": 2024,
  "year_to": 2024
}
```

### Get country overview

Sum up one country for a year: the refugees, asylum-seekers, internally displaced and stateless people it hosts, how many of its own people are refugees or asylum-seekers abroad, and the countries they come from and have gone to.

**Inputs**

- Country (`country`, text, required): The country to sum up.
- Year (`year`, number): The year, counting people at its end. Leave empty for the latest year UNHCR has published. From 1951 to 2026.
- How many countries (`top`, number): How many countries of origin and destination to list (up to 50). From 1 to 50. Default: `5`.

**Outputs**

- `abroad` (object): People from the country living in other countries.
- `country` (text): The country's name, as UNHCR writes it.
- `download_url` (text): A link that downloads the country's figures by country of origin, with UNHCR's footnotes, as a zip of CSV files.
- `found` (true/false): Whether UNHCR has any figures for the country in that year.
- `hosted` (object): The people in the country, whatever their origin: those who fled to it, its own internally displaced, returnees and stateless people.
- `iso3` (text): Its three-letter ISO code.
- `latest_year` (number): The latest year UNHCR has published population figures for.
- `top_destinations` (list): Where refugees and others in need of protection from the country now live, largest first.
- `top_origins` (list): Where the refugees and others in need of protection in the country come from, largest first.
- `year` (number): The year; the figures count people at its end.

**Example output**

```json
{
  "abroad": {
    "asylum_seekers": 853,
    "other_in_need": null,
    "refugees": 348
  },
  "country": "Germany",
  "download_url": "https://api.unhcr.org/population/v1/population/?cf_type=ISO&coa=DEU&coo_all=true&yearFrom=2024&yearTo=2024&download=true",
  "found": true,
  "hosted": {
    "asylum_seekers": 348903,
    "host_community": 0,
    "idps": 0,
    "other_in_need": null,
    "others_of_concern": 0,
    "refugees": 2749266,
    "returned_idps": 0,
    "returned_refugees": 17000,
    "stateless": 28813
  },
  "iso3": "DEU",
  "latest_year": 2025,
  "top_destinations": [
    {
      "asylum_seekers": 60,
      "country": "Russian Federation",
      "iso3": "RUS",
      "other_in_need": null,
      "refugees": 189
    },
    {
      "asylum_seekers": 38,
      "country": "Canada",
      "iso3": "CAN",
      "other_in_need": null,
      "refugees": 39
    }
  ],
  "top_origins": [
    {
      "asylum_seekers": 1830,
      "country": "Ukraine",
      "iso3": "UKR",
      "other_in_need": null,
      "refugees": 1205729
    },
    {
      "asylum_seekers": 62959,
      "country": "Syrian Arab Rep.",
      "iso3": "SYR",
      "other_in_need": null,
      "refugees": 725102
    }
  ],
  "year": 2024
}
```

### Get demographics

Get the age and sex of refugees, asylum-seekers or another group for a country of origin or asylum and year: women and men in each age group (0 to 4, 5 to 11, 12 to 17, 18 to 59, 60 and over), with the share of women and of children. Available from 2001.

**Inputs**

- Country of origin (`origin`, text): The country the people come from. Pick one, or type several ISO3 codes separated by commas (SYR, AFG). Leave empty for every country.
- Country of asylum (`asylum`, text): The country the people are in. Pick one, or type several ISO3 codes separated by commas (DEU, FRA). Leave empty for every country.
- Population types (`population_types`, list): The groups to describe, each in its own row. Tick none for every group. One or more of: `refugees`, `asylum_seekers` (Asylum-seekers), `other_in_need` (Other people in need of international protection), `idps` (Internally displaced people), `returned_refugees` (Returned refugees), `returned_idps` (Returned IDPs), `stateless` (Stateless people), `others_of_concern` (Others of concern), `host_community` (Host community). Default: `["refugees"]`.
- Year (`year`, number): The year, or the first of several. Figures count people at the end of the year. Leave empty for the latest year UNHCR has published. From 2001 to 2026.
- To year (`to_year`, number): For several years, the last one. Leave empty for just the one year. From 2001 to 2026.
- Break down by (`break_down_by`, text): One total per year, or a row for each country of origin, each country of asylum, or each pair of them. One of: `none` (No breakdown: one total per year), `origin` (Country of origin), `asylum` (Country of asylum), `both` (Both: each pair of origin and asylum). Default: `none`.
- Most rows (`limit`, number): The most rows to list, largest first (up to 1,000). Totals still count every one. From 1 to 1000. Default: `100`.

**Outputs**

- `asylum_filter` (list): The countries of asylum the figures were narrowed to; empty for every country.
- `break_down_by` (text): How the rows are split: none (one total per year), origin, asylum or both.
- `count` (number): How many rows are listed.
- `download_url` (text): A link that downloads the same figures, with UNHCR's footnotes, as a zip of CSV files a spreadsheet can open.
- `latest_year` (number): The latest year UNHCR has published demographics for. A year left empty means this one.
- `origin_filter` (list): The countries of origin the figures were narrowed to; empty for every country.
- `population_types` (list): The groups asked for, in words.
- `rows` (list): The figures, newest year first and largest first.
- `total_rows` (number): How many rows there are before the row limit.
- `totals` (list): Every row added up, one line per year (newest first), including rows left out by the row limit.
- `truncated` (true/false): Whether rows were left out to keep to the row limit.
- `year_from` (number): The first year of demographics asked for.
- `year_to` (number): The last year of demographics asked for.

**Example output**

```json
{
  "asylum_filter": [],
  "break_down_by": "none",
  "count": 2,
  "download_url": "https://api.unhcr.org/population/v1/demographics/?cf_type=ISO&coo=SYR&yearFrom=2024&yearTo=2024&ptype_show=true&columns%5B%5D=refugees&columns%5B%5D=asylum_seekers&download=true",
  "latest_year": 2025,
  "origin_filter": [
    {
      "country": "Syrian Arab Rep.",
      "iso3": "SYR"
    }
  ],
  "population_types": [
    "Refugees",
    "Asylum-seekers"
  ],
  "rows": [
    {
      "asylum_country": null,
      "asylum_iso3": null,
      "children": 2666989,
      "children_percent": 46.0,
      "female_0_4": 361651,
      "female_12_17": 368730,
      "female_18_59": 1333250,
      "female_5_11": 556996,
      "female_60_plus": 99900,
      "female_age_unknown": 39666,
      "female_percent": 46.9,
      "female_total": 2760193,
      "male_0_4": 379696,
      "male_12_17": 408485,
      "male_18_59": 1607961,
      "male_5_11": 591431,
      "male_60_plus": 88999,
      "male_age_unknown": 47313,
      "male_total": 3123885,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "population_type": "Refugees",
      "population_type_code": "REF",
      "sex_unknown": 68096,
      "total": 5952174,
      "year": 2024
    },
    {
      "asylum_country": null,
      "asylum_iso3": null,
      "children": 41143,
      "children_percent": 32.0,
      "female_0_4": 4652,
      "female_12_17": 4546,
      "female_18_59": 21063,
      "female_5_11": 6477,
      "female_60_plus": 1317,
      "female_age_unknown": 1882,
      "female_percent": 29.7,
      "female_total": 39937,
      "male_0_4": 4323,
      "male_12_17": 13514,
      "male_18_59": 63700,
      "male_5_11": 7631,
      "male_60_plus": 1514,
      "male_age_unknown": 4033,
      "male_total": 94715,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "population_type": "Asylum-seekers",
      "population_type_code": "ASY",
      "sex_unknown": 32682,
      "total": 167334,
      "year": 2024
    }
  ],
  "total_rows": 2,
  "totals": [
    {
      "asylum_country": null,
      "asylum_iso3": null,
      "children": 2666989,
      "children_percent": 46.0,
      "female_0_4": 361651,
      "female_12_17": 368730,
      "female_18_59": 1333250,
      "female_5_11": 556996,
      "female_60_plus": 99900,
      "female_age_unknown": 39666,
      "female_percent": 46.9,
      "female_total": 2760193,
      "male_0_4": 379696,
      "male_12_17": 408485,
      "male_18_59": 1607961,
      "male_5_11": 591431,
      "male_60_plus": 88999,
      "male_age_unknown": 47313,
      "male_total": 3123885,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "population_type": "Refugees",
      "population_type_code": "REF",
      "sex_unknown": 68096,
      "total": 5952174,
      "year": 2024
    },
    {
      "asylum_country": null,
      "asylum_iso3": null,
      "children": 41143,
      "children_percent": 32.0,
      "female_0_4": 4652,
      "female_12_17": 4546,
      "female_18_59": 21063,
      "female_5_11": 6477,
      "female_60_plus": 1317,
      "female_age_unknown": 1882,
      "female_percent": 29.7,
      "female_total": 39937,
      "male_0_4": 4323,
      "male_12_17": 13514,
      "male_18_59": 63700,
      "male_5_11": 7631,
      "male_60_plus": 1514,
      "male_age_unknown": 4033,
      "male_total": 94715,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "population_type": "Asylum-seekers",
      "population_type_code": "ASY",
      "sex_unknown": 32682,
      "total": 167334,
      "year": 2024
    }
  ],
  "truncated": false,
  "year_from": 2024,
  "year_to": 2024
}
```

### Get durable solutions

Get how many refugees went home, were resettled to another country or became citizens of their country of asylum in a year, and how many internally displaced people went home. Returns count under the country people left, resettlement under the country they went to.

**Inputs**

- Country of origin (`origin`, text): The country the refugees come from. Pick one, or type several ISO3 codes separated by commas (SYR, AFG). Leave empty for every country.
- Country of asylum (`asylum`, text): The country the refugees are in. Pick one, or type several ISO3 codes separated by commas (DEU, FRA). Leave empty for every country.
- Year (`year`, number): The year, or the first of several. Figures count what happened during the year. Leave empty for the latest year UNHCR has published. From 1959 to 2026.
- To year (`to_year`, number): For several years, the last one. Leave empty for just the one year. From 1959 to 2026.
- Break down by (`break_down_by`, text): One total per year, or a row for each country of origin, each country of asylum, or each pair of them. One of: `none` (No breakdown: one total per year), `origin` (Country of origin), `asylum` (Country of asylum), `both` (Both: each pair of origin and asylum). Default: `none`.
- Most rows (`limit`, number): The most rows to list, largest first (up to 1,000). Totals still count every one. From 1 to 1000. Default: `100`.

**Outputs**

- `asylum_filter` (list): The countries of asylum the figures were narrowed to; empty for every country.
- `break_down_by` (text): How the rows are split: none (one total per year), origin, asylum or both.
- `count` (number): How many rows are listed.
- `download_url` (text): A link that downloads the same figures, with UNHCR's footnotes, as a zip of CSV files a spreadsheet can open.
- `latest_year` (number): The latest year UNHCR has published durable solutions for. A year left empty means this one.
- `origin_filter` (list): The countries of origin the figures were narrowed to; empty for every country.
- `rows` (list): The figures, newest year first and largest first.
- `total_rows` (number): How many rows there are before the row limit.
- `totals` (list): Every row added up, one line per year (newest first), including rows left out by the row limit.
- `truncated` (true/false): Whether rows were left out to keep to the row limit.
- `year_from` (number): The first year of durable solutions asked for.
- `year_to` (number): The last year of durable solutions asked for.

**Example output**

```json
{
  "asylum_filter": [],
  "break_down_by": "asylum",
  "count": 2,
  "download_url": "https://api.unhcr.org/population/v1/solutions/?cf_type=ISO&coo=SYR&coa_all=true&yearFrom=2024&yearTo=2024&download=true",
  "latest_year": 2025,
  "origin_filter": [
    {
      "country": "Syrian Arab Rep.",
      "iso3": "SYR"
    }
  ],
  "rows": [
    {
      "asylum_country": "Syrian Arab Rep.",
      "asylum_iso3": "SYR",
      "naturalisations": null,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "resettlement_arrivals": null,
      "returned_idps": 513896,
      "returned_refugees": null,
      "year": 2024
    },
    {
      "asylum_country": "Lebanon",
      "asylum_iso3": "LBN",
      "naturalisations": null,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "resettlement_arrivals": null,
      "returned_idps": null,
      "returned_refugees": 254651,
      "year": 2024
    }
  ],
  "total_rows": 26,
  "totals": [
    {
      "asylum_country": null,
      "asylum_iso3": null,
      "naturalisations": 17595,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "resettlement_arrivals": 25532,
      "returned_idps": 513896,
      "returned_refugees": 512718,
      "year": 2024
    }
  ],
  "truncated": true,
  "year_from": 2024,
  "year_to": 2024
}
```

### Get footnotes

Get the notes UNHCR publishes with its figures for a country of origin or asylum: how a figure was estimated, what it includes, and gaps in the data. Worth reading before quoting a figure.

**Inputs**

- Country of origin (`origin`, text): The country the people come from. Pick one, or type several ISO3 codes separated by commas (SYR, AFG). Leave empty for every country.
- Country of asylum (`asylum`, text): The country the people are in. Pick one, or type several ISO3 codes separated by commas (DEU, FRA). Leave empty for every country.
- Year (`year`, number): Only notes about this year, or the first of several. Leave empty for notes about every year. From 1951 to 2026.
- To year (`to_year`, number): For several years, the last one. Leave empty for just the one year. From 1951 to 2026.
- Most rows (`limit`, number): The most notes to list, largest first (up to 1,000). Totals still count every one. From 1 to 1000. Default: `100`.

**Outputs**

- `asylum_filter` (list): The countries of asylum asked for; empty for every country.
- `count` (number): How many footnotes are listed.
- `origin_filter` (list): The countries of origin asked for; empty for every country.
- `rows` (list): The footnotes, most recent first.
- `total_rows` (number): How many footnotes match before the row limit.
- `truncated` (true/false): Whether footnotes were left out to keep to the row limit.
- `year_from` (number): The first year asked for; empty for every year.
- `year_to` (number): The last year asked for; empty for every year.

**Example output**

```json
{
  "asylum_filter": [],
  "count": 2,
  "origin_filter": [
    {
      "country": "Afghanistan",
      "iso3": "AFG"
    }
  ],
  "rows": [
    {
      "asylum_country": null,
      "asylum_iso3": null,
      "first_year": 2019,
      "last_year": 2025,
      "origin_country": "Afghanistan",
      "origin_iso3": "AFG",
      "population_type_codes": [
        "REF"
      ],
      "population_types": [
        "Refugees"
      ],
      "text": "Refugees includes people in a refugee-like situation",
      "years": "2019 - 2022, 2024 - 2025"
    },
    {
      "asylum_country": "Pakistan",
      "asylum_iso3": "PAK",
      "first_year": 2023,
      "last_year": 2023,
      "origin_country": "Afghanistan",
      "origin_iso3": "AFG",
      "population_type_codes": [
        "REF"
      ],
      "population_types": [
        "Refugees"
      ],
      "text": "The 2.0 million refugees include around 1,371,400 registered refugees and around 143,900 unregistered members of registered families who were recorded through the documentation renewal and information verification exercise (DRIVE) and are being verified at the time of reporting. It also includes an estimated 472,900 Afghans who sought asylum in Pakistan, following transition in Afghanistan in August 2021. In total, some 600,000 Afghans have arrived in Pakistan since then, according to the Government estimates.",
      "years": "2023"
    }
  ],
  "total_rows": 2,
  "truncated": false,
  "year_from": 2023,
  "year_to": 2024
}
```

### Get latest estimates

Get UNHCR's estimates for the current year, before its official figures are published: refugees and asylum-seekers in each country of asylum, as of the latest month, with where each estimate comes from.

**Inputs**

- Country of asylum (`asylum`, text): The country the people are in. Pick one, or type several ISO3 codes separated by commas (DEU, FRA). Leave empty for every country.
- Most rows (`limit`, number): The most countries to list, largest first (up to 1,000). Totals still count every one. From 1 to 1000. Default: `100`.

**Outputs**

- `as_of` (text): The month and year the estimates are as of, such as September 2026.
- `asylum_filter` (list): The countries of asylum asked for; empty for every country.
- `count` (number): How many countries are listed.
- `download_url` (text): A link that downloads the same estimates as a zip of CSV files.
- `month` (text): The month the estimates are as of, such as September.
- `rows` (list): The estimates, largest number of refugees first.
- `total_rows` (number): How many countries have an estimate.
- `totals` (object): The estimates added up over every country asked for.
- `truncated` (true/false): Whether countries were left out to keep to the row limit.
- `year` (number): The year the estimates are for (the current year).

**Example output**

```json
{
  "as_of": "September 2026",
  "asylum_filter": [],
  "count": 2,
  "download_url": "https://api.unhcr.org/population/v1/nowcasting/?cf_type=ISO&coa_all=true&download=true",
  "month": "September",
  "rows": [
    {
      "asylum_country": "Germany",
      "asylum_iso3": "DEU",
      "asylum_seekers": 211575,
      "refugees": 2600712,
      "source": "Government"
    },
    {
      "asylum_country": "T\u00fcrkiye",
      "asylum_iso3": "TUR",
      "asylum_seekers": 102497,
      "refugees": 2245537,
      "source": "Government, UNHCR official statistics, UNHCR operational data"
    }
  ],
  "total_rows": 169,
  "totals": {
    "asylum_seekers": 9024238,
    "refugees": 28271758
  },
  "truncated": true,
  "year": 2026
}
```

### Get population figures

Get how many refugees, asylum-seekers, other people in need of international protection, internally displaced, returned and stateless people UNHCR counts at the end of a year, for any country of origin and country of asylum, since 1951. Break the figures down by either country, or both.

**Inputs**

- Country of origin (`origin`, text): The country the people come from. Pick one, or type several ISO3 codes separated by commas (SYR, AFG). Leave empty for every country.
- Country of asylum (`asylum`, text): The country the people are in. Pick one, or type several ISO3 codes separated by commas (DEU, FRA). Leave empty for every country.
- Year (`year`, number): The year, or the first of several. Figures count people at the end of the year. Leave empty for the latest year UNHCR has published. From 1951 to 2026.
- To year (`to_year`, number): For several years, the last one. Leave empty for just the one year. From 1951 to 2026.
- Break down by (`break_down_by`, text): One total per year, or a row for each country of origin, each country of asylum, or each pair of them. One of: `none` (No breakdown: one total per year), `origin` (Country of origin), `asylum` (Country of asylum), `both` (Both: each pair of origin and asylum). Default: `none`.
- Most rows (`limit`, number): The most rows to list, largest first (up to 1,000). Totals still count every one. From 1 to 1000. Default: `100`.

**Outputs**

- `asylum_filter` (list): The countries of asylum the figures were narrowed to; empty for every country.
- `break_down_by` (text): How the rows are split: none (one total per year), origin, asylum or both.
- `count` (number): How many rows are listed.
- `download_url` (text): A link that downloads the same figures, with UNHCR's footnotes, as a zip of CSV files a spreadsheet can open.
- `latest_year` (number): The latest year UNHCR has published population figures for. A year left empty means this one.
- `origin_filter` (list): The countries of origin the figures were narrowed to; empty for every country.
- `rows` (list): The figures, newest year first and largest first.
- `total_rows` (number): How many rows there are before the row limit.
- `totals` (list): Every row added up, one line per year (newest first), including rows left out by the row limit.
- `truncated` (true/false): Whether rows were left out to keep to the row limit.
- `year_from` (number): The first year of population figures asked for.
- `year_to` (number): The last year of population figures asked for.

**Example output**

```json
{
  "asylum_filter": [],
  "break_down_by": "asylum",
  "count": 2,
  "download_url": "https://api.unhcr.org/population/v1/population/?cf_type=ISO&coo=SYR&coa_all=true&yearFrom=2024&yearTo=2024&download=true",
  "latest_year": 2025,
  "origin_filter": [
    {
      "country": "Syrian Arab Rep.",
      "iso3": "SYR"
    }
  ],
  "rows": [
    {
      "asylum_country": "Syrian Arab Rep.",
      "asylum_iso3": "SYR",
      "asylum_seekers": 0,
      "host_community": 16471143,
      "idps": 7408909,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "other_in_need": null,
      "others_of_concern": 0,
      "refugees": 0,
      "returned_idps": 513896,
      "returned_refugees": 0,
      "stateless": 0,
      "year": 2024
    },
    {
      "asylum_country": "T\u00fcrkiye",
      "asylum_iso3": "TUR",
      "asylum_seekers": 0,
      "host_community": 0,
      "idps": 0,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "other_in_need": null,
      "others_of_concern": 0,
      "refugees": 2901478,
      "returned_idps": 0,
      "returned_refugees": 159439,
      "stateless": 0,
      "year": 2024
    }
  ],
  "total_rows": 125,
  "totals": [
    {
      "asylum_country": null,
      "asylum_iso3": null,
      "asylum_seekers": 167334,
      "host_community": 16471143,
      "idps": 7408909,
      "origin_country": "Syrian Arab Rep.",
      "origin_iso3": "SYR",
      "other_in_need": null,
      "others_of_concern": 3416,
      "refugees": 5952174,
      "returned_idps": 513896,
      "returned_refugees": 512718,
      "stateless": 0,
      "year": 2024
    }
  ],
  "truncated": true,
  "year_from": 2024,
  "year_to": 2024
}
```

### List available years

List the years each of UNHCR's datasets covers, from the first to the latest published, such as population figures from 1951. Use it to find the latest year before asking for figures.

**Inputs**: None.

**Outputs**

- `count` (number): How many datasets are listed.
- `latest_year` (number): The latest year UNHCR has published population figures for.
- `rows` (list): Each dataset and the years it covers.

**Example output**

```json
{
  "count": 6,
  "latest_year": 2025,
  "rows": [
    {
      "action": "Get population figures",
      "dataset": "population",
      "first_year": 1951,
      "latest_year": 2025,
      "name": "Population figures",
      "year_count": 75
    },
    {
      "action": "Get demographics",
      "dataset": "demographics",
      "first_year": 2001,
      "latest_year": 2025,
      "name": "Demographics",
      "year_count": 25
    },
    {
      "action": "Get asylum applications",
      "dataset": "asylum_applications",
      "first_year": 2000,
      "latest_year": 2025,
      "name": "Asylum applications",
      "year_count": 26
    },
    {
      "action": "Get asylum decisions",
      "dataset": "asylum_decisions",
      "first_year": 2000,
      "latest_year": 2025,
      "name": "Asylum decisions",
      "year_count": 26
    },
    {
      "action": "Get durable solutions",
      "dataset": "solutions",
      "first_year": 1959,
      "latest_year": 2025,
      "name": "Durable solutions",
      "year_count": 67
    },
    {
      "action": "Get latest estimates",
      "dataset": "latest_estimates",
      "first_year": 2026,
      "latest_year": 2026,
      "name": "Latest estimates",
      "year_count": 1
    }
  ]
}
```

### List countries

List the countries and territories UNHCR reports on, with their ISO codes, UNHCR's own code, continent and UNHCR region. Find a country's code by name, or list a region's countries.

**Inputs**

- UNHCR region (`unhcr_region`, text): Only countries in this UNHCR region. Leave empty for every region.
- Search (`search`, text): Only countries whose name or code contains these letters.

**Outputs**

- `count` (number): How many countries are listed.
- `rows` (list): The countries, by name.
- `search` (text): The words searched for; empty when not searching.
- `unhcr_region` (text): The UNHCR region asked for; empty for every region.

**Example output**

```json
{
  "count": 1,
  "rows": [
    {
      "continent": "Europe",
      "country": "Germany",
      "iso2": "DE",
      "iso3": "DEU",
      "long_name": "Germany",
      "un_subregion": "Western Europe",
      "unhcr_code": "GFR",
      "unhcr_region": "Europe",
      "unhcr_region_id": 7
    }
  ],
  "search": "germany",
  "unhcr_region": null
}
```

### List regions

List UNHCR's regions, such as Europe or Asia and the Pacific, with how many countries each covers.

**Inputs**: None.

**Outputs**

- `count` (number): How many regions are listed.
- `rows` (list): UNHCR's regions, by name.

**Example output**

```json
{
  "count": 3,
  "rows": [
    {
      "country_count": 52,
      "id": 5,
      "name": "Asia and the Pacific",
      "name_french": "Asie et Pacifique"
    },
    {
      "country_count": 26,
      "id": 3,
      "name": "Eastern and Southern Africa",
      "name_french": "Afrique de l'Afrique de l'Est et Corne de l'Afrique"
    },
    {
      "country_count": 54,
      "id": 7,
      "name": "Europe",
      "name_french": "Europe"
    }
  ]
}
```

### Rank countries

List the countries hosting the most refugees (or another group of displaced or stateless people) in a year, or the countries most of them come from, largest first, with each one's share of the total. Narrow it to people from one country, or in one.

**Inputs**

- Rank (`ranking`, text): Rank the countries people are in, or the countries they come from. One of: `asylum` (Countries of asylum (where people are)), `origin` (Countries of origin (where people come from)). Default: `asylum`.
- People to count (`population_type`, text): The group of displaced or stateless people to count. One of: `refugees`, `refugees_and_other_in_need` (Refugees and other people in need of international protection), `asylum_seekers` (Asylum-seekers), `other_in_need` (Other people in need of international protection), `idps` (Internally displaced people), `returned_refugees` (Returned refugees), `returned_idps` (Returned IDPs), `stateless` (Stateless people), `others_of_concern` (Others of concern), `host_community` (Host community). Default: `refugees`.
- Only people from (`origin`, text): Count only people from this country, such as Syria to see where Syrian refugees live. Leave empty for people from every country. Only when Rank is Countries of asylum (where people are).
- Only people in (`asylum`, text): Count only people in this country, such as Germany to see where its refugees come from. Leave empty for every country. Only when Rank is Countries of origin (where people come from).
- Year (`year`, number): The year to rank, counting people at its end. Leave empty for the latest year UNHCR has published. From 1951 to 2026.
- How many countries (`top`, number): How many countries to list, from the largest (up to 250). From 1 to 250. Default: `10`.

**Outputs**

- `asylum_filter` (list): The countries of asylum counted; empty for every country.
- `count` (number): How many countries are listed.
- `country_count` (number): How many countries count anyone of the group.
- `download_url` (text): A link that downloads the figures behind the ranking, with UNHCR's footnotes, as a zip of CSV files.
- `latest_year` (number): The latest year UNHCR has published population figures for.
- `origin_filter` (list): The countries of origin counted; empty for every country.
- `population_type` (text): The group counted, such as refugees or asylum_seekers.
- `population_type_label` (text): The group counted, in words, such as Refugees.
- `ranking` (text): What is ranked: asylum (the countries people are in) or origin (the countries they come from).
- `rows` (list): The countries, largest first.
- `total` (number): The group's total over every country, ranked or not.
- `year` (number): The year ranked; the figures count people at its end.

**Example output**

```json
{
  "asylum_filter": [],
  "count": 3,
  "country_count": 170,
  "download_url": "https://api.unhcr.org/population/v1/population/?cf_type=ISO&coa_all=true&yearFrom=2024&yearTo=2024&download=true",
  "latest_year": 2025,
  "origin_filter": [],
  "population_type": "refugees",
  "population_type_label": "Refugees",
  "ranking": "asylum",
  "rows": [
    {
      "country": "Iran (Islamic Rep. of)",
      "iso3": "IRN",
      "percent_of_total": 11.3,
      "rank": 1,
      "value": 3489257
    },
    {
      "country": "T\u00fcrkiye",
      "iso3": "TUR",
      "percent_of_total": 9.5,
      "rank": 2,
      "value": 2940735
    },
    {
      "country": "Germany",
      "iso3": "DEU",
      "percent_of_total": 8.9,
      "rank": 3,
      "value": 2749266
    }
  ],
  "total": 30958200,
  "year": 2024
}
```
