Tutorial: ESCO (Skills & Occupations)

Economics

Data source: ESCO API (European Commission)

Overview

ESCO (Skills & Occupations) wraps ESCO API (European Commission), 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-esco": {
      "url": "https://context.gnist.ai/mcp/esco/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`esco_search_skills`

Search the European skills classification (ESCO). ESCO is the EU's multilingual classification of Skills, Competences, Qualifications and Occupations. It covers 13,890 skills and 3,008 occupations with labels in 28 languages. Use this tool to find skills by keyword. Returns skill URIs that can be passed to esco_get_skill for full details including related occupations. Args: query: Search terms for skills. language: Language code for results (default: en). limit: Maximum results (1-50, default: 10). Returns: List of matching skills with URI and title, plus total count.

Parameter	Type	Required	Description
`query`	string	required	Search query (e.g. "python programming", "data analysis", "project management").
`language`	string	optional	Language code for results (en, no, de, fr, etc.). (default: `en`)
`limit`	integer	optional	Maximum results to return (1-50). (default: `10`)

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

import httpx

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

`esco_search_occupations`

Search the European occupation classification (ESCO). Find occupations by keyword. Each occupation is linked to ISCO-08 codes and has associated essential and optional skills. Returns URIs that can be passed to esco_get_occupation or esco_get_occupation_skills. Args: query: Search terms for occupations. language: Language code for results (default: en). limit: Maximum results (1-50, default: 10). Returns: List of matching occupations with URI and title, plus total count.

Parameter	Type	Required	Description
`query`	string	required	Search query (e.g. "software developer", "nurse", "electrician").
`language`	string	optional	Language code for results. (default: `en`)
`limit`	integer	optional	Maximum results to return (1-50). (default: `10`)

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

import httpx

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

`esco_get_skill`

Get detailed information about an ESCO skill. Returns the skill description, alternative labels, broader/narrower skills in the hierarchy, and which occupations require this skill (essential vs optional). Args: uri: ESCO skill URI (e.g. "http://data.europa.eu/esco/skill/..."). language: Language code (default: en). Returns: Skill details including description, related skills, and linked occupations.

Parameter	Type	Required	Description
`uri`	string	required	ESCO skill URI (from search results).
`language`	string	optional	Language code. (default: `en`)

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

import httpx

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

`esco_get_occupation`

Get detailed information about an ESCO occupation. Returns the occupation description, ISCO-08 code, alternative labels, and lists of essential and optional skills required for the role. Args: uri: ESCO occupation URI (e.g. "http://data.europa.eu/esco/occupation/..."). language: Language code (default: en). Returns: Occupation details including description, ISCO code, and skill requirements.

Parameter	Type	Required	Description
`uri`	string	required	ESCO occupation URI (from search results).
`language`	string	optional	Language code. (default: `en`)

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

import httpx

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

`esco_get_occupation_skills`

List all skills required for an ESCO occupation. Returns the complete skill profile split into essential skills (must-have) and optional skills (nice-to-have), with totals. Useful for job matching, training gap analysis, and curriculum design. Args: uri: ESCO occupation URI. language: Language code (default: en). Returns: Essential and optional skill lists with counts.

Parameter	Type	Required	Description
`uri`	string	required	ESCO occupation URI.
`language`	string	optional	Language code. (default: `en`)

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/esco/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'uri': 'example'},
            'name': 'esco_get_occupation_skills'}},
)
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/esco/" \
  -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/esco/",
    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 esco_search_skills to find items, then esco_get_skill 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 ESCO (Skills & Occupations) provide?

European skills, competences, and occupations classification — 13,890 skills and 3,008 occupations linked to ISCO-08 codes in 28 languages. It exposes 6 tools: esco_search_skills, esco_search_occupations, esco_get_skill, esco_get_occupation, esco_get_occupation_skills, 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 ESCO (Skills & Occupations) API return?

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