> ## Documentation Index
> Fetch the complete documentation index at: https://motiontrade.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Taxonomy

> Our hierarchical ontology for market intelligence

## The Taxonomy

Market Motion's taxonomy is a **hierarchical ontology** that organizes all market-relevant information. It's what makes our data machine-readable rather than just searchable.

## Structure

```
Category
└── Subcategory
    └── Entity Type
        └── Entity
            ├── Attributes
            ├── Relationships
            └── Market Exposures
```

## Categories

<Tabs>
  <Tab title="Politics">
    **Subcategories:**

    * `presidential` - Presidential elections and candidates
    * `us-congress` - Senators and Representatives
    * `governors` - State governors
    * `international` - Foreign leaders and elections
    * `legislation` - Bills and policy

    **Entity Types:** person, org

    **Example Entities:**

    * Joe Biden (person)
    * Donald Trump (person)
    * Democratic Party (org)
  </Tab>

  <Tab title="Sports">
    **Subcategories:**

    * `nfl` - National Football League
    * `nba` - National Basketball Association
    * `mlb` - Major League Baseball
    * `nhl` - National Hockey League
    * `soccer` - MLS, international

    **Entity Types:** person, team, place, league

    **Example Entities:**

    * Patrick Mahomes (person)
    * Kansas City Chiefs (team)
    * Arrowhead Stadium (place)
    * NFL (league)
  </Tab>

  <Tab title="Crypto">
    **Subcategories:**

    * `layer-1` - Base layer protocols
    * `defi` - DeFi protocols
    * `memecoins` - Meme tokens
    * `nft` - NFT projects
    * `regulation` - Regulatory events

    **Entity Types:** asset, org, person

    **Example Entities:**

    * Bitcoin (asset)
    * Ethereum (asset)
    * Coinbase (org)
  </Tab>

  <Tab title="Finance">
    **Subcategories:**

    * `fed` - Federal Reserve
    * `macro` - Macroeconomic indicators
    * `equities` - Stock markets
    * `earnings` - Company earnings

    **Entity Types:** org, person, asset

    **Example Entities:**

    * Federal Reserve (org)
    * Jerome Powell (person)
    * S\&P 500 (asset)
  </Tab>
</Tabs>

## Why a Taxonomy?

### vs. Raw Text

| Raw Text                                  | Taxonomy                                           |
| ----------------------------------------- | -------------------------------------------------- |
| "Patrick Mahomes questionable for Sunday" | `entity.attributes.injury_status = "questionable"` |
| Requires NLP to extract                   | Directly queryable                                 |
| Ambiguous meanings                        | Typed values                                       |
| No relationships                          | Explicit graph                                     |

### vs. Keyword Tags

| Keyword Tags                      | Taxonomy                                           |
| --------------------------------- | -------------------------------------------------- |
| \["nfl", "chiefs", "quarterback"] | `category: sports, subcategory: nfl, type: person` |
| Flat structure                    | Hierarchical                                       |
| No semantics                      | Typed relationships                                |
| No inference                      | Traversable graph                                  |

## Taxonomy API

### Get Subcategories

```bash theme={null}
GET /api/entities/subcategories
```

Returns:

```json theme={null}
{
  "categories": [
    {
      "category": "sports",
      "count": 450,
      "subcategories": [
        { "name": "nfl", "count": 200 },
        { "name": "nba", "count": 150 }
      ]
    }
  ]
}
```

### Filter by Taxonomy

```bash theme={null}
# All NFL players
GET /api/entities?category=sports&subcategory=nfl&type=person

# All crypto assets
GET /api/entities?category=crypto&type=asset

# All political organizations
GET /api/entities?category=politics&type=org
```

## Building on the Taxonomy

### Portfolio by Category

```javascript theme={null}
// Get all entities you're exposed to by category
const sports = await fetch('/api/entities?category=sports&limit=100');
const politics = await fetch('/api/entities?category=politics&limit=100');

// Count market exposures per category
const sportsExposure = sports.entities.reduce(
  (sum, e) => sum + e.marketExposures?.length || 0, 0
);
```

### Category Alerts

```javascript theme={null}
// Monitor all entities in a category for attribute changes
const politicians = await fetch('/api/entities?category=politics&type=person');

for (const pol of politicians.entities) {
  if (pol.attributes.approval_rating < 40) {
    console.log(`Low approval: ${pol.displayName}`);
    // Check connected markets
  }
}
```

## Extending the Taxonomy

The taxonomy grows as we add coverage:

<Steps>
  <Step title="New Category">
    Weather, Entertainment, Science
  </Step>

  <Step title="New Subcategory">
    Premier League under Sports
  </Step>

  <Step title="New Entity Type">
    Event type for conferences, games
  </Step>

  <Step title="New Attributes">
    Domain-specific attributes per subcategory
  </Step>
</Steps>

<Note>
  Have a category or entity type you need? Let us know on GitHub.
</Note>