# Get Macro Indicator History
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_macro_indicator_history(indicator_id, time=None, max_count=None)
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
Parameter Type Description indicator_id int Macro indicator ID (from get_macro_indicator_listreturn) (required)time str Time point, format "yyyy-MM-dd", pulls data before this time; defaults to current time if not provided max_count int Number of records to pull, default 100, maximum 1000 Return
Parameter Type Description ret RET_CODE API call result data pd.DataFrame When ret == RET_OK, returns data str When ret != RET_OK, returns error description - Data format:
Field Type Description data_time str Data date ("yyyy-MM-dd") release_time str Release date ("yyyy-MM-dd HH:mm:ss") value float Actual value (restored to original value) predict_value float Forecast value (restored) previous_value float Previous value (restored) unit_type str Unit type (PERCENT=percentage / VALUE=value / INDEX=index)
- Data format:
Example
from futu import *
quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
# First get indicator ID
ret, indicators = quote_ctx.get_macro_indicator_list(region=MacroRegion.US)
if ret == RET_OK:
indicator_id = indicators.iloc[0]['indicator_id']
# Query historical data
ret, data = quote_ctx.get_macro_indicator_history(indicator_id=indicator_id, max_count=2)
if ret == RET_OK:
print(data)
else:
print('error:', data)
quote_ctx.close()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
- Output
data_time release_time value predict_value previous_value unit_type
0 2026-05-01 2026-06-11 20:34:01 0.0642 N/A 0.0566 PERCENT
1 2026-04-01 2026-05-13 20:31:01 0.0566 N/A 0.0427 PERCENT
1
2
3
2
3
# Qot_GetMacroIndicatorHistory.proto
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
Protocol ID
3403
uint GetMacroIndicatorHistory(Qot_GetMacroIndicatorHistory.Request req);
virtual void OnReply_GetMacroIndicatorHistory(FTAPI_Conn client, uint nSerialNo, Qot_GetMacroIndicatorHistory.Response rsp);
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
public class Program : FTSPI_Qot, FTSPI_Conn {
FTAPI_Qot qot = new FTAPI_Qot();
public Program() {
qot.SetClientInfo("csharp", 1); //设置客户端信息
qot.SetConnCallback(this); //设置连接回调
qot.SetQotCallback(this); //设置行情回调
}
public void Start() {
qot.InitConnect("127.0.0.1", (ushort)11111, false);
}
public void OnInitConnect(FTAPI_Conn client, long errCode, String desc)
{
Console.Write("Qot onInitConnect: ret={0} desc={1} connID={2}
", errCode, desc, client.GetConnectID());
if (errCode != 0)
return;
QotGetMacroIndicatorHistory.C2S c2s = QotGetMacroIndicatorHistory.C2S.CreateBuilder()
.SetIndicatorId(1003000003)
.Build();
QotGetMacroIndicatorHistory.Request req = QotGetMacroIndicatorHistory.Request.CreateBuilder().SetC2S(c2s).Build();
uint seqNo = qot.GetMacroIndicatorHistory(req);
Console.Write("Send QotGetMacroIndicatorHistory: {0}
", seqNo);
}
public void OnDisconnect(FTAPI_Conn client, long errCode) {
Console.Write("Qot onDisConnect: {0}
", errCode);
}
public void OnReply_GetMacroIndicatorHistory(FTAPI_Conn client, uint nSerialNo, QotGetMacroIndicatorHistory.Response rsp)
{
Console.Write("Reply: QotGetMacroIndicatorHistory: {0}
", nSerialNo);
if (rsp.RetType == 0 && rsp.HasS2C)
Console.Write("{0}
", rsp.ToString());
}
public static void Main(String[] args) {
FTAPI.Init();
Program program = new Program();
program.Start();
while (true)
Thread.Sleep(1000 * 600);
}
}
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
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
- Output
Send QotGetMacroIndicatorHistory: 3
Reply: QotGetMacroIndicatorHistory: 3
GetMacroIndicatorHistory: errCode 0, retMsg , retType 0
{
"indicatorId": "1003000003",
"dataList": [
{ "dataTime": "2026-05-01", "value": 0.0642, "previousValue": 0.0566, "unitType": "PERCENT" },
{ "dataTime": "2026-04-01", "value": 0.0566, "previousValue": 0.0427, "unitType": "PERCENT" },
{ "dataTime": "2026-03-01", "value": 0.0427, "previousValue": 0.0338, "unitType": "PERCENT" }
]
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
int getMacroIndicatorHistory(Qot_GetMacroIndicatorHistory.Request req);
onReply_GetMacroIndicatorHistory(FTAPI_Conn client, int nSerialNo, Qot_GetMacroIndicatorHistory.Response rsp)
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
public class QotDemo implements FTSPI_Qot, FTSPI_Conn {
FTAPI_Conn_Qot qot = new FTAPI_Conn_Qot();
public QotDemo() {
qot.setClientInfo("javaclient", 1); //设置客户端信息
qot.setConnSpi(this); //设置连接回调
qot.setQotSpi(this); //设置行情回调
}
public void start() {
qot.initConnect("127.0.0.1", (short)11111, false);
}
@Override
public void onInitConnect(FTAPI_Conn client, long errCode, String desc)
{
System.out.printf("Qot onInitConnect: ret=%d desc=%s connID=%d
", errCode, desc, client.getConnectID());
if (errCode != 0)
return;
QotGetMacroIndicatorHistory.C2S c2s = QotGetMacroIndicatorHistory.C2S.newBuilder()
.setIndicatorId(1003000003)
.build();
QotGetMacroIndicatorHistory.Request req = QotGetMacroIndicatorHistory.Request.newBuilder().setC2S(c2s).build();
int seqNo = qot.getMacroIndicatorHistory(req);
System.out.printf("Send QotGetMacroIndicatorHistory: %d
", seqNo);
}
@Override
public void onDisconnect(FTAPI_Conn client, long errCode) {
System.out.printf("Qot onDisConnect: %d
", errCode);
}
@Override
public void onReply_GetMacroIndicatorHistory(FTAPI_Conn client, int nSerialNo, QotGetMacroIndicatorHistory.Response rsp) {
if (rsp.getRetType() != 0) {
System.out.printf("QotGetMacroIndicatorHistory failed: %s
", rsp.getRetMsg());
} else {
try {
String json = JsonFormat.printer().print(rsp);
System.out.printf("Receive QotGetMacroIndicatorHistory: %s
", json);
} catch (InvalidProtocolBufferException e) {
e.printStackTrace();
}
}
}
public static void main(String[] args) {
FTAPI.init();
QotDemo qot = new QotDemo();
qot.start();
while (true) {
try {
Thread.sleep(1000 * 600);
} catch (InterruptedException exc) {
}
}
}
}
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
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
- Output
Send QotGetMacroIndicatorHistory: 3
Receive QotGetMacroIndicatorHistory: {
"indicatorId": "1003000003",
"dataList": [
{ "dataTime": "2026-05-01", "value": 0.0642, "previousValue": 0.0566, "unitType": "PERCENT" },
{ "dataTime": "2026-04-01", "value": 0.0566, "previousValue": 0.0427, "unitType": "PERCENT" },
{ "dataTime": "2026-03-01", "value": 0.0427, "previousValue": 0.0338, "unitType": "PERCENT" }
]
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
Futu::u32_t GetMacroIndicatorHistory(const Qot_GetMacroIndicatorHistory::Request &stReq); virtual void OnReply_GetMacroIndicatorHistory(Futu::u32_t nSerialNo, const Qot_GetMacroIndicatorHistory::Response &stRsp) = 0;
Description
Protocol request and response definition
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
class Program : public FTSPI_Qot, public FTSPI_Conn
{
public:
Program() {
m_pQotApi = FTAPI::CreateQotApi();
m_pQotApi->RegisterQotSpi(this);
m_pQotApi->RegisterConnSpi(this);
}
~Program() {
if (m_pQotApi != nullptr) {
m_pQotApi->UnregisterQotSpi();
m_pQotApi->UnregisterConnSpi();
FTAPI::ReleaseQotApi(m_pQotApi);
m_pQotApi = nullptr;
}
}
void Start() {
m_pQotApi->InitConnect("127.0.0.1", 11111, false);
}
virtual void OnInitConnect(FTAPI_Conn* pConn, Futu::i64_t nErrCode, const char* strDesc) {
Qot_GetMacroIndicatorHistory::Request req;
Qot_GetMacroIndicatorHistory::C2S *c2s = req.mutable_c2s();
c2s->set_indicatorid(10001); // example indicator ID, obtain from GetMacroIndicatorList
c2s->set_maxcount(100);
m_GetMacroIndicatorHistorySerialNo = m_pQotApi->GetMacroIndicatorHistory(req);
}
virtual void OnReply_GetMacroIndicatorHistory(Futu::u32_t nSerialNo, const Qot_GetMacroIndicatorHistory::Response &stRsp) {
if (nSerialNo != m_GetMacroIndicatorHistorySerialNo) return;
string resp_str;
ProtoBufToBodyData(stRsp, resp_str);
cout << UTF8ToLocal(resp_str) << endl;
}
protected:
FTAPI_Qot *m_pQotApi;
Futu::u32_t m_GetMacroIndicatorHistorySerialNo = 0;
};
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
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
- Output
{
"retType": 0,
"retMsg": "",
"errCode": 0,
"s2c": {
"indicatorId": 10001,
"dataList": [
{
"time": "2024-06-01",
"value": 3.27
},
{
"time": "2024-05-01",
"value": 3.36
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
getMacroIndicatorHistory(qotGetMacroIndicatorHistory)
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
import ftWebsocket from "futu-api";
import { Common, Qot_Common } from "futu-api/proto";
import beautify from "js-beautify";
function QotGetMacroIndicatorHistory(){
const { RetType } = Common
let [addr, port, enable_ssl, key] = ["127.0.0.1", 11111, false, "xxxxxx"];
let websocket = new ftWebsocket();
websocket.onlogin = (ret, msg)=>{
if (ret) {
const req = {
c2s: { indicatorId: 1003000003 },
};
websocket.GetMacroIndicatorHistory(req)
.then((res)=>{
let { errCode, retMsg, retType, s2c } = res
console.log("GetMacroIndicatorHistory: errCode %d, retMsg %s, retType %d", errCode, retMsg, retType);
if(retType == RetType.RetType_Succeed){
let data = beautify(JSON.stringify(s2c), { indent_size: 2, space_in_empty_paren: true });
console.log(data);
}
})
.catch((error)=>{ console.log("error:", error); });
} else {
console.log("start error", msg);
}
};
websocket.start(addr, port, enable_ssl, key);
setTimeout(()=>{ websocket.stop(); process.exit(); }, 5000);
}
QotGetMacroIndicatorHistory()
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
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
- Output
GetMacroIndicatorHistory: errCode 0, retMsg , retType 0
{
"indicatorId": "1003000003",
"dataList": [
{ "dataTime": "2026-05-01", "value": 0.0642, "previousValue": 0.0566, "unitType": "PERCENT" },
{ "dataTime": "2026-04-01", "value": 0.0566, "previousValue": 0.0427, "unitType": "PERCENT" },
{ "dataTime": "2026-03-01", "value": 0.0427, "previousValue": 0.0338, "unitType": "PERCENT" }
]
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
API Limits
- Maximum 60 requests within 30 seconds
- Only the first page of paginated requests counts towards rate limiting
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_macro_indicator_history(indicator_id, time=None, max_count=None)
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
Parameter Type Description indicator_id int Macro indicator ID (from get_macro_indicator_listreturn) (required)time str Time point, format "yyyy-MM-dd", pulls data before this time; defaults to current time if not provided max_count int Number of records to pull, default 100, maximum 1000 Return
Parameter Type Description ret RET_CODE API call result data pd.DataFrame When ret == RET_OK, returns data str When ret != RET_OK, returns error description - Data format:
Field Type Description data_time str Data date ("yyyy-MM-dd") release_time str Release date ("yyyy-MM-dd HH:mm:ss") value float Actual value (restored to original value) predict_value float Forecast value (restored) previous_value float Previous value (restored) unit_type str Unit type (PERCENT=percentage / VALUE=value / INDEX=index)
- Data format:
Example
from futu import *
quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
# First get indicator ID
ret, indicators = quote_ctx.get_macro_indicator_list(region=MacroRegion.US)
if ret == RET_OK:
indicator_id = indicators.iloc[0]['indicator_id']
# Query historical data
ret, data = quote_ctx.get_macro_indicator_history(indicator_id=indicator_id, max_count=2)
if ret == RET_OK:
print(data)
else:
print('error:', data)
quote_ctx.close()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
- Output
data_time release_time value predict_value previous_value unit_type
0 2026-05-01 2026-06-11 20:34:01 0.0642 N/A 0.0566 PERCENT
1 2026-04-01 2026-05-13 20:31:01 0.0566 N/A 0.0427 PERCENT
1
2
3
2
3
# Qot_GetMacroIndicatorHistory.proto
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
Protocol ID
3403
uint GetMacroIndicatorHistory(Qot_GetMacroIndicatorHistory.Request req);
virtual void OnReply_GetMacroIndicatorHistory(FTAPI_Conn client, uint nSerialNo, Qot_GetMacroIndicatorHistory.Response rsp);
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
public class Program : MMSPI_Qot, MMSPI_Conn {
MMAPI_Qot qot = new MMAPI_Qot();
public Program() {
qot.SetClientInfo("csharp", 1); //设置客户端信息
qot.SetConnCallback(this); //设置连接回调
qot.SetQotCallback(this); //设置行情回调
}
public void Start() {
qot.InitConnect("127.0.0.1", (ushort)11111, false);
}
public void OnInitConnect(MMAPI_Conn client, long errCode, String desc)
{
Console.Write("Qot onInitConnect: ret={0} desc={1} connID={2}
", errCode, desc, client.GetConnectID());
if (errCode != 0)
return;
QotGetMacroIndicatorHistory.C2S c2s = QotGetMacroIndicatorHistory.C2S.CreateBuilder()
.SetIndicatorId(1003000003)
.Build();
QotGetMacroIndicatorHistory.Request req = QotGetMacroIndicatorHistory.Request.CreateBuilder().SetC2S(c2s).Build();
uint seqNo = qot.GetMacroIndicatorHistory(req);
Console.Write("Send QotGetMacroIndicatorHistory: {0}
", seqNo);
}
public void OnDisconnect(MMAPI_Conn client, long errCode) {
Console.Write("Qot onDisConnect: {0}
", errCode);
}
public void OnReply_GetMacroIndicatorHistory(MMAPI_Conn client, uint nSerialNo, QotGetMacroIndicatorHistory.Response rsp)
{
Console.Write("Reply: QotGetMacroIndicatorHistory: {0}
", nSerialNo);
if (rsp.RetType == 0 && rsp.HasS2C)
Console.Write("{0}
", rsp.ToString());
}
public static void Main(String[] args) {
MMAPI.Init();
Program program = new Program();
program.Start();
while (true)
Thread.Sleep(1000 * 600);
}
}
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
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
- Output
Send QotGetMacroIndicatorHistory: 3
Reply: QotGetMacroIndicatorHistory: 3
GetMacroIndicatorHistory: errCode 0, retMsg , retType 0
{
"indicatorId": "1003000003",
"dataList": [
{ "dataTime": "2026-05-01", "value": 0.0642, "previousValue": 0.0566, "unitType": "PERCENT" },
{ "dataTime": "2026-04-01", "value": 0.0566, "previousValue": 0.0427, "unitType": "PERCENT" },
{ "dataTime": "2026-03-01", "value": 0.0427, "previousValue": 0.0338, "unitType": "PERCENT" }
]
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
int getMacroIndicatorHistory(Qot_GetMacroIndicatorHistory.Request req);
onReply_GetMacroIndicatorHistory(FTAPI_Conn client, int nSerialNo, Qot_GetMacroIndicatorHistory.Response rsp)
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
public class QotDemo implements MMSPI_Qot, MMSPI_Conn {
MMAPI_Conn_Qot qot = new MMAPI_Conn_Qot();
public QotDemo() {
qot.setClientInfo("javaclient", 1); //设置客户端信息
qot.setConnSpi(this); //设置连接回调
qot.setQotSpi(this); //设置行情回调
}
public void start() {
qot.initConnect("127.0.0.1", (short)11111, false);
}
@Override
public void onInitConnect(MMAPI_Conn client, long errCode, String desc)
{
System.out.printf("Qot onInitConnect: ret=%d desc=%s connID=%d
", errCode, desc, client.getConnectID());
if (errCode != 0)
return;
QotGetMacroIndicatorHistory.C2S c2s = QotGetMacroIndicatorHistory.C2S.newBuilder()
.setIndicatorId(1003000003)
.build();
QotGetMacroIndicatorHistory.Request req = QotGetMacroIndicatorHistory.Request.newBuilder().setC2S(c2s).build();
int seqNo = qot.getMacroIndicatorHistory(req);
System.out.printf("Send QotGetMacroIndicatorHistory: %d
", seqNo);
}
@Override
public void onDisconnect(MMAPI_Conn client, long errCode) {
System.out.printf("Qot onDisConnect: %d
", errCode);
}
@Override
public void onReply_GetMacroIndicatorHistory(MMAPI_Conn client, int nSerialNo, QotGetMacroIndicatorHistory.Response rsp) {
if (rsp.getRetType() != 0) {
System.out.printf("QotGetMacroIndicatorHistory failed: %s
", rsp.getRetMsg());
} else {
try {
String json = JsonFormat.printer().print(rsp);
System.out.printf("Receive QotGetMacroIndicatorHistory: %s
", json);
} catch (InvalidProtocolBufferException e) {
e.printStackTrace();
}
}
}
public static void main(String[] args) {
MMAPI.init();
QotDemo qot = new QotDemo();
qot.start();
while (true) {
try {
Thread.sleep(1000 * 600);
} catch (InterruptedException exc) {
}
}
}
}
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
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
- Output
Send QotGetMacroIndicatorHistory: 3
Receive QotGetMacroIndicatorHistory: {
"indicatorId": "1003000003",
"dataList": [
{ "dataTime": "2026-05-01", "value": 0.0642, "previousValue": 0.0566, "unitType": "PERCENT" },
{ "dataTime": "2026-04-01", "value": 0.0566, "previousValue": 0.0427, "unitType": "PERCENT" },
{ "dataTime": "2026-03-01", "value": 0.0427, "previousValue": 0.0338, "unitType": "PERCENT" }
]
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
moomoo::u32_t GetMacroIndicatorHistory(const Qot_GetMacroIndicatorHistory::Request &stReq); virtual void OnReply_GetMacroIndicatorHistory(moomoo::u32_t nSerialNo, const Qot_GetMacroIndicatorHistory::Response &stRsp) = 0;
Description
Protocol request and response definition
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
class Program : public MMSPI_Qot, public MMSPI_Conn
{
public:
Program() {
m_pQotApi = MMAPI::CreateQotApi();
m_pQotApi->RegisterQotSpi(this);
m_pQotApi->RegisterConnSpi(this);
}
~Program() {
if (m_pQotApi != nullptr) {
m_pQotApi->UnregisterQotSpi();
m_pQotApi->UnregisterConnSpi();
MMAPI::ReleaseQotApi(m_pQotApi);
m_pQotApi = nullptr;
}
}
void Start() {
m_pQotApi->InitConnect("127.0.0.1", 11111, false);
}
virtual void OnInitConnect(MMAPI_Conn* pConn, moomoo::i64_t nErrCode, const char* strDesc) {
Qot_GetMacroIndicatorHistory::Request req;
Qot_GetMacroIndicatorHistory::C2S *c2s = req.mutable_c2s();
c2s->set_indicatorid(10001); // example indicator ID, obtain from GetMacroIndicatorList
c2s->set_maxcount(100);
m_GetMacroIndicatorHistorySerialNo = m_pQotApi->GetMacroIndicatorHistory(req);
}
virtual void OnReply_GetMacroIndicatorHistory(moomoo::u32_t nSerialNo, const Qot_GetMacroIndicatorHistory::Response &stRsp) {
if (nSerialNo != m_GetMacroIndicatorHistorySerialNo) return;
string resp_str;
ProtoBufToBodyData(stRsp, resp_str);
cout << UTF8ToLocal(resp_str) << endl;
}
protected:
MMAPI_Qot *m_pQotApi;
moomoo::u32_t m_GetMacroIndicatorHistorySerialNo = 0;
};
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
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
- Output
{
"retType": 0,
"retMsg": "",
"errCode": 0,
"s2c": {
"indicatorId": 10001,
"dataList": [
{
"time": "2024-06-01",
"value": 3.27
},
{
"time": "2024-05-01",
"value": 3.36
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
getMacroIndicatorHistory(qotGetMacroIndicatorHistory)
Description
Get macro indicator history. Returns the historical data point list of the specified macro indicator, including data date, release date, actual value, forecast value, previous value, etc., sorted by time in descending order.
Parameters
// Macro data unit type
enum MacroDataUnitType {
MacroDataUnitType_Unknown = 0; //Unknown
MacroDataUnitType_Percent = 1; //Percentage(%)
MacroDataUnitType_Value = 2; //Value
MacroDataUnitType_Index = 3; //Index
}
// Macro data point
message MacroDataPoint {
optional string dataTime = 1; //Data date "yyyy-MM-dd"
optional string releaseTime = 2; //Publication date "yyyy-MM-dd HH:mm:ss"
optional double value = 3; //Actual value (restored to original)
optional double predictValue = 4; //Forecast value (restored)
optional double previousValue = 5; //Previous value (restored)
optional int32 unitType = 6; //MacroDataUnitType, unit type
}
message C2S {
required uint64 indicatorId = 1; //Macro indicator ID (from Qot_GetMacroIndicatorList response)
optional string time = 2; //Time point "yyyy-MM-dd", fetch backwards from this time; default current time if omitted
optional int32 maxCount = 3; //Fetch count, default 100, max 1000
optional Qot_Common.QotHeader header = 100; //Quote common parameter header
}
message S2C {
optional uint64 indicatorId = 1; //Indicator ID (echo back)
repeated MacroDataPoint dataList = 2; //Historical data points list (sorted by time descending)
}
message Request {
required C2S c2s = 1;
}
message Response {
required int32 retType = 1 [default = -400]; //RetType, return result
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
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
- For interface result, refer to RetType
Protocol ID
3403
Example
import mmWebsocket from "moomoo-api";
import { Common, Qot_Common } from "moomoo-api/proto";
import beautify from "js-beautify";
function QotGetMacroIndicatorHistory(){
const { RetType } = Common
let [addr, port, enable_ssl, key] = ["127.0.0.1", 11111, false, "xxxxxx"];
let websocket = new mmWebsocket();
websocket.onlogin = (ret, msg)=>{
if (ret) {
const req = {
c2s: { indicatorId: 1003000003 },
};
websocket.GetMacroIndicatorHistory(req)
.then((res)=>{
let { errCode, retMsg, retType, s2c } = res
console.log("GetMacroIndicatorHistory: errCode %d, retMsg %s, retType %d", errCode, retMsg, retType);
if(retType == RetType.RetType_Succeed){
let data = beautify(JSON.stringify(s2c), { indent_size: 2, space_in_empty_paren: true });
console.log(data);
}
})
.catch((error)=>{ console.log("error:", error); });
} else {
console.log("start error", msg);
}
};
websocket.start(addr, port, enable_ssl, key);
setTimeout(()=>{ websocket.stop(); process.exit(); }, 5000);
}
QotGetMacroIndicatorHistory()
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
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
- Output
GetMacroIndicatorHistory: errCode 0, retMsg , retType 0
{
"indicatorId": "1003000003",
"dataList": [
{ "dataTime": "2026-05-01", "value": 0.0642, "previousValue": 0.0566, "unitType": "PERCENT" },
{ "dataTime": "2026-04-01", "value": 0.0566, "previousValue": 0.0427, "unitType": "PERCENT" },
{ "dataTime": "2026-03-01", "value": 0.0427, "previousValue": 0.0338, "unitType": "PERCENT" }
]
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
API Limits
- Maximum 60 requests within 30 seconds
- Only the first page of paginated requests counts towards rate limiting