tushare

tushare

Turn natural language financial data requests into executable Tushare data workflows.

This is a natural language-oriented financial data research skill.

What this skill is for

Typical scenarios for using this skill:

• Look at the recent trend of a certain stock, index, or ETF
• Check company basic information, valuation, and financial trends
• Do horizontal comparison across multiple targets
• Look at capital flows, northbound capital, the dragon-tiger list, and sector strength
• Sort out announcements, news, research reports, and policy clues
• View macroeconomic data such as CPI / PPI / PMI / social financing / interest rates
• Export CSV / parquet for subsequent analysis or backtesting
• Generate a concise research summary, rather than only spitting out raw field tables

First understand what problem the user wants to solve, then choose interfaces, retrieve data, organize, explain, and deliver.

---

When to use

When the user expresses the following intentions, prioritize using this skill:

Market / trend

• See how XX has been doing recently
• How much has XX risen during this period
• How has performance been so far this year
• Has there been any volume expansion recently
• Has this stock been strong recently

Financials / valuation / company quality

• Look at XX's financial report
• Profit trend in recent quarters
• How is the financial quality
• Is cash flow good
• Is the current valuation considered high
• Help me look at PE / PB / ROE / gross margin

Comparison / ranking / screening

• Which is stronger, XX or YY
• Help me make a horizontal comparison
• Which companies have faster profit growth
• Help me screen for high ROE and low debt
• Give me a top ten ranking

Sectors / indices / themes

• Which sector has been strongest recently
• How have semiconductors been recently
• Why are robots rising
• What are the constituent stocks of the index
• Which themes are hottest

Capital flow / sentiment

• What has capital been buying recently
• Where has northbound capital been flowing recently
• Which sector is attracting the most capital
• Who has the largest main capital inflow
• What are the highlights on the dragon-tiger list

Announcements / news / research reports / policy

• What announcements have there been recently
• Help me sort out XX's announcements
• Have there been any catalysts recently
• How has the news side been recently
• What important policies have there been recently

Macro / cross-market

• How has the macroeconomic environment been recently
• How should we view CPI / PMI recently
• What is the current market style leaning toward
• Is the broader market environment leaning bullish or bearish
• How have Hong Kong stocks / US stocks / US Treasuries been recently

Data export / research preparation

• Export a market data set for me
• Pull the past two years of daily bars into CSV
• Generate a backtestable data table
• Pull a research table for subsequent analysis

---

What this skill is NOT for

This skill is not suitable for:

• Directly give buy/sell advice or act as an investment advisor substitute
• Automatically place orders or execute trades
• Scenarios requiring millisecond-level real-time trading decisions
• The implementation of complex backtesting engines and portfolio optimization systems themselves (that is another engineering project)
• Forcefully fabricate data without Tushare permission/credit support

If data permissions are insufficient, the interface is unavailable, or the time range is unreasonable, clearly state the limitations; do not hard-code.

---

Natural-language trigger guide

Even if the user does not say tushare、financials、macro these terms at all, as long as the intent matches the following meanings, this skill should also be triggered.

Common colloquial triggers

• See how this stock has been doing recently
• Give me a quick study of XX
• What is the situation now with that stock mentioned last time
• Help me look at the financial report
• Which sector has been strongest recently
• What have northbound funds been buying recently
• What catalytic news is there
• Is this company worth focusing on
• Pull a dataset for me
• Export to CSV
• Help me screen a batch of stocks
• Compare these companies

Chinese natural language priority principle

When the user speaks plainly, first understand the task; do not first go back to interface names and field names. Prioritize interpreting:

• "recently" as a reasonable time window
• "financial report" as the most recent 8 quarters / most recent fiscal year
• "strong or not" as trend + relative strength + activity
• "capital attention" as net inflow, active trading, dragon-tiger list/northbound and other available measures

If the task has multiple reasonable interpretations, then do minimal clarification.

---

Environment check

Before actually requesting data, do pre-checks first:

1. Check whether Python is available, version requirement 3.7+
2. Check whether the tushare package is installed·
3. Check whether TUSHARE_TOKEN and TUSHARE_PROXY_URL exist.
4. When necessary, do a lightweight interface smoke test (such as trading calendar / basic interfaces)
5. If the user requests a high-permission interface, warn in advance that there may be credit/permission limits

If the token is missing, directly indicate the shortest repair path, for example:

export TUSHARE_TOKEN=your_token
export TUSHARE_PROXY_URL=https://your-proxy-host/dataapi

After initializing pro , add the setting:

pro._DataApi__http_url = os.getenv("TUSHARE_PROXY_URL", "")

Do not wait until the main query fails before exposing environment problems.

---

Intent taxonomy

First identify the task type, then decide the interface combination.

1. Market data / trend

Typical questions:

• How has the trend been recently
• How much has it risen this year
• Has volatility been high recently
• Has there been any volume surge recently

Commonly used interfaces:

• daily
• pro_bar
• weekly
• monthly
• stk_mins
• rt_k / rt_min(if a real-time measure is truly needed and permissions allow)
• daily_basic

2. Basic information / instrument identification

Typical questions:

• What company / what index / what fund is this
• Is it on ChiNext / is it ST / when did it list

Commonly used interfaces:

• stock_basic
• fund_basic
• index_basic
• stock_company
• stock_st / st

3. Financials / company quality

Typical questions:

• Profit trend over the last few quarters
• Revenue and net profit trend over the last few quarters
• How is the financial quality
• How are ROE / gross margin / cash flow

Commonly used interfaces:

• income(revenue / net profit trend takes priority)
• fina_indicator(Supplementary quality metrics such as ROE / gross margin / net margin)
• balancesheet
• cashflow
• forecast
• express
• disclosure_date

4. Valuation / fundamental indicators

Typical questions:

• Is the current valuation high
• Which is cheaper
• What are the PE / PB / dividend yield

Commonly used interfaces:

• daily_basic
• fina_indicator

5. Capital flows / market behavior

Typical questions:

• What has Northbound been buying recently
• Main capital flow direction
• Dragon and Tiger List situation

Commonly used interfaces:

• moneyflow
• moneyflow_hsgt
• hsgt_top10
• top_list
• top_inst
• moneyflow_ind_dc
• moneyflow_mkt_dc

6. Sectors / indices / themes

Typical questions:

• Which sector has been strongest recently
• How is industry rotation
• What constituent stocks are in a certain sector

Commonly used interfaces:

• index_basic
• index_daily
• index_classify
• index_member_all
• sw_daily
• ths_index
• ths_member
• dc_index
• dc_member

7. Limit-up trading / sentiment / activity

Typical questions:

• Today's limit-up ladder
• Consecutive limit-up structure
• Failed limit-up rate / sentiment strength

Commonly used interfaces:

• limit_list_d
• limit_step
• kpl_list
• dc_hot
• ths_hot

8. Announcements / news / research reports / policy

Typical questions:

• What announcements or catalysts have there been recently
• What research reports have there been recently
• What has happened recently on the policy front

Commonly used interfaces:

• anns_d
• news
• major_news
• research_report
• npr
• irm_qa_sh
• irm_qa_sz

9. Macro / cross-market

Typical questions:

• CPI / PMI / social financing / M2
• Interest rates and yield curve
• Hong Kong stocks / US stocks / US Treasury data

Commonly used interfaces:

• cn_cpi
• cn_ppi
• cn_pmi
• cn_gdp
• cn_m
• sf_month
• shibor
• shibor_lpr
• us_tycr
• us_daily
• hk_daily
• index_global

10. Export / research preparation

Typical questions:

• Export the market data of a certain security over a period of time
• Generate a data table for backtesting
• Output CSV / parquet

Commonly used interfaces:

• Depends on the upstream task; the core is unified output rules and naming conventions

---

Entity resolution rules

Security resolution

• Prioritize identifying stock names, stock codes, index names, ETF names, and fund names
• For Chinese abbreviations, first try to match standard objects
• If there are duplicate names or multiple interpretations, list the candidates and make minimal clarification
• Security codes are internally unified into a standard format, such as:600519.SH、000001.SZ

Market identification

• By default, interpret as A-shares first, unless the user explicitly mentions Hong Kong stocks / US stocks / funds / bonds / futures
• Indices, ETFs, and individual stocks should be judged separately; do not mix interfaces

Default time values

If the user does not explicitly give a time range, use reasonable defaults:

• "Recent trend" → defaults to the last 20 trading days
• "This period / recently" → defaults to the last 3 months
• "Financial report / performance" → defaults to the last 8 quarters + the most recent annual period
• "How have capital flows been recently" → defaults to the last 5–20 trading days, adjusted according to task granularity
• "How has the macro situation been recently" → defaults to the last 6–12 periods

Default sector classification

If the user only says "sector / industry / concept" but does not specify a classification system:

• For industries, prioritize relatively stable classifications such as Shenwan / CITIC
• For concepts, prioritize thematic classifications such as Tonghuashun / East Money
• If the conclusion depends on differences in specific classifications, clearly state which classification was used

---

Input normalization rules

Normalize before requesting data:

• Dates are unified as YYYYMMDD
• Check start_date <= end_date
• When the user enters a future date, automatically clip it to the nearest available date and notify
• Bare code such as 000001 do not guess blindly; if it can be completed, explain the completion rules; if it cannot be completed, clarify
• For conflicting parameters (such as trade_date and start_date/end_date given at the same time), adjudicate first, do not just pass them through arbitrarily

---

Data retrieval rules

Documentation first

Before writing request code, first confirm:

• Whether the endpoint name is correct
• Required parameters
• Optional parameters
• Return fields
• Quota / rate limits

Do not hard-code field names from memory alone.

Field confirmation

For fields parameters, prioritize using a known field whitelist or endpoint documentation for confirmation. If the user requests a field that does not exist, state this clearly rather than searching blindly.

Default to segmented fetching

Do not pull long-range data all at once. Recommendations:

• Daily / weekly / monthly bars: slice by year or quarter
• Financial statements: slice by year / reporting period
• Minute data: slice by month / week
• Large batches of multiple symbols: batch by symbol + segment by date

Retries and rate limiting

• Only perform limited retries for transient errors (network jitter, timeouts, 429)
• Do not blindly retry parameter errors, insufficient permissions, or field errors
• Add throttling during batch fetching to avoid hitting rate limits at high frequency

Segment merging

After segmented fetching:

• Merge
• Deduplicate
• Sort by primary key
• Record failed segments
• If partially successful, clearly tell the user which segments failed

---

Output contract

Unless the user explicitly wants only the raw table, prioritize output in this structure:

1. One-sentence conclusion
2. Data range and definitions
3. Key metrics / key tables
4. Anomalies / risk points / interpretation limits
5. If there is local output, provide the file path

Result delivery format

Choose based on task complexity:

• Small results: Markdown summary + brief table
• Medium data tables: CSV
• Large-scale / follow-up analysis: Parquet
• Need a reusable process: attach a Python script
• When visualization is needed: output a PNG chart or explain that a chart can be drawn

Metadata

When generating data files, try to also record:

• Endpoint name
• Request parameters
• Fetch time
• Number of data rows
• Field list
• Whether there are failed segments / missing data

---

Workflow templates

The following templates are the core of this skill. Do not start from the endpoint; start from the task template.

1. Single-symbol market analysis

Applicable:

• Take a look at how XX has been doing recently
• Has this stock been strong recently
• How has it performed year to date

Default process:

1. Parse the symbol
2. Determine the time range
3. Fetch market data + necessary basic indicators
4. Summarize interval returns, trading activity, highs and lows, volatility
5. Output a one-sentence conclusion + key numbers

2. Multi-symbol horizontal comparison

Applicable:

• Who is stronger, XX or YY
• Compare these companies

Default process:

1. Lock the targets
2. Unify the time basis
3. Choose 3–5 key metrics
4. Output a comparison table
5. Give a summary of "who is stronger in which aspect"

3. Financial quality snapshot

Applicable to:

• Take a look at XX's financial report
• Profit trend over the last few quarters
• How is the financial quality

Default process:

1. Pull the core financial data for the last 8 quarters + the most recent fiscal year
2. Distinguish revenue, profit, gross margin, ROE, cash flow
3. Mark improvement / deterioration / fluctuation points
4. Explain cumulative values, single-quarter values, and year-over-year basis

4. Valuation analysis / screening

Applicable to:

• Is the current valuation high
• Which one is cheaper
• Screen for low valuation and high dividend yield

Default process:

1. Clarify the target pool
2. Pull daily_basic and other valuation metrics
3. Link to financial quality when necessary
4. Output ranking, extremes, and basis explanations

5. Capital flow tracking

Applicable to:

• What is capital buying recently
• Where has northbound capital been flowing recently
• Who has the largest main capital inflow

Default process:

1. Clarify the capital scope (northbound / main / dragon-tiger list / sector capital)
2. Determine the time window
3. Pull net inflow / active trading / persistence
4. Link explanation with price performance
5. Avoid describing single-day noise as a trend

6. Sector / theme rotation analysis

Applicable to:

• Which sector is strongest recently
• Where has robotics been strong recently
• What constituent stocks are in a certain concept sector

Default process:

1. Determine the classification basis
2. Pull sector interval performance
3. Link constituent stocks, capital flow, and limit-up tiers when necessary
4. Output the ranking of strong sectors and representative targets

7. Announcements / news / events review

Applicable to:

• What announcements are there recently
• Is there any catalyst
• How is the recent news situation

Default process:

1. Clarify the target and time window
2. Pull announcements / news / research reports / policy data
3. Denoise and extract 3–5 main threads
4. Distinguish facts, announcements, and media interpretation
5. Combine with stock price anomalies for weak causal explanation when necessary

8. Data export and research preparation

Applicable to:

• Pull a CSV
• Make a backtest data table
• Export market/financial data for a certain period

Default process:

1. Clarify data scope, frequency, and fields
2. Use a segmented data retrieval strategy
3. Clean, deduplicate, and unify field types
4. Output CSV / parquet
5. Provide the file path and metadata

9. Comprehensive research brief

Applicable to:

• Give me a quick study of XX
• Make an investor-perspective brief
• First give a panoramic judgment

Default workflow:

1. One-sentence conclusion
2. Market performance
3. Financial trends
4. Valuation level
5. Capital flow situation
6. Announcements / news catalysts
7. Risk points
8. Questions worth further investigation

---

Data quality rules

After the pull is complete, at least perform these checks:

• Schema validation
• Key field existence check
• Primary key deduplication
• Fixed sorting
• Date standardization
• Numeric field type normalization

Empty result handling

An empty table is not necessarily a failure; distinguish:

• Non-trading day
• No data in the range
• Stock not yet listed
• Parameter error
• Insufficient API permissions

Do not call all empty results "the API is broken."

---

Cache and reuse rules

To make the skill reusable over the long term, prioritize supporting:

• Basic table caching (such as stock_basic, trading calendar, index basic information)
• Incremental updates, rather than full re-pulls every time
• Resumable execution for large tasks
• Standardized naming of result files

Recommended naming format:

• daily_600519.SH_20230101_20231231_20260322.csv
• fina_indicator_300750.SZ_20260322.parquet

When there is a cache hit, it is best to indicate which data came from the cache and which was newly pulled.

---

Error handling

Prioritize outputting errors in a "plain language + layered debugging details" manner.

User-visible layer

• Token not configured
• The current API may require higher credits/permissions
• The time range is too large; automatically switched to segmented pulling
• The stock name is not unique; please confirm which one it is
• The current result is empty, possibly because the date is a non-trading day / the target is not listed / there is no permission

Debug layer

Add when necessary:

• API name
• Parameters
• Failed segment
• Original exception text

Partial success principle

If some segments fail, do not say "completed successfully." Should clearly state:

• Which parts succeeded
• Which parts failed
• Whether an incomplete result has been generated

---

Recommended minimal interface set

Do not stuff hundreds of APIs into the main skill body. Prioritize remembering the core API set for the 80% of common tasks:

• stock_basic
• trade_cal
• daily
• pro_bar
• daily_basic
• fina_indicator
• income
• balancesheet
• cashflow
• forecast
• express
• moneyflow
• moneyflow_hsgt
• hsgt_top10
• top_list
• index_basic
• index_daily
• index_classify
• sw_daily
• ths_index
• ths_member
• limit_list_d
• limit_step
• news
• major_news
• research_report
• anns_d
• cn_cpi
• cn_pmi
• us_tycr

For all data APIs, please refer to references/数据接口.md。

---

Best practices

• Understand the task first, then choose APIs
• Fetch as little as possible; core data first, then expand
• Give the conclusion first, then the evidence
• By default, speak plainly and do not pile up field names
• For vague Chinese expressions such as "recent / financial report / strong or not / capital attention," there should be reasonable default interpretations
• For large tasks, give an execution plan first, then start running
• For export tasks, try to retain scripts, metadata, and file paths for easy reuse

---

Examples

Single-stock market data

• Look at CATL's trend over the last three months
• How much has Moutai risen so far this year
• What is the approximate maximum drawdown of China Merchants Bank over the past two years

Financials / valuation

• Look at BYD's revenue and net profit trends over the last 8 quarters
• Is Moutai's current valuation considered high
• Help me find companies with high ROE and low debt

Comparison

• Compare the gains and valuations of Moutai, Wuliangye, and Luzhou Laojiao over the past year
• Compare the performance of the CSI 300, CSI 500, and ChiNext this year

Capital flows / sectors

• Which stocks had the largest northbound capital inflows today
• Which sector has been the strongest recently
• Has the semiconductor sector been strong over the past month

Announcements / events

• Help me sort out Cambricon's recent important announcements
• What news-based catalysts have there been in the robotics sector recently

Macro

• Look at recent changes in CPI, PPI, and PMI
• Is the current market style tilted toward growth or value

Export

• Export the CSI 300 constituent stocks' daily data for the past two years as CSV
• Download CATL's adjusted price data from 2020 to now
• Pull ROE, PE, PB, and revenue growth for the past 3 years into a table

---

Quick rule

When the user says:

• View trends
• Check financial reports
• Compare companies
• View sectors
• View capital flows
• Sort out announcements and news
• View macro
• Pull data and export

Don't first think “what APIs are there.” First think: What kind of task is this? Which data workflow should it follow by default? How should the result be delivered to be truly useful?