pysnowball Documentation

Before calling any APIs, you must manually obtain a token from the Xueqiu (雪球) website/app. Use ball.set_token() to provide the token string, which must include both xq_a_token and u. Without this step, API access will be denied.

import pysnowball as ball
ball.set_token("xq_a_token=662745a236*****;u=909119****")

Install the pysnowball package using the standard Python package manager.

pip install pysnowball

After setting the token, you can call various financial data APIs. The following example demonstrates how to fetch cash flow data for a specific stock (e.g., 'SH600000').

import pysnowball as ball
ball.set_token("xq_a_token=662745a236*****;u=909119****")
ball.cash_flow('SH600000')

Use the income() method to retrieve financial data from the income statement for a specific stock symbol. You can filter for annual reports and specify the number of historical records to return.

import pysnowball as ball
ball.income('SZ300251')
# or
ball.income(symbol='SZ300251', is_annals=1, count=10)

Retrieve Northbound shareholding data for the Shenzhen-Hong Kong and Shanghai-Hong Kong Stock Connect.

• northbound_shareholding_sh(date): Retrieves data for the Shanghai-Hong Kong connection. Defaults to the current day if no date is provided. Date format: 'YYYY/MM/DD'.
• northbound_shareholding_sz(date): Retrieves data for the Shenzhen-Hong Kong connection. Defaults to the current day. Date format: 'YYYY/MM/DD'.

Returns a list of objects containing code, name, shareholding, and shareholding_percent.

Use nav_daily(symbol) to retrieve the daily Net Asset Value (NAV) history for a specific combination or index. This is useful for tracking the performance of a custom portfolio (cube) against a benchmark.

Input Parameter:

• symbol: The identifier for the combination or index (e.g., 'ZH2567925').

Output Data Structure: The function returns a list of objects. Each object contains a list of daily data points including:

• time: Timestamp.
• date: Formatted date string.
• value: The NAV value.
• percent: The daily percentage change.

import pysnowball as ball
ball.nav_daily("ZH2567925")

Search for stock codes using a text query (e.g., a company name or ticker fragment).

Returns a JSON object containing a list of matches with code, label, query, state, stock_type, and type.

import pysnowball as ball
ball.suggest_stock("tyzn")

Retrieve historical performance data for a specific index using its index code (e.g., from CSI). You can fetch data for the last 7, 30, or 90 days.

Returns a list of daily data including open, high, low, close, changePct, tradingVol, and tradingValue.

Use the business() method to retrieve data regarding the composition of a company's main business activities. You can specify the number of records to return.

import pysnowball as ball
ball.business('SZ300251')
# or
ball.business(symbol='SZ300251', count=10)

Use ball.indicator(symbol, is_annals, count) to retrieve financial report data by year or quarter.

Parameters:

• symbol: The stock symbol.
• is_annals: If 1, only retrieves annual reports (default). If 0, retrieves quarterly reports.
• count: The number of data points to return (default is 5).

import pysnowball as ball
ball.indicator('SZ002027')
# or
ball.indicator(symbol='SZ002027',is_annals=1,count=10)

Use ball.quotec(symbol) to retrieve basic real-time market data for a specific stock. The returned data includes current price, percentage change, volume, amount, market capitalization, and other key metrics.

import pysnowball as ball
ball.quotec('SZ002027')