{"slug":"getting-started","title":"Getting Started with WorldOfTaxonomy","description":"API quickstart, MCP setup, authentication, and rate limits for the unified classification knowledge graph.","content_markdown":"## Getting Started with WorldOfTaxonomy\n\n> **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.\n\n---\n\n## Three access points, one knowledge graph\n\n```mermaid\ngraph LR\n  subgraph Graph[\"Knowledge Graph\"]\n    SYS[\"1,000 Systems\"]\n    NODES[\"1.2M+ Nodes\"]\n    EDGES[\"321K+ Edges\"]\n  end\n  subgraph Surfaces[\"Access Points\"]\n    API[\"REST API\\n/api/v1/*\"]\n    MCP[\"MCP Server\\nstdio transport\"]\n    WEB[\"Web App\\nlocalhost:3000\"]\n  end\n  Graph --> API\n  Graph --> MCP\n  Graph --> WEB\n```\n\nPick 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.\n\n## Quick start - REST API\n\nBase URL: `https://worldoftaxonomy.com/api/v1`\n\n### List all classification systems\n\n```bash\ncurl https://worldoftaxonomy.com/api/v1/systems\n```\n\nReturns an array of all systems with their ID, name, region, node count, and provenance metadata.\n\n### Search across all systems\n\n```bash\ncurl \"https://worldoftaxonomy.com/api/v1/search?q=physician\"\n```\n\nFull-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.\n\nAdd `&grouped=true` to group results by system, or `&context=true` to include ancestor paths and children for each match.\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 node with its title, description, level, parent code, and whether it is a leaf node.\n\n### Browse children\n\n```bash\ncurl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/62/children\n```\n\nReturns all direct child codes under a given node. This is how you drill down through a hierarchy.\n\n### Get cross-system equivalences\n\n```bash\ncurl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/6211/equivalences\n```\n\nReturns crosswalk mappings to other systems. NAICS 6211 (\"Offices of Physicians\") maps to ISIC 8620, NACE 86.2, NIC 8620, and others.\n\n### Translate to all systems at once\n\n```bash\ncurl https://worldoftaxonomy.com/api/v1/systems/naics_2022/nodes/6211/translations\n```\n\nReturns equivalences across all connected systems in a single call. One request, every known translation.\n\n## Quick start - MCP server\n\nThe MCP (Model Context Protocol) server lets AI agents query the knowledge graph directly.\n\n### Setup\n\n```bash\npip install world-of-taxonomy\npython -m world_of_taxonomy mcp\n```\n\nTransport: stdio. The server exposes 25 tools and wiki-based resources. It works with Claude, Cursor, VS Code, Windsurf, and any MCP-compatible client.\n\n### Key MCP tools\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| `list_classification_systems` | List all 1,000+ systems | \"What systems cover Germany?\" |\n| `search_classifications` | Full-text search across all nodes | \"Find codes for diabetes\" |\n| `get_industry` | Look up a specific code | \"What is NAICS 5415?\" |\n| `browse_children` | Get child codes | \"Show subcategories of HS chapter 01\" |\n| `get_equivalences` | Get crosswalk mappings | \"What does ICD-10-CM E11 map to?\" |\n| `translate_code` | Translate a code to another system | \"Convert SOC 29-1211 to ISCO\" |\n| `translate_across_all_systems` | Translate to all connected systems | \"All equivalents for NAICS 4841\" |\n| `classify_business` | Classify free text into taxonomy codes (returns `domain_matches` + `standard_matches`) | \"Classify: mobile app for pet sitting\" |\n| `get_audit_report` | Data provenance and quality audit | \"Show provenance breakdown\" |\n| `get_country_taxonomy_profile` | Systems applicable to a country | \"What systems apply in Brazil?\" |\n\n### MCP resources\n\nThe server also provides resources that AI agents can read for deeper context:\n\n- `taxonomy://systems` - JSON list of all classification systems\n- `taxonomy://stats` - Knowledge graph statistics\n- `taxonomy://wiki/{slug}` - Individual guide pages as markdown\n\n## Authentication\n\n### Registration\n\n```bash\ncurl -X POST https://worldoftaxonomy.com/api/v1/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"you@example.com\", \"password\": \"your-password\"}'\n```\n\n### API keys\n\nAfter registration, create an API key:\n\n```bash\ncurl -X POST https://worldoftaxonomy.com/api/v1/auth/keys \\\n  -H \"Authorization: Bearer <your-jwt-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"My App\"}'\n```\n\nAPI keys use the format `wot_` followed by 32 hex characters. Pass them in the Authorization header:\n\n```\nAuthorization: Bearer wot_your_key_here\n```\n\n## Rate limits\n\n| Tier | Requests/Minute | Daily Limit | Best for |\n|------|-----------------|-------------|----------|\n| Anonymous | 30 | Unlimited | Quick exploration |\n| Free (authenticated) | 1,000 | Unlimited | Development and prototyping |\n| Pro | 5,000 | 100,000 | Production applications |\n| Enterprise | 50,000 | Unlimited | High-volume integrations |\n\n## API request flow\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 JWT 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## API endpoints reference\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/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` + `standard_matches` (see [domain-vs-standard](/guide/domain-vs-standard)) |\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## Data disclaimer\n\nAll 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.\n"}