# 篩選正股
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_stock_screen(request)
介紹
條件選股 V2。相比舊接口 get_stock_filter，因子覆蓋更廣（11 類共 244+ 個因子），數值統一傳原始值（OpenD 自動倍率轉換），支持單字段或多字段排序、顯式聲明取回屬性，結果按
value_type分別填入sval/ival/aval/dval。參數
參數 類型 說明 request StockScreenRequest 條件選股請求對象，通過 builder 方式構建 StockScreenRequest 字段：
字段 類型 說明 page_from int 分頁起始位置 不傳默認為 0page_count int 單頁最大返回數 不傳默認為 200篩選條件 builder 方法（每次調用追加一條篩選條件，所有數值字段直接傳原始值，OpenD 自動倍率轉換）：
方法 說明 add_simple_field(field, values) 市場 / 交易所 / 指數 / 自選股等枚舉字段篩選 field 取自 SimpleField；values 為枚舉值列表（OR 關係）。ScrMarket.MY / JP / SG 後續支持，目前結果為空add_plate(plate_ids, parent_plate_id=None) 板塊篩選 plate_ids 形如 ["BK1001"]add_simple_property(name, lower=None, upper=None) 簡單行情屬性區間篩選 name 取自 SimpleProperty（最新價、市值、PE、量比等）；lower / upper 直接傳原始值，如最新價 10 元傳 10、市值 ≥ 100 億傳 10_000_000_000add_cumulative_property(name, days=1, lower=None, upper=None) 累計行情屬性 name 取自 CumulativeProperty；days 用於 N 日累計。漲跌幅類（如 PRICE_CHANGE_PCT）傳值為小數（5% 傳 0.05，非 5.0）add_financial_property(name, term=None, year=None, lower=None, upper=None, ...) 財務屬性 name 取自 FinancialProperty；term 取自 Term 枚舉（Q1=1、年報=100、最新單季=10 等）。Term.SURPRISE_LATEST 系列（200~204）實測 HK/US 均會返回數值，但當前數據通常與 ANNUAL 相同，慎用add_indicator_positional(first_indicator_name, period_type, position, second_indicator=None, ...) 技術指標位置關係 如 MA5 上穿 MA20。指標名/週期/位置取自 Indicator / Period / Positionadd_indicator_pattern(name, period_type, ...) 技術指標形態（金叉、死叉、背離等） name 取自 Patternadd_featured_property(name, intervals=None, value_set=None, period=None, range_period=None, first_custom_param=None) 特色指標（籌碼、熱度、分析師評級、資金流等） add_broker_holdings(name, days=None, param=None, intervals=None) 經紀商持股因子 僅港股。經紀商因子 6101 / 6102 / 6105 / 6106 / 6107 倍率 1000，按百分數傳值（如 20% 傳 20）；days參數不生效add_kline_shape(name, period=None, value_set=None) K 線形態（雙底、頭肩底等） period 必傳，目前僅支持日 K(11) 與 1 小時 K(21)add_option(name, intervals=None, param=None, period=None) 期權指標（正股 IV、HV 等） 取回屬性 builder 方法（聲明返回哪些字段值；不聲明則只返回 stock_id）：
方法 說明 add_retrieve_basic(name) 代碼 / 名稱 / 行業 name 取自 BasicProperty：CODE=1101、NAME=1102、INDUSTRY=1103add_retrieve_simple(name) 簡單行情屬性 name 取自 SimplePropertyadd_retrieve_cumulative(name, days=1, period_average=None) 累計屬性 name 取自 CumulativePropertyadd_retrieve_financial(name, term=None, year=None, ...) 財務屬性 name 取自 FinancialPropertyadd_retrieve_indicator(name, period=None, indicator_params=None) 技術指標 add_retrieve_featured(name, period=None, range_period=None, first_custom_param=None) 特色屬性 add_retrieve_broker(name, days=None, param=None) 經紀商 add_retrieve_option(name, param=None, period=None) 期權屬性 add_retrieve_kline_shape(name, period=None) K 線形態 period 必傳，否則不返回結果；目前僅支持日 K(11) 與 1 小時 K(21)排序 builder 方法：
方法 說明 set_sort(direction, property_type, property_params) 單字段排序 direction 取自 ScrSortDir：ASC=1、DESC=2、ABS_ASC=3、ABS_DESC=4。property_type 取 'basic' / 'simple' / 'cumulative' / 'financial' / 'indicator' / 'featured' / 'broker' / 'option' / 'kline_shape'add_sort(direction, property_type, property_params) 多字段排序 按調用順序生效；與 set_sort 二選一，sortList 非空時優先
返回
參數 類型 說明 ret RET_CODE 接口調用結果 data tuple 當 ret == RET_OK，返回 (last_page, all_count, items) str 當 ret != RET_OK，返回錯誤描述 返回 tuple 字段：
字段 類型 說明 last_page bool 是否最後一頁 all_count int 滿足條件的總條數 items list[dict] 當前頁結果列表，元素結構為 {'stock_id': int, 'results': [result, ...]}單條 result 結構：
字段 類型 說明 type str 屬性類型 'basic' / 'simple' / 'cumulative' / 'financial' / 'indicator' / 'featured' / 'broker' / 'option' / 'kline_shape'property dict 對應 property 描述（含 name / days / term 等） value_type int 值類型 1=string(sval)、2=int64(ival)、3=int64數組(aval)、4=double(dval)。當 OpenD 無數據時僅下發 value_type（多為 2），sval/ival/aval/dval 均缺失，如港股 Q2/Q3/Q4 財務數據sval str 字符串值（value_type=1 時存在） ival int 整型值（value_type=2 時存在） aval list[int] 整型數組值（value_type=3 時存在） dval float 浮點值（value_type=4 時存在） enum_type_name str 當 ival 為枚舉碼時，對應的枚舉類型名（如 'KlineShapeType'） enum_name str 當 ival 為枚舉碼時，OpenD/SDK 解碼出的枚舉名（如 'DOUBLE_BOTTOMS'、'NONE'） end_time int 財報結束時間戳 僅 financial 類型，且當前 OpenD 版本暫未下發，實際返回結果中通常沒有該字段
Example
from futu import OpenQuoteContext, RET_OK, StockScreenRequest
from futu.quote.stock_screen_const import (
ScrMarket, ScrSortDir, SimpleField, SimpleProperty,
CumulativeProperty, FinancialProperty, Term,
Indicator, Period, Position, Pattern,
BasicProperty, KlineShapeProperty, KlineShapeType,
)
quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
# 示例 1：港股大市值股 + MACD 金叉
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_simple_property(name=SimpleProperty.PRICE, lower=10.0) # 最新價 ≥ 10
req.add_simple_property(name=SimpleProperty.MARKET_CAP, lower=10_000_000_000.0) # 市值 ≥ 100 億
req.add_simple_property(name=SimpleProperty.PE_TTM, lower=10.0, upper=50.0) # PE(TTM) 10~50
req.add_indicator_pattern(name=Pattern.MACD_GOLD_CROSS, period_type=Period.DAY) # MACD 金叉
# 取回字段
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_basic(name=BasicProperty.NAME)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.add_retrieve_simple(name=SimpleProperty.MARKET_CAP)
req.add_retrieve_simple(name=SimpleProperty.PE_TTM)
# 排序
req.set_sort(direction=ScrSortDir.DESC, property_type='simple',
property_params={'name': int(SimpleProperty.MARKET_CAP)})
req.page_count = 50
ret, data = quote_ctx.get_stock_screen(req)
if ret == RET_OK:
last_page, all_count, items = data
print(f"總數 {all_count}, 當前返回 {len(items)} 條")
for it in items[:3]:
print(it['stock_id'], it['results'])
else:
print('error: ', data)
# 示例 2：財務因子 + 累計漲跌幅
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_cumulative_property(name=CumulativeProperty.PRICE_CHANGE_PCT,
days=5, lower=-0.05, upper=0.05) # 5 日漲跌幅 -5%~5%（百分數傳小數）
req.add_financial_property(name=FinancialProperty.NET_PROFIT,
term=Term.ANNUAL, lower=0.0) # 年報淨利潤 > 0
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.page_count = 200
ret, data = quote_ctx.get_stock_screen(req)
# 示例 3：K 線形態（W 型底 + 頭肩底）
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_kline_shape(name=KlineShapeProperty.SHAPE_TYPE, period=Period.DAY,
value_set=[KlineShapeType.DOUBLE_BOTTOMS,
KlineShapeType.HEAD_SHOULDERS_BOTTOM])
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_kline_shape(name=KlineShapeProperty.SHAPE_TYPE, period=Period.DAY)
ret, data = quote_ctx.get_stock_screen(req)
quote_ctx.close()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
- Output
總數 1, 當前返回 1 條
54047868453564 [{'type': 'basic', 'property': {'name': 1101}, 'value_type': 1, 'sval': '00700'},
{'type': 'basic', 'property': {'name': 1102}, 'value_type': 1, 'sval': '騰訊控股'},
{'type': 'simple', 'property': {'name': 2201}, 'value_type': 4, 'dval': 460.0},
{'type': 'simple', 'property': {'name': 2301}, 'value_type': 4, 'dval': 4194280264040.0},
{'type': 'simple', 'property': {'name': 2303}, 'value_type': 4, 'dval': 15.75126}]
1
2
3
4
5
6
2
3
4
5
6
# Qot_StockScreen.proto
介紹
條件選股 V2
參數
message Boundary
{
required double value = 1;
optional bool includes = 2; // 是否閉區間，默認 true
}
message Interval
{
optional Boundary filterMin = 1;
optional Boundary filterMax = 2;
}
// ===== 各類 PropertyXxx =====
message PropertyBasic { required int32 name = 1; }
message PropertySimple { required int32 name = 1; optional int32 unit = 2; }
message PropertyCumulative {
required int32 name = 1;
required int32 days = 2;
optional int32 periodAverage = 3;
optional int32 unit = 4;
}
message PropertyFinancial {
required int32 name = 1;
optional int32 term = 2;
optional int32 year = 3;
optional int32 duration = 4;
optional int32 periodAverage = 5;
optional int32 futureDuration = 6;
optional int32 unit = 7;
}
message PropertyIndicator {
required int32 name = 1;
optional int32 period = 2;
repeated int32 indicatorParams = 3;
}
message PropertyFeatured {
required int32 name = 1;
optional int32 period = 2;
optional int32 rangePeriod = 3;
optional int32 firstCustomParam = 4;
}
message PropertyBroker {
required int32 name = 1;
optional int32 days = 2;
optional string param = 3;
}
message PropertyOption {
required int32 name = 1;
optional int32 period = 2;
optional string param = 3;
}
message PropertyKlineShape {
required int32 name = 1;
optional int32 period = 2;
}
// ===== 各類 QueryXxx =====
message SimpleFieldQuery
{
required int32 simpleField = 1;
repeated int32 screenValueList = 2;
}
message PlateInfo
{
repeated string plateIdList = 1;
optional string parentPlateId = 2;
}
message PlateQuery { repeated PlateInfo plateList = 1; }
message SimplePropertyQuery
{
required PropertySimple property = 1;
optional Boundary filterMin = 2;
optional Boundary filterMax = 3;
}
message CumulativePropertyQuery
{
required PropertyCumulative property = 1;
optional Boundary filterMin = 2;
optional Boundary filterMax = 3;
optional int32 continuousPeriod = 4;
}
message FinancialPropertyQuery
{
required PropertyFinancial property = 1;
optional Boundary filterMin = 2;
optional Boundary filterMax = 3;
optional int32 continuousPeriod = 4;
}
message IndicatorPositionalQuery
{
required int32 firstIndicatorName = 1;
required int32 periodType = 2;
required int32 position = 3;
optional int32 secondIndicator = 4;
optional int32 secondValue = 5;
repeated int32 firstIndicatorParams = 6;
repeated int32 secondIndicatorParams = 7;
optional int32 continuousPeriod = 8;
repeated Interval intervals = 9;
}
message IndicatorPatternQuery
{
required int32 name = 1;
required int32 periodType = 2;
optional int32 continuousPeriod = 3;
optional bool isMatching = 4;
repeated int32 subPatterns = 5;
}
message FeaturedPropertyQuery
{
required PropertyFeatured property = 1;
repeated Interval intervals = 2;
repeated int32 valueSet = 3;
}
message BrokerHoldingsQuery
{
required PropertyBroker property = 1;
repeated Interval intervals = 2;
}
message KlineShapeQuery
{
required PropertyKlineShape property = 1;
repeated int32 valueSet = 2;
}
message OptionQuery
{
required PropertyOption property = 1;
repeated Interval intervals = 2;
}
// ===== 一條篩選條件 (oneof 多選一) =====
message ScreenQuery
{
optional SimpleFieldQuery simpleFieldQuery = 1;
optional PlateQuery plateQuery = 2;
optional SimplePropertyQuery simplePropertyQuery = 3;
optional CumulativePropertyQuery cumulativePropertyQuery = 4;
optional FinancialPropertyQuery financialPropertyQuery = 5;
optional IndicatorPositionalQuery indicatorPositionalQuery = 6;
optional IndicatorPatternQuery indicatorPatternQuery = 7;
optional FeaturedPropertyQuery featuredPropertyQuery = 8;
optional BrokerHoldingsQuery brokerHoldingsQuery = 9;
optional KlineShapeQuery klineShapeQuery = 10;
optional OptionQuery optionQuery = 11;
}
// ===== 取回字段 =====
message RetrieveQuery
{
optional PropertyBasic basicProperty = 1;
optional PropertySimple simpleProperty = 2;
optional PropertyCumulative cumulativeProperty = 3;
optional PropertyFinancial financialProperty = 4;
optional PropertyIndicator indicatorProperty = 5;
optional PropertyFeatured featuredProperty = 6;
optional PropertyBroker brokerProperty = 7;
optional PropertyOption optionProperty = 8;
optional PropertyKlineShape klineShapeProperty = 9;
}
// ===== 排序定義 =====
message Sort
{
required int32 direction = 1; // 1=ASC, 2=DESC, 3=ABS_ASC, 4=ABS_DESC
optional PropertyBasic basicProperty = 2;
optional PropertySimple simpleProperty = 3;
optional PropertyCumulative cumulativeProperty = 4;
optional PropertyFinancial financialProperty = 5;
optional PropertyIndicator indicatorProperty = 6;
optional PropertyFeatured featuredProperty = 7;
optional PropertyBroker brokerProperty = 8;
optional PropertyOption optionProperty = 9;
optional PropertyKlineShape klineShapeProperty = 10;
}
message C2S
{
repeated ScreenQuery filterList = 1;
repeated RetrieveQuery retrieveList = 2;
repeated int64 watchlistStockIds = 3;
optional Sort sort = 4; // 單字段排序
optional int32 pageFrom = 5;
optional int32 pageCount = 6;
repeated Sort sortList = 7; // 多字段排序，非空時優先於 sort
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
- 返回
// 單條結果值: valueType=1 時取 sval, =2 取 ival, =3 取 aval, =4 取 dval
message ResultPropertyBasic
{
required PropertyBasic property = 1;
optional int32 valueType = 2;
optional string sval = 3;
optional int64 ival = 4;
repeated int64 aval = 5;
optional double dval = 6;
optional string enumTypeName = 7;
optional string enumName = 8;
}
// 其餘 ResultPropertySimple / Cumulative / Financial / Indicator / Featured / Broker / Option / KlineShape
// 結構與 ResultPropertyBasic 相同，僅 property 類型不同。Financial 額外包含 endTime。
message RspItemResult
{
optional ResultPropertyBasic basicPropertyResult = 1;
optional ResultPropertySimple simplePropertyResult = 2;
optional ResultPropertyCumulative cumulativePropertyResult = 3;
optional ResultPropertyFinancial financialPropertyResult = 4;
optional ResultPropertyIndicator indicatorPropertyResult = 5;
optional ResultPropertyFeatured featuredPropertyResult = 6;
optional ResultPropertyBroker brokerPropertyResult = 7;
optional ResultPropertyOption optionPropertyResult = 8;
optional ResultPropertyKlineShape klineShapePropertyResult = 9;
}
message RspItem
{
required int64 stockId = 1;
repeated RspItemResult results = 2;
}
message S2C
{
required bool lastPage = 1;
required int32 allCount = 2;
repeated RspItem dataList = 3;
}
message Response
{
required int32 retType = 1 [default = -400];
optional string retMsg = 2;
optional int32 errCode = 3;
optional S2C s2c = 4;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
- 接口調用結果，結構參見 RetType
協議 ID
3252
uint StockScreen(QotStockScreen.Request req); virtual void OnReply_StockScreen(FTAPI_Conn client, uint nSerialNo, QotStockScreen.Response rsp);
介紹
條件選股 V2
參數
參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。
返回
參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。
協議 ID
3252
int stockScreen(QotStockScreen.Request req) onReply_StockScreen(FTAPI_Conn client, int nSerialNo, QotStockScreen.Response rsp)
介紹
條件選股 V2
參數
參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。
返回
參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。
協議 ID
3252
bool StockScreen(uint32_t & nSerialNo, const Qot_StockScreen::Request & stReq); virtual void OnReply_StockScreen(FTAPI_Conn* pConn, uint32_t nSerialNo, const Qot_StockScreen::Response & stRsp)
介紹
條件選股 V2
參數
參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。
返回
參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。
協議 ID
3252
stockScreen(qotStockScreen)
介紹
條件選股 V2
參數
參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。
返回
參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。
協議 ID
3252
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_stock_screen(request)
介紹
條件選股 V2，參數與返回字段同 nn 標籤頁。
Example
from moomoo import OpenQuoteContext, RET_OK, StockScreenRequest
from moomoo.quote.stock_screen_const import (
ScrMarket, ScrSortDir, SimpleField, SimpleProperty,
Indicator, Period, Pattern, BasicProperty,
)
quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_simple_property(name=SimpleProperty.PRICE, lower=10.0)
req.add_simple_property(name=SimpleProperty.MARKET_CAP, lower=10_000_000_000.0)
req.add_indicator_pattern(name=Pattern.MACD_GOLD_CROSS, period_type=Period.DAY)
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_basic(name=BasicProperty.NAME)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.add_retrieve_simple(name=SimpleProperty.MARKET_CAP)
req.set_sort(direction=ScrSortDir.DESC, property_type='simple',
property_params={'name': int(SimpleProperty.MARKET_CAP)})
req.page_count = 50
ret, data = quote_ctx.get_stock_screen(req)
if ret == RET_OK:
last_page, all_count, items = data
print(f"總數 {all_count}, 當前返回 {len(items)} 條")
else:
print('error: ', data)
quote_ctx.close()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Qot_StockScreen.proto
參考 nn 標籤頁 Proto 內容，協議 ID 3252。
uint StockScreen(QotStockScreen.Request req); virtual void OnReply_StockScreen(FTAPI_Conn client, uint nSerialNo, QotStockScreen.Response rsp);
參考 nn 標籤頁 Proto 內容，協議 ID 3252。
int stockScreen(QotStockScreen.Request req) onReply_StockScreen(FTAPI_Conn client, int nSerialNo, QotStockScreen.Response rsp)
參考 nn 標籤頁 Proto 內容，協議 ID 3252。
bool StockScreen(uint32_t & nSerialNo, const Qot_StockScreen::Request & stReq); virtual void OnReply_StockScreen(FTAPI_Conn* pConn, uint32_t nSerialNo, const Qot_StockScreen::Response & stRsp)
參考 nn 標籤頁 Proto 內容，協議 ID 3252。
stockScreen(qotStockScreen)
參考 nn 標籤頁 Proto 內容，協議 ID 3252。