Double 11 annual ¥1,699/yrView
Pro endpoint · Pro

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.

ProGET /v1/screen
Signature
GET /v1/screen?filters=pe_ttm%3A0..20%2Croe_ttm%3A%3E%3D15
One-liner
curl "https://api.ashareapi.com/v1/screen?filters=pe_ttm%3A0..20%2Croe_ttm%3A%3E%3D15&key=YOUR_KEY"
Parameters: mode · filters · sort · board · metric · preset · pool · strategy · event · limit · offset · date · start · end · asset · list · slim* = required

Quick start

Replace the key below with yours (free endpoints need no key):

curl
# 注: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"
Python
import requests

r = requests.get(
    "https://api.ashareapi.com/v1/screen",
    headers={"Authorization": "Bearer YOUR_KEY"},
    params={},
    timeout=30,
)
print(r.json())
JavaScript
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

modestring
filter factor screening (default) / pool theme pools / rank whole-market ranking / strategy strategies / event corporate events
filtersstring
[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
sortstring
Sort field (semantic name, see list=fields); descending by default, prefix - for ascending: sort=roe_ttm / sort=-roe_ttm
boardstring
Stock pool: hs300 / zz500 / zz1000 / sse50 / sz_component; blank = whole market
metricstring
[rank] Ranking metric: overall / capital / fundamental / risk / technical (default overall)
presetstring
[filter] Official preset name (mutually exclusive with filters): low_pe / high_dividend … 22 in total; see list=presets
poolstring
[pool] Theme pool / attribute tag — a Chinese name or a code both work (e.g. 央企 / shareholder_central_state); see list=pools for the catalogue
strategystring
[strategy] Strategy — a Chinese name or a code both work (e.g. 高股息 / high_dividend); see list=strategies for the catalogue
eventstring
[event] Event — a Chinese name or a code both work (e.g. 分红预案公告后一月 / dividend_plan); see list=events for the catalogue
limitinteger
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
offsetinteger
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
datestring
Query date YYYY-MM-DD (blank = latest trading day); in filter mode this is a historical cross-section
startstring
[pool/strategy] Range start date YYYY-MM-DD (pair with end)
endstring
[pool/strategy] Range end date YYYY-MM-DD (pair with start)
assetstring
Asset class: stock (default) / etf — pool/rank only; filter and strategy are stocks only
liststring
true = list every available value for that mode (with Chinese names and groups)
slimboolean
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

Response 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.

Located in: structuredEnvelope: ok / endpoint / tier / elapsed_ms / source / trace_idProbed: 2026-11-09
FieldTypeReal sample value
codestrsz000809
namestr和展能源
PE_TTMstr57192.71
ClosePricestr2.95
ChangePCTstr-1.01
isSTboolfalse
isDelistingboolfalse
statusstrnormal

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 */ ] ]
}
Response

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.

Rate limits & quota

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

Why is 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.

How do I write a screening expression?

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.

Is /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.

Which columns come back?

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)

Do these endpoints need an API key?

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.

Am I charged when the upstream returns nothing or errors?

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.

How fresh is the data?

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.

Can I request several stocks in one call?

No. code is a single-value parameter — one stock per call. For batches, issue concurrent calls and respect your tier per-minute limit.

How do I use this from Claude / Cursor / ChatGPT?

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.

Use it from an AI Agent?

Set up MCP once, then just ask the AI — it calls the endpoint itself.

← Back to the full endpoint reference