finshare: one Python API over six market data providers

A single import over Eastmoney, Tencent, Sina and BaoStock

finshare is a Python toolkit for fetching financial data, described in the README as a professional financial data fetching toolkit. Its central proposition is that a developer should not have to learn a separate client library for every provider.

The multi-source list is the substance of the project: Eastmoney, Yahoo Finance, Tencent, Sina, Tongdaxin and BaoStock, with the acknowledgements section listing what each one provides. Eastmoney covers A-share quotes, financial data, the dragon-tiger leaderboard and margin financing data. Tencent and Sina cover Hong Kong quotes and real time prices. Tongdaxin supplies quote data, BaoStock supplies securities data, and 天天基金 supplies fund net asset values.

That spread determines who should care. This is a China market library first, with Hong Kong and US coverage through Yahoo Finance. It is not a general purpose market data client, and a team outside that market would use very little of it.

The supported data categories are equally concrete: K-line, real time snapshot, capital flow, dragon-tiger list and margin financing for stocks; net value, information, lists, ETF and LOF for funds; K-line and snapshot for futures; and security lists for stocks, ETFs, LOFs and futures.

Two return shapes: DataFrames for history, objects for snapshots

The API returns two different shapes, and the quick start shows both in under ten lines:

import finshare as fs

# 获取历史K线
df = fs.get_historical_data('000001.SZ', start='2024-01-01', end='2024-12-31')

# 获取实时快照
snapshot = fs.get_snapshot_data('000001.SZ')

# 批量获取快照
snapshots = fs.get_batch_snapshots(['000001.SZ', '600519.SH'])

print(df.head())

History comes back as a pandas DataFrame, which is what you want for anything analytical. A single snapshot comes back as an object with named attributes, since the screener example reads snap.last_price and snap.change_pct. A batch of snapshots comes back as a mapping from code to snapshot, and the price alert example iterates over it with data.items().

The DataFrame column names are visible in the candlestick example, where a kline frame is indexed by trade_date and carries open_price, high_price, low_price and close_price. Those are the names you will write against, and they are snake_case rather than the abbreviated forms used by some provider APIs, which is the point of the normalisation.

The snapshot attribute names are last_price, change_pct, volume, code and name. The screener example also uses stocks['change_pct'], stocks['amount'] and stocks.get('turnover_rate', 0), which tells you the list function returns a DataFrame whose turnover_rate column may be absent, hence the .get with a default.

Installing from PyPI and the first call you can make

Installation is a single pip command:

pip install finshare

The package requires Python 3.8 or newer, and the pyproject.toml declares that floor with classifiers for 3.8 through 3.11. The runtime dependencies are numpy, pandas, baostock, pytdx, pydantic, loguru and requests, with yfinance also listed in the project dependencies for the international side.

The dependency list is itself informative. baostock and pytdx are not generic utilities, they are specific provider clients, which tells you that the failover mechanism is built on top of dedicated per-provider code rather than on raw HTTP calls to a common schema. pydantic suggests the returned snapshot objects are validated models rather than ad hoc namespaces, and loguru is used for the library's own logging.

Note the discrepancy between the dependency sets. The pyproject.toml lists yfinance among the project dependencies, while requirements.txt lists numpy, pandas, baostock, pytdx, pydantic, loguru and requests without it. Anyone pinning an environment by hand from requirements.txt gets a different install than pip install finshare does.

Beyond the package, the README points at an online documentation site that holds the complete API reference, a quick start guide, notes on the data sources, a FAQ and more code examples, and at an examples/ directory in the repository with numbered scripts covering basic usage, batch fetch, batch snapshots, financial data, feature data, async usage, cache usage, Hong Kong stocks, futures, funds and security lists.

Automatic failover is also an outage mask

The feature list claims automatic failover: when a data source fails, the library switches to a backup source. That is genuinely useful, because free public endpoints rate limit, block and change shape without notice.

It also hides something. The README does not describe how failover decides to trigger, so there is no documented guarantee about how it treats data that arrives successfully but looks stale or subtly wrong. The unified format guarantee means a row from one source looks like a row from another, so a silent difference in fields or semantics between providers is hard to notice from the outside. The README states that all sources return a unified format, but it does not describe a per-source provenance field or a way to ask which provider served a given call.

That is the practical caution for anyone using this for research. If a number matters, confirm it against the provider you already trust before publishing it. The screener example makes the same point in miniature: it filters on stocks['amount'] > 1e8 and stocks.get('turnover_rate', 0) > 10, and the.get with a zero default means a missing turnover column silently passes everything.

There is also a scope limit in the acknowledgements. The listed data sources are free API interfaces. Free means unauthenticated and unsponsored, which in practice means no service level, no changelog notice and no commitment to keep the endpoint alive.

Where finshare sits against akshare

The README names akshare as the open source project it referenced for design ideas and API style, describing akshare as a professional financial data open source library that provided important reference. That is the comparison to understand, because both tools exist to remove per-provider plumbing.

The difference in approach is one of scope and packaging. akshare is organised around the breadth of Chinese financial data endpoints it exposes, with each function tied to a specific data source and a specific category of data. finshare takes the opposite shape: a fixed set of unified calls such as get_historical_data, get_snapshot_data, get_batch_snapshots and get_stock_list, each of which can be served by any of several sources, with the provider chosen and failed over internally.

So finshare optimises for a stable interface over a variable source, and akshare optimises for covering more endpoints. If your need is a specific table such as capital flow or the dragon-tiger list and you are willing to bind to one provider, akshare style access may reach further. If you want get_historical_data to keep working when one provider is down, finshare's model fits.

The surrounding ecosystem is also worth noting, since it shows how the library is meant to be used. The related projects table lists finboard for real time quote dashboards, finscreener for screening, finquant for backtesting, finshare-skills for assistant tooling, and meepoquant as a free backtesting platform.

Building on top: a board, a screener, an alert bot and a Flask API

The README frames finshare as more than a database, describing it as a foundation library for quickly building financial tools, and then shows five ways to do that. Each one is short enough to read as a pattern rather than a tutorial.

The dashboard example is a Streamlit app with a Plotly candlestick chart. The interesting part is the metric rendering, which assumes the snapshot object exposes last_price and change_pct:

for code, snap in data.items():
    st.metric(code, snap.last_price, f"{snap.change_pct:.2f}%")

The alert bot example polls get_batch_snapshots on a loop with a sixty second sleep and posts to a DingTalk webhook when a price crosses a threshold. The Flask example exposes two routes, one returning a snapshot as JSON fields and one returning the historical frame converted with to_dict(orient='records'):

@app.route('/kline/<code>')
def get_kline(code):
    df = fs.get_historical_data(code, start='2024-01-01')
    return jsonify(df.to_dict(orient='records'))

The creative ideas table goes further and lists quantitative backtesting, automatic trading, news monitoring, mini programs and an Excel plugin, with the qualifier that it is not just a database but a base library for building financial tools quickly.

Treat that last list as a wish list rather than a feature set. The documented data categories stop at quotes, funds, futures and security lists. Backtesting, auto trading and news monitoring are described as things you could build, and the repository name for the backtesting framework is finquant, not finshare.

MIT terms, a beta classifier and three version numbers

The licence field on the repository says MIT, the README states MIT License with details in the LICENSE file, and the pyproject.toml declares license = {text = "MIT"}. For a library you import into your own code, that is about as permissive as it gets, and it carries no obligation on downstream projects beyond keeping the licence text with substantial portions of the software.

The metadata also classifies the project as Development Status :: 4 - Beta and lists the intended audience as Developers and the Financial and Insurance Industry. The beta label is worth taking at face value for a library whose whole value is data access.

The version numbers do not agree. The pyproject.toml in the repository reports version 1.0.8, while the release list shows 2.1.0 published on 2026-04-27, preceded by v1.1.0 on 2026-03-18 and v1.0.2 on 2026-03-10. The tree therefore carries an older manifest version than the newest tag, which means the manifest in the checkout is not a reliable indicator of what is on PyPI.

On maintenance, the repository is not archived and the last push was on 2026-04-27. That is the most recent activity recorded, and it is the date to use when deciding whether to pin a version and test the upgrade path rather than tracking main.

Editorial conclusion

finshare suits Python developers building research scripts, screeners or dashboards over Chinese and global market data who want one import instead of six provider clients. It does not suit production trading systems, since every upstream is a free public endpoint whose availability and response format the project does not control. Before adopting, run pip install finshare and check that get_historical_data and get_snapshot_data return rows for the codes you care about, read the data source notes in the docs site, and treat the failover behaviour as a mask for upstream outages rather than as a reliability guarantee.

Frequently asked questions

Official sources

1. finvfamily/finshare on GitHub
2. License: MIT
3. Project website
4. README
5. Releases