Getting Started with WorldOfTaxonomy

Getting Started with WorldOfTaxonomy

TL;DR: Three ways to query 1,000+ classification systems, 1.2M+ codes, and 321K+ crosswalk edges - REST API, MCP server for AI agents, and a web app. All open source, all free to start.

Three access points, one knowledge graph

graph LR
  subgraph Graph["Knowledge Graph"]
    SYS["1,000 Systems"]
    NODES["1.2M+ Nodes"]
    EDGES["321K+ Edges"]
  end
  subgraph Surfaces["Access Points"]
    API["REST API\n/api/v1/*"]
    MCP["MCP Server\nstdio transport"]
    WEB["Web App\nlocalhost:3000"]
  end
  Graph --> API
  Graph --> MCP
  Graph --> WEB

Pick whichever fits your workflow. The API is for application integrations and scripts. The MCP server gives AI agents direct tool access. The web app is for visual exploration.

Quick start - REST API

Base URL: https://worldoftaxonomy.com/api/v1

List all classification systems

curl https://worldoftaxonomy.com/api/v1/systems

Returns an array of all systems with their ID, name, region, node count, and provenance metadata.

Search across all systems

curl "https://worldoftaxonomy.com/api/v1/search?q=physician"

Full-text search across all 1.2M+ nodes. A search for "physician" returns matches from SOC, ISCO, ESCO, NAICS, ICD-10-CM, and dozens more systems in a single call.

Add &grouped=true to group results by system, or &context=true to include ancestor paths and children for each match.

Look up a specific code

curl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/6211

Returns the node with its title, description, level, parent code, and whether it is a leaf node.

Browse children

curl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/62/children

Returns all direct child codes under a given node. This is how you drill down through a hierarchy.

Get cross-system equivalences

curl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/6211/equivalences

Returns crosswalk mappings to other systems. NAICS 6211 ("Offices of Physicians") maps to ISIC 8620, NACE 86.2, NIC 8620, and others.

Translate to all systems at once

curl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/6211/translations

Returns equivalences across all connected systems in a single call. One request, every known translation.

Quick start - MCP server

The MCP (Model Context Protocol) server lets AI agents query the knowledge graph directly.

Setup

pip install world-of-taxonomy
python -m world_of_taxonomy mcp

Transport: stdio. The server exposes 25 tools and wiki-based resources. It works with Claude, Cursor, VS Code, Windsurf, and any MCP-compatible client.

Key MCP tools

MCP resources

The server also provides resources that AI agents can read for deeper context:

• taxonomy://systems - JSON list of all classification systems
• taxonomy://stats - Knowledge graph statistics
• taxonomy://wiki/{slug} - Individual guide pages as markdown

Authentication

Registration

curl -X POST https://worldoftaxonomy.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

API keys

After registration, create an API key:

curl -X POST https://worldoftaxonomy.com/api/v1/auth/keys \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}'

API keys use the format wot_ followed by 32 hex characters. Pass them in the Authorization header:

Authorization: Bearer wot_your_key_here

Rate limits

API request flow

sequenceDiagram
    participant C as Your App
    participant RL as Rate Limiter
    participant AUTH as Auth Layer
    participant Q as Query Layer
    participant DB as PostgreSQL

    C->>RL: GET /api/v1/search?q=physician
    RL->>RL: Check tier limit
    RL->>AUTH: Forward
    AUTH->>AUTH: Validate JWT or API key
    AUTH->>Q: Authenticated request
    Q->>DB: Full-text search
    DB-->>Q: Matching nodes
    Q-->>C: JSON response

API endpoints reference

Systems

Nodes

Search

Crosswalks

Classification

Countries

Data disclaimer

All classification data in WorldOfTaxonomy is provided for informational purposes only. It should not be used as a substitute for official government or standards body publications. Always verify codes against the authoritative source for regulatory, legal, or compliance purposes.