股票篩選
POST/api/v1.0/quote/stock-screen條件選股:組合 N 個篩選條件對全市場標的過濾、排序、分頁,並按指定取值因子返回每隻命中標的的多個列。窩輪篩選請用 warrant-screen;期權篩選請用 option-screen。
請求參數
| 參數 | 類型 | 位置 | 必填 | 説明 |
|---|---|---|---|---|
screen_queries | object[] | 請求體 | 是 | 篩選條件數組,每元素是「11 選 1」的 query 對象——simple_field_query(市場/交易所/指數/北向板塊等枚舉字段 IN 列表)/ plate_query(板塊篩選)/ simple_property_query(行情·估值因子區間)/ cumulative_property_query(累計行情區間,需帶週期)/ financial_property_query(財務因子區間,需帶財報期)/ indicator_positional_query(技術指標位置關係)/ indicator_pattern_query(技術形態)/ featured_property_query(特色因子)/ broker_holdings_query(經紀商持股,僅 HK)/ kline_shape_query(K 線形態)/ option_query(期權指標)。區間用 lower={value, includes} / upper={value, includes},value 已按字段倍率預放大。 最少項數 1; 最多項數 10000 |
retrieve_queries | object[] | 請求體 | 否 | 取值因子數組,每元素是「9 選 1」的 retrieve 對象——basic_property / simple_property / cumulative_property / financial_property / featured_property / indicator_property / broker_property / kline_shape_property / option_property。返回順序與 retrieve_queries 完全對齊。 最多項數 10000 |
sort | object | 請求體 | 否 | 單字段排序(與 sorts 二選一,sorts 優先)。結構 {direction, simple_property:{name}}(也可換成 cumulative_property / financial_property / featured_property)。direction:1=升序,2=降序,3=按絕對值升序,4=按絕對值降序。 |
sorts | object[] | 請求體 | 否 | 排序字段列表,按數組順序分主次。 最多項數 10000 |
next_key | string | 請求體 | 否 | 翻頁遊標,首頁留空。 最長長度 1000; 格式 ^$|^(-?[0-9]+)?$ |
limit | int | 請求體 | 否 | 單頁條數。 ≤ 300; 默認 200 |
watchlist_stock_ids | int[] | 請求體 | 否 | 自選股 stock_id 列表,僅在自選範圍內篩選時傳入。 最多項數 10000 |
holding_stock_ids | int[] | 請求體 | 否 | 持倉 stock_id 列表,僅在持倉範圍內篩選時傳入。 最多項數 10000 |
user_stock_list_mode | int | 請求體 | 否 | 篩選範圍:0 不限制,1 僅自選,2 僅持倉。 取值 0, 1, 2 |
請求示例
bash
curl -X POST "https://webapi.futunn.com/api/v1.0/quote/stock-screen" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AccessToken>" \
-d '{"limit":3,"screen_queries":[{"simple_field_query":{"simple_field":1,"screen_value_list":[1]}}],"retrieve_queries":[{"simple_property":{"name":2201}},{"simple_property":{"name":2301}},{"simple_property":{"name":2303}}],"sort":{"direction":2,"simple_property":{"name":2301}}}' | jq響應字段
| 參數 | 類型 | 説明 |
|---|---|---|
data | object | |
data.items | object[] | |
data.items[].code | string | 標的代碼(含市場前綴),例: HK.00700 |
data.items[].name | string | 標的英文名,例: TENCENT |
data.items[].sc_name | string | 標的簡體中文名,例: 騰訊控股 |
data.items[].tc_name | string | 標的繁體中文名,例: 騰訊控股 |
data.items[].results | object[] | 該標的對應每個 retrieve_queries 因子的取值結果,含 basic_property_result / simple_property_result / financial_property_result 等。res.ival 為整數原始值(含倍率),result_type=2 表示 int。倍率規則: 倍數類(PE/PB/PS/PCF/量比/BETA) ×1e5、價格/漲跌額 ×1000、市值/成交額 ×1000;百分比類(漲跌幅/振幅/換手率/股息率/各類增長率·利潤率·收益率·持股比例等) 一律 ×1e3(即返回值=百分數×1000,÷1e3 還原百分數)。例: [{simple_property_result:{property:{name:2201}, res:{ival:"505000", result_type:2}, value:"505000"}}] |
pagination | object | |
pagination.total | int | |
pagination.has_more | bool | |
pagination.next_key | string |
限制範圍
- 支持市場:HK 港股 / US 美股 / CN A 股 / SG 新加坡 / CA 加拿大 / AU 澳大利亞 / JA 日本 / MY 馬來西亞 / KR 韓國暫不支援。
- 支持品類:正股 / ETF / 指數 / REIT 等可在篩選範圍內的標的;窩輪請用
warrant-screen,期權請用option-screen。 broker_holdings_query/kline_shape_query僅 HK 市場可用;option_query需標的有期權。- 單頁
limit最大 300;next_key為不透明遊標。 - 合法但無命中(過嚴篩選、或傳入不支持的市場等)返回
ret_code=0+data.items=[]+pagination.total=0,空結果集是成功而非錯誤。
錯誤碼
| ret_code | error.code | 觸發條件 | 處理建議 |
|---|---|---|---|
| -3 | invalid_parameter | 缺必填 screen_queries;limit > 300;next_key 非法;user_stock_list_mode 取值不在 {0,1,2} 內;其它字段類型錯誤。 | 校正請求體後重試。 |
| -5 | internal_error | 服務錯誤 | 檢查 query 結構與 property name / market 值的合法性後重試。 |
| -6 | internal_error | 服務錯誤 | 聯繫 技術支援排查。 |
響應示例
json
{
"ret_code": 0,
"ret_msg": "success",
"data": {
"items": [
{
"code": "HK.05432",
"name": "...",
"sc_name": "...",
"tc_name": "...",
"results": []
},
{
"code": "HK.00700",
"name": "TENCENT",
"sc_name": "腾讯控股",
"tc_name": "騰訊控股",
"results": []
}
]
},
"pagination": {
"has_more": true,
"next_key": "3",
"total": 2938
}
}