Tools (5)

get_population
get_demographics
get_solutions
list_countries
report_feedback

get_population

Get refugee, asylum seeker, IDP, and stateless population statistics from UNHCR.

Covers 70+ years of global displacement data across 200+ countries. Returns counts of
refugees, asylum seekers, internally displaced persons (IDPs), stateless persons,
and other populations of concern by country of origin and asylum.

Examples:
get_population(year=2023, country_of_origin="SYR") → Syrian displacement worldwide
get_population(year=2023, country_of_asylum="DEU") → All displaced populations in Germany
get_population(year=2023) → Global displacement snapshot

Returns:
page, max_pages, results (list of population records by origin/asylum pair).

Parameter	Type	Required	Description
`year`	`any`	optional	Filter by year (1951–2025). Example: 2023.
`country_of_origin`	`any`	optional	ISO country code of origin (2 or 3 letter). Example: 'SYR' for Syria, 'UA' for Ukraine.
`country_of_asylum`	`any`	optional	ISO country code of asylum (2 or 3 letter). Example: 'DEU' for Germany, 'US' for United States.
`limit`	`integer`	optional	Results per page (1-100). (default: 20)
`page`	`integer`	optional	Page number. (default: 1)

Request Body

{
  "query": "example"
}

get_demographics

Get age and gender demographic breakdowns of displaced populations.

Returns female/male counts across age brackets (0-4, 5-11, 12-17, 18-59, 60+)
for each origin/asylum country pair.

Examples:
get_demographics(year=2023, country_of_asylum="DEU") → Age/gender of displaced in Germany
get_demographics(year=2023, country_of_origin="AFG") → Afghan refugee demographics worldwide

Returns:
page, max_pages, results (list with female/male age breakdowns).

Parameter	Type	Required	Description
`year`	`any`	optional	Filter by year (1951–2025).
`country_of_origin`	`any`	optional	ISO country code of origin.
`country_of_asylum`	`any`	optional	ISO country code of asylum.
`limit`	`integer`	optional	Results per page (1-100). (default: 20)
`page`	`integer`	optional	Page number. (default: 1)

Request Body

{
  "query": "example"
}

get_solutions

Get durable solutions data — refugee returns, resettlement, and naturalisation.

Tracks how displacement is resolved: voluntary repatriation (returned refugees),
third-country resettlement, naturalisation in country of asylum, and IDP returns.

Examples:
get_solutions(year=2023) → Global solutions overview
get_solutions(year=2023, country_of_origin="SYR") → Syrian returns and resettlement

Returns:
page, max_pages, results (list with returned_refugees, resettlement, naturalisation, returned_idps).

Parameter	Type	Required	Description
`year`	`any`	optional	Filter by year (1951–2025).
`country_of_origin`	`any`	optional	ISO country code of origin.
`country_of_asylum`	`any`	optional	ISO country code of asylum.
`limit`	`integer`	optional	Results per page (1-100). (default: 20)
`page`	`integer`	optional	Page number. (default: 1)

Request Body

{
  "query": "example"
}

list_countries

List all countries and territories in the UNHCR displacement dataset.

Returns ISO codes, names, regions, and major areas for 200+ countries.
Use these codes with get_population, get_demographics, and get_solutions.

Returns:
total, countries (list of {code, iso, iso2, name, region, major_area}).

Request Body

{
  "query": "example"
}

report_feedback

Report a bug, feature request, or general feedback for this data source.

Use this when something doesn't work as expected, when you'd like
a new feature, or when you have suggestions for improvement.

Args:
feedback: Describe the issue or suggestion.
feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	`string`	required
`feedback_type`	`string`	optional	(default: "general")

Request Body

{
  "feedback": "example"
}

Quick Start

Shell

curl -X POST "https://context.gnist.ai/rest/migration/report_feedback" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"feedback": "example"}'

Python

import httpx

resp = httpx.post(
    "https://context.gnist.ai/rest/migration/report_feedback",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={
  "feedback": "example"
},
)
print(resp.json())