Tutorial: International Migration (UNHCR)

Government

Data source: UNHCR Population Statistics API

Overview

International Migration (UNHCR) wraps UNHCR Population Statistics API, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-migration": {
      "url": "https://context.gnist.ai/mcp/migration/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`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`)

curl -X POST "https://context.gnist.ai/mcp/migration/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_population", "arguments": {"year": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/migration/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'year': 'example'}, 'name': 'get_population'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/migration/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_demographics", "arguments": {"year": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/migration/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'year': 'example'}, 'name': 'get_demographics'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/migration/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_solutions", "arguments": {"year": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/migration/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'year': 'example'}, 'name': 'get_solutions'}},
)
print(resp.json())

`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}).

curl -X POST "https://context.gnist.ai/mcp/migration/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_countries", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/migration/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_countries'}},
)
print(resp.json())

`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`)

curl -X POST "https://context.gnist.ai/mcp/migration/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/migration/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use list_countries to find items, then get_population to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does International Migration (UNHCR) provide?

Global displacement statistics from UNHCR — refugees, asylum seekers, IDPs, stateless persons. 70+ years of data across 200+ countries with demographics and durable solutions. It exposes 5 tools: get_population, get_demographics, get_solutions, list_countries, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the International Migration (UNHCR) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.