Stock screening (factor / label / ranking / strategy / event) API
Screen the market — five modes selected by mode (default condition). condition: a factor expression, e.g. intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15]), or one of 22 presets. label: by attribute tag — central SOEs / SOEs / private / QFII, ST / delisting / broken IPO, below-book, loss-making, cash-flow structure, listing age, market-cap band … (108 tags); asset=etf switches to ETF theme pools. ranking: whole-market ranking by metric — composite / capital / fundamentals / risk / technical scores, margin balance and its daily-weekly-monthly-quarterly-yearly change, main and retail fund flows, northbound activity, limit-up streak … (type picks the metric, default CompScore). strategy: technical and style strategies — MACD golden cross, KDJ golden cross, break above the 250-day line, first limit-up, consecutive limit-ups, high dividend, high-ROE value, master strategies (Buffett / Graham / Fisher …) — 98 strategies. event: event-driven — dividend plan/resolution/implementation/ex-date, earnings pre-announcement/express/release, private placement before and after listing, management changes and insider trading, block trades, lockup releases … (42 events). ⭐ Not sure which values exist? Set list=true to get the full list with Chinese names and groups; you may pass type as a group filter when listing. Do not guess the type value. ⚠️ If the source rejects your type value, the response is ok:false + reason:"invalid_param" + hint (carrying the source's own message and the ?mode=xxx&list=true pointer) — retrying will not help, just use a valid value. data is a formatted table; read structured for the first table — some queries return several sections, so use tables for all of them. ⭐ Risk flags (ST / delisting period): results carry an extra trailing column 风险标记 (- / ST / 退市整理), and every structured / tables row also carries isST (boolean) / isDelisting (boolean) / status (normal / ST / delisting). Useful because factor sorts such as low PE / low PB put delisting-period and ST names at the top (measured: preset=low_pe returns 萃华退 first) — the column lets you exclude them yourself. ⛔ We never filter implicitly — flags are provided, the decision is yours, otherwise your backtests cannot be reproduced. ⚠️ Suspensions are not flagged: the source has no suspension dimension, and "change = 0" cannot be used to infer it (normal stocks hit 0 too), so we flag nothing rather than flag wrongly. Fetch size: mode=condition has no 200 cap on limit — one call with limit=9999 returned the whole market (5,000+ rows, ~1.6 MB, 1-2 s), still billed as a single request. ⚠️ condition does not support offset paging — fetch everything in one call instead of looping. Other modes (label/ranking/strategy/event) are capped at 200 per page and page via offset.
GET /v1/screenGET /v1/screen?filters=pe_ttm%3A0..20%2Croe_ttm%3A%3E%3D15curl "https://api.ashareapi.com/v1/screen?filters=pe_ttm%3A0..20%2Croe_ttm%3A%3E%3D15&key=YOUR_KEY"mode · filters · sort · board · metric · preset · pool · strategy · event · limit · offset · date · start · end · asset · list · slim* = requiredQuick start
Replace the key below with yours (free endpoints need no key):
# 注:filters 的值已做 URL 编码(浏览器 / curl 会自动还原,照抄即可)
# 推荐:Authorization 头(密钥不进日志)
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.ashareapi.com/v1/screen?filters=pe_ttm%3A0..20%2Croe_ttm%3A%3E%3D15"
# 快速测试:直接浏览器打开(?key= 会留在日志/历史里,别用于生产)
curl "https://api.ashareapi.com/v1/screen?filters=pe_ttm%3A0..20%2Croe_ttm%3A%3E%3D15&key=YOUR_KEY"import requests
r = requests.get(
"https://api.ashareapi.com/v1/screen",
headers={"Authorization": "Bearer YOUR_KEY"},
params={},
timeout=30,
)
print(r.json())const r = await fetch("https://api.ashareapi.com/v1/screen?filters=pe_ttm%3A0..20%2Croe_ttm%3A%3E%3D15", {
headers: { Authorization: "Bearer YOUR_KEY" },
});
console.log(await r.json());Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| mode | string | No | filter factor screening (default) / pool theme pools / rank whole-market ranking / strategy strategies / event corporate events |
| filters | string | No | [filter] Screening conditions, comma = AND: pe_ttm:0..20,roe_ttm:>=15. Ranges 0..20 (inclusive); comparisons >=15 / <=30 / >0 / <0 / =5; 94 available fields, see list=fields |
| sort | string | No | Sort field (semantic name, see list=fields); descending by default, prefix - for ascending: sort=roe_ttm / sort=-roe_ttm |
| board | string | No | Stock pool: hs300 / zz500 / zz1000 / sse50 / sz_component; blank = whole market |
| metric | string | No | [rank] Ranking metric: overall / capital / fundamental / risk / technical (default overall) |
| preset | string | No | [filter] Official preset name (mutually exclusive with filters): low_pe / high_dividend … 22 in total; see list=presets |
| pool | string | No | [pool] Theme pool / attribute tag — a Chinese name or a code both work (e.g. 央企 / shareholder_central_state); see list=pools for the catalogue |
| strategy | string | No | [strategy] Strategy — a Chinese name or a code both work (e.g. 高股息 / high_dividend); see list=strategies for the catalogue |
| event | string | No | [event] Event — a Chinese name or a code both work (e.g. 分红预案公告后一月 / dividend_plan); see list=events for the catalogue |
| limit | integer | No | Number of rows, default 20. filter mode has no cap (pass 9999 to fetch the whole market in one call — measured 5,000+ rows); other modes cap at 200 per page |
| offset | integer | No | Skip the first N rows (paging). filter mode supports it too — we fetch the full set and slice offset:offset+limit, so rows are dropped but values never change; other modes pass it to the data source |
| date | string | No | Query date YYYY-MM-DD (blank = latest trading day); in filter mode this is a historical cross-section |
| start | string | No | [pool/strategy] Range start date YYYY-MM-DD (pair with end) |
| end | string | No | [pool/strategy] Range end date YYYY-MM-DD (pair with start) |
| asset | string | No | Asset class: stock (default) / etf — pool/rank only; filter and strategy are stocks only |
| list | string | No | true = list every available value for that mode (with Chinese names and groups) |
| slim | boolean | No | Slim response: true drops tables when it is a verbatim duplicate of structured (single-table output, ~42% smaller); multi-table output (calendar / macro) is unaffected |
modestringfiltersstringsortstringboardstringmetricstringpresetstringpoolstringstrategystringeventstringlimitintegeroffsetintegerdatestringstartstringendstringassetstringliststringslimbooleanResponse fields
The table below is captured from real API calls (not inferred): each row gives the field name, its type and one real sample value, so you can align your parser.
structuredEnvelope: ok / endpoint / tier / elapsed_ms / source / trace_idProbed: 2026-11-09| Field | Type | Real sample value |
|---|---|---|
| code | str | sz000809 |
| name | str | 和展能源 |
| PE_TTM | str | 57192.71 |
| ClosePrice | str | 2.95 |
| ChangePCT | str | -1.01 |
| isST | bool | false |
| isDelisting | bool | false |
| status | str | normal |
Response example
Sample: GET /v1/screen?expr=intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15])&limit=3 (real response, 2026-09-26, truncated). ⚠️ Note data is a Markdown table string, not an array — read structured or tables from code.
{
"ok": true,
"endpoint": "screen",
"tier": "unlimited",
"elapsed_ms": 2430,
"source": "multi",
"data": "| code | name | PE_TTM | ROETTM | ClosePrice | ChangePCT |\n| --- | --- | --- | --- | --- | --- |\n| sz000656 | 金科股份 | 0.35 | 883.0546 | 1.23 | -2.38 |\n| … |",
"structured": [
{ "code": "sz000656", "name": "金科股份", "PE_TTM": "0.35",
"ROETTM": "883.0546", "ClosePrice": "1.23", "ChangePCT": "-2.38" },
{ "code": "sh600841", "name": "动力新科", "PE_TTM": "2.40",
"ROETTM": "50.3702", "ClosePrice": "5.63", "ChangePCT": "-1.57" }
],
"tables": [ [ /* same content as structured, as a table array */ ] ]
}Unified envelope: { ok, endpoint, tier, elapsed_ms, source, data }
Rows live in data; when upstream returns nothing you get ok:false and the call is not counted.
Free endpoints need no key (anonymous 5/min — 250 bars per request, 100k rows per day; solve one PoW challenge for 15/min). Paid tiers: Trial 30 · Standard 120 · Pro 300 · Unlimited 600 per minute; buyout packs are capped by total calls and never expire.
See the error code table →FAQ
data a Markdown table string?So you can paste the result straight into an LLM. data is Markdown table text; for code, read the sibling structured (array of objects) or tables (array of tables) — all three carry identical content.
Combine conditions with intersect([...]), e.g. intersect([PE_TTM > 0, PE_TTM < 20, ROETTM > 15]). You can also use a preset such as LowPE. limit defaults to 20. The returned columns are determined by the factors you put in expr.
/v1/screen free? Is there a free alternative?It is a paid endpoint. A call without a key returns {"error":"需要 API Key(此端点属付费层)"}. Free alternatives: /v1/changedist (advance/decline distribution), /v1/hot (hot list) and /v1/market-overview.
Whatever your expression asks for — factors in expr become the returned columns. For the sample expression: code / name / PE_TTM / ROETTM / ClosePrice / ChangePCT.
General (applies to every endpoint)
Free endpoints do not: health, challenge, quote, kline, hot, market-overview and changedist work anonymously. Paid endpoints do: send Authorization: Bearer <your key>. ⚠️ The anonymous allowance is tiered by caller type: browsers (humans) get 5/min; scripts, SDKs and AI Agents (curl, requests, axios, openai user-agent strings) get 2/min — automated traffic is easier to abuse. Solving one PoW challenge (GET /v1/challenge, then send the X-PoW header) raises it to 15/min regardless of type. ⚠️ Also, anonymous calls are capped at 250 bars per request and 100k rows per day — use an API key for the full 1212 bars or unlimited daily volume.
No. When the upstream fails or returns nothing you get ok:false and the charge for that call is refunded (total_calls / usage_log / ep_log are rolled back together). Only calls that actually returned data count.
Quotes (quote / kline / orderbook / changedist) are real-time or current session; financials, shareholders, dividends and events are within T+1 of source disclosure. Every response carries its own data timestamp — time (HHMM) on intraday bars, date (trading day) on quotes — so you can check exactly which moment a payload reflects.
No. code is a single-value parameter — one stock per call. For batches, issue concurrent calls and respect your tier per-minute limit.
Set up MCP once, then just ask the AI — it calls the endpoint itself. MCP exposes 92 tools covering quotes, financials, screening, sectors and macro.
Related endpoints
Set up MCP once, then just ask the AI — it calls the endpoint itself.