Skip to content

Get Started

A quick guide to install and use QuantDB in minutes.

pip install quantdb

🔧 Install from source

# Clone the repository
git clone https://github.com/franksunye/quantdb.git
cd quantdb

# Install dependencies (optional)
pip install -r requirements.txt

# Install the package in editable mode
pip install -e .

📋 Requirements

  • Python 3.8+
  • OS: Windows, macOS, or Linux
  • Memory: 4GB+ recommended
  • Disk: 1GB+ recommended (for local cache)

🔍 Verify installation

import qdb

# Check version
print(qdb.__version__)

# Basic test
data = qdb.stock_zh_a_hist("000001")
print(data.head())

Import and Initialize

import qdb  # package name: quantdb, import name: qdb

# Optional: specify cache directory
db_dir = "./my_quantdb_cache"
qdb.init(cache_dir=db_dir)

Tip: First call auto-initializes, explicit init is not required.

Basic Usage

import qdb

# 1) Stock history (simplified API)
df = qdb.get_stock_data("000001", days=30)

# 2) Batch fetch
data = qdb.get_multiple_stocks(["000001", "000002", "600000"], days=30)

# 3) Realtime data
rt = qdb.get_realtime_data("000001")

# 4) Stock list (filter by market)
all_stocks = qdb.get_stock_list()

Advanced Usage

# AKShare-compatible interface
df = qdb.stock_zh_a_hist("000001", start_date="20240101", end_date="20240201")

# Cache management
stats = qdb.cache_stats()
print(stats)
qdb.clear_cache()            # clear all
# qdb.clear_cache("000001")   # per-symbol clearing not yet implemented in simplified mode

# Configuration
qdb.set_cache_dir("./qdb_cache")
qdb.set_log_level("INFO")

Note: TTL is managed internally; there are no set_cache_expire / disable_cache / enable_cache functions in this version.

🇭🇰 Hong Kong Index Support

QuantDB now supports Hong Kong stock indexes with international symbol conventions:

# Hong Kong major indexes
hsi_data = qdb.get_index_data('HSI', '20240101', '20240131', 'daily')        # Hang Seng Index
hscei_data = qdb.get_index_data('HSCEI', '20240101', '20240131', 'daily')    # H-shares Index
hstech_data = qdb.get_index_data('HSTECH', '20240101', '20240131', 'daily')  # Hang Seng TECH

# Realtime quotes
hsi_quote = qdb.get_index_realtime('HSI')
print(f"HSI: {hsi_quote['price']} ({hsi_quote['pct_change']:+.2f}%)")

# Symbol aliases also work
hsi_data = qdb.get_index_data('^HSI', '20240101', '20240131', 'daily')       # Bloomberg style
hsi_data = qdb.get_index_data('HANG SENG', '20240101', '20240131', 'daily')  # Full name

# Get all Hong Kong indexes
hk_indexes = qdb.get_index_list(category='香港指数')
print(f"Found {len(hk_indexes)} Hong Kong indexes")

See Hong Kong Index Guide for complete documentation. See API Reference for financial summaries/indicators and more.

Run the examples

The repository includes runnable scripts:

python examples/basic_usage.py
python examples/realtime.py
python examples/stock_list.py
python examples/finance.py
python examples/cache_management.py
python examples/hong_kong_indexes.py    # 🇭🇰 Hong Kong index demo

🚨 Troubleshooting

Dependency conflicts

Use a virtual environment to isolate dependencies:

python -m venv quantdb_env
# Linux/Mac
source quantdb_env/bin/activate
# Windows (PowerShell)
quantdb_env\Scripts\Activate.ps1

pip install quantdb

Slow downloads

If you experience slow downloads due to regional network issues, consider using a closer mirror or a stable network.

📚 What's next