ticker-classifier is a small Python library for classifying ticker-like symbols (for example AAPL, BTC, EUR, GOLD) into a simple market/category representation. It uses Yahoo Finance for equities, CoinGecko for cryptocurrencies and a few heuristics for currencies/commodities. The output indicates the most likely category, a display name, market cap when available, and a yahoo_lookup value to fetch further data if desired.

• Key Features
• Installation
• Usage
• API
• Development
• Citation
• Contributing
• License

• Classify symbols as Equity, Crypto, Forex, Commodity, Index or Unknown.
• Uses multiple public APIs and simple heuristics to make robust decisions.
• Provides both synchronous and asynchronous APIs.
• Lightweight disk cache to avoid repeated lookups (TickerCache).

Install from pip using the provided requirements.txt or install the package directly from the repository for latest changes:

pip install -r requirements.txt

or

pip install git+https://github.com/StephanAkkerman/ticker-classifier.git

Basic synchronous usage:

from ticker_classifier.classifier import TickerClassifier

classifier = TickerClassifier()
symbols = ["AAPL", "BTC", "EUR", "GOLD", "UNKNOWN123"]
results = classifier.classify(symbols)
for r in results:
    print(r)

Example asynchronous usage:

import asyncio
from ticker_classifier.classifier import TickerClassifier

async def main():
    classifier = TickerClassifier()
    symbols = ["AAPL", "BTC", "ETH", "JPY"]
    results = await classifier.classify_async(symbols)
    for r in results:
        print(r)

asyncio.run(main())

The output for each symbol is a dictionary like:

{'category': 'EQUITY', 'ticker': 'AAPL', 'name': 'Apple Inc.', 'market_cap': 4029017227264, 'yahoo_lookup': 'AAPL', 'alternatives': ['crypto'], 'source': 'api'}
{'category': 'crypto', 'ticker': 'BTC', 'name': 'Bitcoin', 'market_cap': 1736590593460.9607, 'yahoo_lookup': 'BTC-USD', 'alternatives': ['stock'], 'source': 'api'}
{'category': 'crypto', 'ticker': 'ETH', 'name': 'Ethereum', 'market_cap': 338145915081.1455, 'yahoo_lookup': 'ETH-USD', 'alternatives': ['stock'], 'source': 'cache'}
{'category': 'forex', 'ticker': 'JPY', 'name': 'JPY Currency', 'market_cap': None, 'yahoo_lookup': 'JPYUSD=X', 'alternatives': ['stock'], 'source': 'cache'}

Notes

• The classifier caches positive classifications (non-Unknown) in an SQLite database (default ticker_cache.db) for 24 hours by default.
• You can customize the cache filename and expiry by passing db_name and hours_to_expire to TickerClassifier.

• ticker_classifier.classifier.TickerClassifier
• classify(symbols: List[str]) -> List[dict] – synchronous classification.
• classify_async(symbols: List[str]) -> List[dict] – async classification.
• ticker_classifier.apis.yahoo.YahooClient – low-level Yahoo quote fetcher (sync + async helpers).
• ticker_classifier.apis.coingecko.CoinGeckoClient – crypto lookup + market cap helpers (sync + async).
• ticker_classifier.db.cache.TickerCache – tiny SQLite-backed cache used by TickerClassifier.

Run formatting and linting tools you prefer (project uses black code style).

Run a quick smoke check by running the classifier.py module directly:

& .venv\Scripts\python.exe ticker_classifier\classifier.py

If you add tests, run them with your chosen test runner (e.g. pytest).

If you use this project in your research, please cite as follows (adjust metadata accordingly):

@misc{ticker-classifier,
author  = {Stephan Akkerman},
title   = {ticker-classifier},
year    = {2025},
publisher = {GitHub},
howpublished = {\url{https://github.com/StephanAkkerman/ticker-classifier}}
}

Contributions are welcome. Suggested workflow:

1. Fork the repository and create a feature branch.
2. Run tests and format your changes with black.
3. Open a pull request with a clear description of the change.

Please open issues for feature requests or bugs and include a small reproducible example when possible.

This project is licensed under the MIT License. See the LICENSE file for details.