{"slug":"getting-started","title":"Getting Started with World Of Taxonomy","description":"API quickstart, MCP setup, authentication, and rate limits for the unified classification knowledge graph.","content_markdown":"## Getting Started with World Of Taxonomy\n\n> **In one sentence:** World Of Taxonomy is a free, open knowledge graph that connects 1,000+ ways of classifying the world (industries, jobs, diseases, products, regulations, places) and lets you translate between them.\n\n---\n\n## What problem does this solve?\n\nSay you run a small bakery in Texas. Depending on who is asking, your business is:\n\n- **NAICS 311811** to the U.S. Census Bureau\n- **ISIC 1071** to the United Nations\n- **NACE 10.71** to anyone selling into Europe\n- **SIC 2051** to an older banking form\n- **HS 1905** when you export your croissants\n- **SOC 51-3011** if you are filing a job posting for a baker\n\nSame bakery. Six different code books. None of them talk to each other.\n\nWorld Of Taxonomy is the bridge. Give it a code in one system, get the equivalent code in every other system that connects to it. Or describe your business in plain English and let it find the codes for you.\n\n## Is this for me?\n\nPick the path that matches you:\n\n| You are... | Start here |\n|-----------|-----------|\n| **A business owner or analyst** who needs to find the right code for a business, product, or job | Try the [Explore page](https://worldoftaxonomy.com/explore) and the **Classify My Business** tool |\n| **A developer** building an app, integration, or data pipeline | Skip to [Quick start: the API](#quick-start-the-api) below |\n| **Using Claude, Cursor, or another AI agent** and want it to look up codes for you | Skip to [Quick start: AI agents (MCP)](#quick-start-ai-agents-mcp) below |\n| **A researcher** comparing classification systems across countries | Browse the [Systems Catalog](/guide/systems-catalog) and the [Crosswalk Map](/guide/crosswalk-map) |\n\nYou do not need an account to explore. You only need to sign in if you want an API key for automated access.\n\n## How the data is organized\n\nThree ideas cover almost everything:\n\n1. **Systems.** A classification system is a single code book, like NAICS 2022 or ICD-10-CM. There are over 1,000 of them in World Of Taxonomy.\n2. **Nodes.** A node is one entry in a code book. NAICS 6211 (\"Offices of Physicians\") is a node. ICD-10-CM E11 (\"Type 2 diabetes mellitus\") is a node. Nodes live in a tree: each one has a parent and may have children.\n3. **Equivalences.** An equivalence (also called a crosswalk) is a link that says \"this code over here means roughly the same thing as this code over there.\" NAICS 6211 has an equivalence to ISIC 8620, NACE 86.2, NIC 8620, and so on.\n\nThat is the whole model. Everything else (search, translate, classify) is built on top of these three.\n\n```mermaid\ngraph LR\n  subgraph Graph[\"The Knowledge Graph\"]\n    SYS[\"1,000+ Systems\"]\n    NODES[\"1.3M+ Nodes\"]\n    EDGES[\"326K+ Equivalences\"]\n  end\n  subgraph Surfaces[\"How you reach it\"]\n    WEB[\"Web App<br/>worldoftaxonomy.com\"]\n    API[\"REST API<br/>for developers\"]\n    MCP[\"MCP Server<br/>for AI agents\"]\n  end\n  Graph --> WEB\n  Graph --> API\n  Graph --> MCP\n```\n\n## Quick start: the web app\n\nNo setup, nothing to install. Just open these in your browser:\n\n- **[Explore](https://worldoftaxonomy.com/explore)** - type a word, see matching codes across every system. Try `physician`, `bakery`, or `solar panel`.\n- **[Systems](https://worldoftaxonomy.com/systems)** - browse the full catalog of code books, filtered by region or category.\n- **[Classify My Business](https://worldoftaxonomy.com/classify)** - describe a business in your own words, get back the most likely codes in each system.\n\nIf you only want to look something up once, the web app is the answer.\n\n## Quick start: the API\n\nUse the API when you want to integrate classification lookups into your own application.\n\nThe base URL is `https://worldoftaxonomy.com/api/v1`. Every endpoint returns JSON. The examples below use `curl`, but any HTTP client works.\n\n### Find a code by searching\n\n```bash\ncurl \"https://worldoftaxonomy.com/api/v1/search?q=physician\"\n```\n\nSearches all 1.3 million nodes at once and returns matches from SOC, ISCO, ESCO, NAICS, ICD-10-CM, and dozens of other systems in a single call.\n\nHelpful query parameters:\n- `&grouped=true` groups results by system, so you see one block per code book\n- `&context=true` adds the ancestor path and child codes for each match, so you can see where it sits in the hierarchy\n\n### Look up a specific code\n\n```bash\ncurl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/6211\n```\n\nReturns the code's title, description, level, parent code, and whether it has any children.\n\n### Walk the tree\n\n```bash\ncurl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/62/children\n```\n\nReturns the direct children of a node. This is how you drill down: start at the top, ask for children, pick one, ask for its children.\n\n### Translate to other systems\n\n```bash\ncurl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/6211/translations\n```\n\nReturns equivalents in every system that has a crosswalk to NAICS 6211. One request, every known translation. For a single pairwise lookup, use `/equivalences` instead of `/translations`.\n\n## Quick start: AI agents (MCP)\n\nIf you use Claude Desktop, Cursor, Zed, VS Code with Continue, Windsurf, or any other client that speaks MCP (Model Context Protocol), you can give your AI agent direct access to the knowledge graph.\n\n**One-line install:**\n\n```bash\npip install world-of-taxonomy\npython -m world_of_taxonomy mcp\n```\n\nThat runs the MCP server over stdio. You point your AI client at it once, and from then on the agent can search, look up codes, translate between systems, and classify free text by itself.\n\nFor client-specific config (Claude Desktop, Cursor, Zed, and others), see the [MCP Setup Guide](/guide/mcp-setup).\n\nThe server exposes 26 tools. The ones you will use most:\n\n| Tool | What it does |\n|------|--------------|\n| `list_classification_systems` | List all 1,000+ systems |\n| `search_classifications` | Full-text search across every node |\n| `get_industry` | Look up one specific code |\n| `browse_children` | Walk the tree |\n| `get_equivalences` | Get crosswalk mappings for a code |\n| `translate_code` | Translate a code into another system |\n| `translate_across_all_systems` | Translate into every connected system |\n| `classify_business` | Turn a free-text description into codes |\n| `get_country_taxonomy_profile` | Which systems apply in a given country |\n| `get_audit_report` | Data provenance and quality breakdown |\n\nIt also exposes MCP resources the agent can read for context:\n- `taxonomy://systems` - JSON list of all systems\n- `taxonomy://stats` - graph statistics\n- `taxonomy://wiki/{slug}` - any guide page (including this one)\n\n## When you need an account\n\nYou only need to sign in if you want an API key. Without one, you get 30 requests per minute (plenty for poking around). With an API key, you get 1,000 per minute and a few extra features.\n\n### Signing in\n\nThere are no passwords. Go to [worldoftaxonomy.com/login](https://worldoftaxonomy.com/login), enter your email, click the one-time link we send. That drops you on the API key dashboard at `/developers/keys`.\n\n### Creating an API key\n\nFrom the dashboard, click \"Generate key\" and copy the raw key right away. We never show it again. Keys look like `wot_` followed by 32 hex characters. Send it in the Authorization header:\n\n```\nAuthorization: Bearer wot_your_key_here\n```\n\nYou can revoke any key from the same dashboard. Revocation takes effect within about two seconds.\n\n### Rate limits at a glance\n\n| Tier | Per minute | Daily | Good for |\n|------|-----------|-------|----------|\n| Anonymous | 30 | unlimited | Exploring |\n| Free (signed in) | 1,000 | unlimited | Building and prototyping |\n| Pro | 5,000 | 100,000 | Production traffic |\n| Enterprise | 50,000 | unlimited | High-volume integrations |\n\n## What happens behind the scenes\n\n```mermaid\nsequenceDiagram\n    participant C as Your app\n    participant RL as Rate limiter\n    participant AUTH as Auth layer\n    participant Q as Query layer\n    participant DB as PostgreSQL\n\n    C->>RL: GET /api/v1/search?q=physician\n    RL->>RL: Check tier limit\n    RL->>AUTH: Forward\n    AUTH->>AUTH: Validate session cookie or API key\n    AUTH->>Q: Authenticated request\n    Q->>DB: Full-text search\n    DB-->>Q: Matching nodes\n    Q-->>C: JSON response\n```\n\n## Full API reference\n\nThe tutorial sections above cover the common cases. Here is the complete endpoint list for when you need it.\n\n### Systems\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /systems` | List all classification systems |\n| `GET /systems/{id}` | System detail with root codes |\n| `GET /systems/stats` | Leaf and total node counts per system |\n| `GET /systems?group_by=region` | Systems grouped by region |\n| `GET /systems?country={code}` | Systems applicable to a country |\n\n### Nodes\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /systems/{id}/nodes/{code}` | Look up a specific code |\n| `GET /systems/{id}/nodes/{code}/children` | Direct children |\n| `GET /systems/{id}/nodes/{code}/ancestors` | Parent chain to root |\n| `GET /systems/{id}/nodes/{code}/siblings` | Sibling codes |\n| `GET /systems/{id}/nodes/{code}/subtree` | Subtree summary stats |\n\n### Search\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /search?q={query}` | Full-text search |\n| `GET /search?q={query}&grouped=true` | Results grouped by system |\n| `GET /search?q={query}&context=true` | Results with ancestor and child context |\n\n### Crosswalks\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /systems/{id}/nodes/{code}/equivalences` | Cross-system mappings |\n| `GET /systems/{id}/nodes/{code}/translations` | Translate to all systems |\n| `GET /equivalences/stats` | Crosswalk statistics |\n| `GET /compare?a={sys}&b={sys}` | Side-by-side sector comparison |\n| `GET /diff?a={sys}&b={sys}` | Codes with no mapping |\n\n### Classification\n\n| Endpoint | Description |\n|----------|-------------|\n| `POST /classify` | Classify free text; returns `domain_matches` plus `standard_matches`. See [domain-vs-standard](/guide/domain-vs-standard) for the difference. |\n\n### Countries\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /countries/stats` | Per-country taxonomy coverage |\n| `GET /countries/{code}` | Full taxonomy profile for a country |\n\n## A note on accuracy\n\nAll data in World Of Taxonomy is provided for informational purposes. It is not a substitute for official government or standards body publications. For regulatory, legal, or compliance work, always verify codes against the authoritative source.\n"}