get_demographics_data
Retrieve UNHCR demographic data for forcibly displaced populations, including age and sex breakdowns, filtered by country of origin, asylum, year, and population type.
Instructions
Get forcibly displaced populations demographics data from UNHCR. It shows breakdown by age and sex when available.
Args:
coo: Country of origin (ISO3 code) - Use for questions about forcibly displaced populations FROM a specific country
coa: Country of asylum (ISO3 code) - Use for questions about forcibly displaced populations IN a specific country
year: Year to filter by (defaults to 2025)
coo_all: Set to True when breaking down results by ORIGIN country
coa_all: Set to True when breaking down results by ASYLUM country
pop_type: Set to True when asked about specific population types (e.g., refugees, asylum seekers, stateless persons)
Returns:
Demographics data from UNHCR API
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| coo | No | ||
| coa | No | ||
| year | No | ||
| coo_all | No | ||
| coa_all | No | ||
| pop_type | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/unhcr_mcp/server.py:148-173 (handler)The MCP tool handler for 'get_demographics_data', decorated with @server.tool(). It invokes the UNHCRAPIClient to fetch demographics data from the UNHCR API.
@server.tool() def get_demographics_data( coo: str | None = None, coa: str | None = None, year: str | int | None = None, coo_all: bool = False, coa_all: bool = False, pop_type: bool = False, ) -> dict[str, Any]: """ Get forcibly displaced populations demographics data from UNHCR. It shows breakdown by age and sex when available. Args: coo: Country of origin (ISO3 code) - Use for questions about forcibly displaced populations FROM a specific country coa: Country of asylum (ISO3 code) - Use for questions about forcibly displaced populations IN a specific country year: Year to filter by (defaults to 2025) coo_all: Set to True when breaking down results by ORIGIN country coa_all: Set to True when breaking down results by ASYLUM country pop_type: Set to True when asked about specific population types (e.g., refugees, asylum seekers, stateless persons) Returns: Demographics data from UNHCR API """ return api_client.get_demographics( coo=coo, coa=coa, year=year, coo_all=coo_all, coa_all=coa_all, pop_type=pop_type ) - src/unhcr_mcp/server.py:85-88 (helper)Helper method in the UNHCRAPIClient class that calls the generic _fetch method specifically for the 'demographics' endpoint.
def get_demographics(self, coo: Optional[str] = None, coa: Optional[str] = None, year: Optional[Union[str, int]] = None, coo_all: bool = False, coa_all: bool = False, pop_type: bool = False) -> dict[str, Any]: return self._fetch("demographics", coo=coo, coa=coa, year=year, coo_all=coo_all, coa_all=coa_all, pop_type=pop_type) - src/unhcr_mcp/server.py:40-78 (helper)Core helper function _fetch in UNHCRAPIClient that constructs API parameters and makes HTTP requests to UNHCR endpoints.
pop_type: Optional[bool] = None) -> dict[str, Any]: """ Generic function to fetch data from various UNHCR API endpoints. """ params = {"cf_type": "ISO"} if coo: params["coo"] = coo if coa: params["coa"] = coa if coo_all: params["coo_all"] = "true" if coa_all: params["coa_all"] = "true" if pop_type is True: params["pop_type"] = "true" if year is None: # Default to 2025 as per previous implementation logic params["year[]"] = "2025" else: year_str = str(year) if "," in year_str: years = [y.strip() for y in year_str.split(",")] params["year[]"] = years else: params["year[]"] = year_str url = f"{self.BASE_URL}/{endpoint}/" try: logger.info(f"Fetching UNHCR {endpoint} data with params: {params}") response = requests.get(url, params=params) response.raise_for_status() return response.json() except requests.RequestException as e: logger.error(f"Error fetching UNHCR {endpoint} data: {e}") return {"error": str(e), "status": "error"}