A-Share Data in Python with the Official SDK

Install

pip install ashareapi            # base: returns list[dict]
pip install "ashareapi[pandas]"  # add DataFrame support (recommended)

• Requires Python 3.9+; the only hard dependency is `requests` — pandas is optional
• Without pandas every method returns `list[dict]` — nothing breaks

Quickstart in 30 seconds (free endpoints need no key)

Five free endpoints: `quote` / `kline` / `hot` / `market_overview` / `changedist` — no signup, no key.

from ashareapi import AShareAPI

cli = AShareAPI()                       # free endpoints need no key
df = cli.quote("sh600667")              # realtime quote -> DataFrame
print(df[["date", "last", "turnover"]])

print(cli.kline("600667.SH", count=5))  # symbol format is forgiving
print(cli.hot(limit=10))                # hot list
print(cli.changedist())                 # advance/decline breadth

Symbol formats: all three work

`cli.quote("600667.SH")` and `cli.quote("sh600667")` are the same call — code migrated from another data source usually works unchanged.

Paid endpoints: pass a key

from ashareapi import AShareAPI

cli = AShareAPI("ct-your-key")           # or set ASHARE_API_KEY
df = cli.screen(preset="low_pe", orderby="ROETTM", limit=10)
print(df.head())

print(cli.fund("sh600667"))              # fund flow + boards + block trades + margin
print(cli.finance("sh600667"))           # three financial statements
print(cli.lhb("institution"))            # top-trader institution board

• Keys come from the [pricing page](https://ashareapi.com/pricing/) (from CNY 9.9)
• 32 endpoints = 32 methods, named 1:1 with the HTTP paths (`/v1/margin-trade` -> `margin_trade()`)
• Full list: [endpoint reference](https://ashareapi.com/endpoints/)

Return types: DataFrame or list?

The SDK converts the object array into a DataFrame (it prefers `structured`, falling back to `data`); table lists (`finance`) and sectioned structures (`shareholder` / `calendar`) are returned as-is (not force-wrapped, which would degrade into a 3x1 table); use `raw=True` for the full envelope.

Error handling: 5 exception types, each actionable

from ashareapi import (AShareAPI, AuthError, RateLimitError,
                       UpstreamError, EmptyResultError)

cli = AShareAPI()
try:
    df = cli.fund("sh600667")
except AuthError as e:          # 401 -> paid endpoint, get a key
    print(e)
except RateLimitError as e:     # 429 -> slow down / solve one PoW / upgrade
    print(e)
except UpstreamError as e:      # upstream fetch failed (failover done, not counted) -> retry once
    print(e)
except EmptyResultError as e:   # no data right now (e.g. no block trades today) -> free, change filters
    print(e)

SDK vs raw HTTP vs Tushare / AkShare

Gotchas and boundaries

• `401` on a paid endpoint -> missing key: only 5 endpoints are free
• `429` -> anonymous limits are low; solve one PoW (`cli.challenge()`) for 60 req/min, or upgrade
• `EmptyResultError` is not a failure: it means "there is genuinely no such data right now" (e.g. no block trades today) — not billed, do not treat it as an outage
• Data dates: holidays do not become "today"; read the `date` field to see which session the data belongs to
• Units: `volume` is in lots (x100 = shares), `amount` in CNY, ratio fields are percentages (`20` = 20%)
• Minute-level K-line is out of scope (daily / weekly / monthly only) — stated plainly