akshare-mastery

name: AkShare Mastery description: Expert guide for using AkShare to fetch Chinese financial data, covering installation, proxy configuration, resilience patterns, and key interfaces.

AkShare Mastery Skill

AkShare is an open-source financial data interface library for Python, built for human beings! It fetches data from various sources (Eastmoney, Sina, Xueqiu, etc.) primarily via web scraping.

1. Core Philosophy

• Data Source Aggregator: AkShare isn't a data provider itself; it's a collected interface for scraping other providers.
• Dependency: If the upstream source (e.g., Eastmoney) changes its API or blocks IPs, AkShare breaks.
• No Native Proxy Config: It uses standard Python requests. Proxies must be set via standard environment variables.

2. Installation & Mirror

For faster installation in China, use Aliyun mirror:

pip install akshare --upgrade -i https://mirrors.aliyun.com/pypi/simple/

3. Network & Proxy Configuration (Critical)

Since AkShare scrapes websites, it is vulnerable to IP blocking (403 Forbidden / Connection Reset). To use a proxy:

Method A: Environment Variables (Recommended)

Set these before running your script.

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
python main.py

Method B: Python Context (Targeted)

import os
import akshare as ak

# Apply proxy globally for the process just before calling AkShare
os.environ["HTTP_PROXY"] = "http://127.0.0.1:7890"
os.environ["HTTPS_PROXY"] = "http://127.0.0.1:7890"

df = ak.stock_zh_a_spot_em()

4. Key Interfaces (A-Share)

Real-time Quotes

• Spot Data (All Stocks): ak.stock_zh_a_spot_em()
  • Source: Eastmoney
  • Columns: 代码, 名称, 最新价, 涨跌幅, ...
  • Note: High failure rate if IP is dirty.

Historical Data

• Daily K-line: ak.stock_zh_a_hist(symbol="000001", period="daily", start_date="20230101", adjust="qfq")
  • Source: Eastmoney
  • Symbols: "000001" (no prefix usually).

Market Breadth / Northbound

• Northbound Funds: ak.stock_hsgt_fund_flow_summary_em()

5. Resilience Pattern (The "Antigravity" Way)

Never call AkShare directly in production without these wrappers:

1. Timeout Protection: Blocking calls will hang indefinitely if the server holds the connection. Use asyncio.wait_for or func_timeout.
2. Retries: Use tenacity library.
3. Validation: Always check if df.empty.

from tenacity import retry, stop_after_attempt
import akshare as ak

@retry(stop=stop_after_attempt(3))
def safe_fetch_spot():
    df = ak.stock_zh_a_spot_em()
    if df is None or df.empty:
        raise ValueError("Empty response")
    return df

6. Troubleshooting

• Connection Reset / Timeout: 99% chance your IP is blocked by Eastmoney. Switch IP or wait 2-24 hours.
• AttributeError: AkShare updates frequently. Run pip install akshare --upgrade.
• "Zero Data": Check if today is a trading day.