Tutorial: ILOSTAT (ILO Labour Statistics)

Economics

Data source: ILO (SDMX 2.1)

Overview

ILOSTAT (ILO Labour Statistics) wraps ILO (SDMX 2.1), handling authentication, pagination, and rate limits for you. This tutorial covers all 6 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-ilostat": {
      "url": "https://context.gnist.ai/mcp/ilostat/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`search_datasets`

Search the ILOSTAT dataset catalog by keyword. Returns matching datasets with their dataflow IDs needed for get_data, get_dataset_structure, and compare_countries calls. ILOSTAT covers employment, unemployment, wages, working conditions, labour force participation, child labour, migration, and social protection across 190+ countries. Args: query: Search term (e.g. "unemployment", "wages", "child labour"). limit: Number of results to return (1-50, default 20). Returns: List of matching datasets with id, name, agency, and description. Use the 'id' field as the dataflow parameter in other tools.

Parameter	Type	Required	Description
`query`	string	required	Search term for ILOSTAT datasets (e.g. "unemployment", "wages", "child labour", "migration", "working poverty").
`limit`	integer	optional	Number of results to return (1-50, default 20). (default: `20`)

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

import httpx

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

`list_datasets`

List available ILOSTAT datasets, optionally filtered by topic. Browse the full ILOSTAT data catalog. Use this to discover what datasets exist before querying specific data. Args: topic: Optional topic filter keyword. Omit to list all datasets. limit: Maximum datasets to return (1-100, default 50). Returns: List of datasets with id, name, and description.

Parameter	Type	Required	Description
`topic`	any	optional	Optional topic filter (e.g. "employment", "wages", "labour force", "migration"). Omit to list all.
`limit`	integer	optional	Maximum datasets to return (1-100, default 50). (default: `50`)

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

import httpx

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

`get_dataset_structure`

Get the dimension structure of an ILOSTAT dataset. Shows what dimensions (filters) are available for a dataset and their valid values. Use this before get_data to understand what country codes, sex breakdowns, age groups, and other parameters are accepted. Args: dataflow: ILOSTAT dataflow identifier from search_datasets. Returns: List of dimensions with their valid codes/values. Each dimension shows its position in the SDMX key and sample values.

Parameter	Type	Required	Description
`dataflow`	string	required	ILOSTAT dataflow identifier from search_datasets (e.g. "DF_UNE_2EAP_SEX_AGE_RT", "DF_EMP_TEMP_SEX_AGE_NB").

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

import httpx

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

`get_data`

Fetch data from an ILOSTAT dataset. Query any ILOSTAT dataset by country and time period. Covers employment, unemployment, wages, working conditions, labour force participation, child labour, migration, and social protection across 190+ countries worldwide. Args: dataflow: ILOSTAT dataflow identifier. Use search_datasets to find IDs. countries: ISO alpha-2/3 country codes. Omit for all countries. start_period: Start period filter (e.g. "2015"). end_period: End period filter (e.g. "2023"). dimension_filter: Advanced SDMX dimension key. Overrides countries. limit: Maximum observations to return (1-1000, default 200). Returns: Observations with all dimension labels and values.

Parameter	Type	Required	Description
`dataflow`	string	required	ILOSTAT dataflow identifier (e.g. "DF_UNE_2EAP_SEX_AGE_RT"). Use search_datasets to find IDs.
`countries`	any	optional	ISO alpha-2/3 country codes (e.g. ["USA", "DEU", "NOR"]). Omit for all countries.
`start_period`	any	optional	Start period (e.g. "2015", "2020-Q1", "2020-01").
`end_period`	any	optional	End period (e.g. "2023", "2023-Q4", "2023-12").
`dimension_filter`	any	optional	Advanced: SDMX dimension key filter (dot-separated, e.g. "USA.A.UNE_DEAP_RT.SEX_T.YGE15"). Overrides countries param. Use get_dataset_structure to find valid dimension values.
`limit`	integer	optional	Maximum observations to return (1-1000, default 200). (default: `200`)

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

import httpx

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

`compare_countries`

Compare data across countries for a given ILOSTAT dataset. Fetches the same indicator for multiple countries side by side. Useful for cross-country analysis of unemployment rates, wage levels, labour force participation, and other ILO labour statistics. Args: dataflow: ILOSTAT dataflow identifier. country_codes: ISO alpha-2/3 country codes to compare. Maximum 20. start_period: Start period. Omit for most recent data. end_period: End period. Omit for most recent data. Returns: Data grouped by country for easy comparison.

Parameter	Type	Required	Description
`dataflow`	string	required	ILOSTAT dataflow identifier (e.g. "DF_UNE_2EAP_SEX_AGE_RT").
`country_codes`	list[string]	required	ISO alpha-2/3 country codes to compare (e.g. ["USA", "DEU", "JPN", "NOR"]). Maximum 20.
`start_period`	any	optional	Start period (e.g. "2020"). Omit for most recent data.
`end_period`	any	optional	End period (e.g. "2023"). Omit for most recent data.

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ilostat/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'country_codes': '["USA"',
                          'dataflow': 'DF_UNE_2EAP_SEX_AGE_RT'},
            'name': 'compare_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/ilostat/" \
  -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/ilostat/",
    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 search_datasets to find items, then get_dataset_structure 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 ILOSTAT (ILO Labour Statistics) provide?

International Labour Organization statistics — employment, unemployment, wages, working conditions, labour force participation, child labour, and migration data for 190+ countries. It exposes 6 tools: search_datasets, list_datasets, get_dataset_structure, get_data, compare_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 ILOSTAT (ILO Labour Statistics) API return?

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