Merge branch 'main_260117_merge' into 'main'

feat: Add footprint interface

See merge request webull/webull-openapi-python-sdk!13

Author: 方佳

samples/__init__.py

@@ -1 +1 @@
-__version__ = '1.0.8'
+__version__ = '1.0.9'

samples/data/data_client.py

@@ -70,9 +70,9 @@
     if res.status_code == 200:
         print('get_batch_history_bar:', res.json())
 
-    res = data_client.market_data.get_tick("AAPL", Category.US_STOCK.name, trading_sessions=trading_sessions)
+    res = data_client.market_data.get_footprint("AAPL", Category.US_STOCK.name, Timespan.S5.name)
     if res.status_code == 200:
-        print('get_tick:', res.json())
+        print('get_footprint:', res.json())
 
     res = data_client.market_data.get_quotes("AAPL", Category.US_STOCK.name, depth=1, overnight_required=True)
     if res.status_code == 200:
@@ -90,9 +90,9 @@
     if res.status_code == 200:
         print('get_futures_tick:', res.json())
 
-    res = data_client.futures_market_data.get_futures_snapshot("SILZ5,6BM6", Category.US_FUTURES.name)
+    res = data_client.futures_market_data.get_futures_footprint("SILZ5,6BM6", Category.US_FUTURES.name, Timespan.S5.name)
     if res.status_code == 200:
-        print('get_futures_snapshot:', res.json())
+        print('get_futures_footprint:', res.json())
 
     res = data_client.instrument.get_futures_products(Category.US_FUTURES.name)
     if res.status_code == 200:

webull/__init__.py

@@ -1 +1 @@
-__version__ = '1.0.8'
+__version__ = '1.0.9'

webull/core/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '1.0.8'
+__version__ = '1.0.9'
 
 import logging
 

webull/data/__init__.py

@@ -1,3 +1,3 @@
 # coding=utf-8
 
-__version__ = '1.0.8'
+__version__ = '1.0.9'

webull/data/common/timespan.py

@@ -16,6 +16,8 @@
 
 from webull.core.common.easy_enum import EasyEnum
 class Timespan(EasyEnum):
+    S5 = (12, "5 Second")
+    S15= (13, "15 Second")
     M1 = (1, "1 minute")
     M5 = (2, "5 minute")
     M15 = (3, "15 minute")

webull/data/quotes/futures_market_data.py

@@ -11,8 +11,8 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
-
+from webull.data.common.category import Category
+from webull.data.request.get_futures_footprint_request import GetFuturesFootprintRequest
 from webull.data.request.get_futures_historical_bars_request import GetFuturesHistoricalBarsRequest
 from webull.data.request.get_futures_snapshot_request import GetFuturesSnapshotRequest
 from webull.data.request.get_futures_depth_request import GetFuturesDepthRequest
@@ -86,4 +86,26 @@ def get_futures_tick(self, symbol, category, count='200'):
         tick_request.set_category(category)
         tick_request.set_count(count)
         response = self.client.get_response(tick_request)
+        return response
+
+    def get_futures_footprint(self, symbols, category, timespan, count=None,
+                      real_time_required=None, trading_sessions=None):
+        """
+         Search the futures footprint based on the list of futures codes and futures types.
+
+        :param symbols: Futures Securities symbol, such as: BITH6,BITF26.
+        :param category: Security type, enumeration.
+        :param timespan: Time granularity.
+        :param count: Number of entries: 200 by default, maximum 1200.
+        :param real_time_required: Whether to include the latest data or candlestick charts that are not yet finalized. The default is false, meaning they are not included. This option is only used for minute candlestick charts.
+        :param trading_sessions: RTH: During trading hours, PRE: Before trading hours, ATH: After trading hours. Default: RTH.
+        """
+        footprint_request = GetFuturesFootprintRequest()
+        footprint_request.set_symbols(symbols)
+        footprint_request.set_category(category)
+        footprint_request.set_timespan(timespan)
+        footprint_request.set_count(count)
+        footprint_request.set_real_time_required(real_time_required)
+        footprint_request.set_trading_sessions(trading_sessions)
+        response = self.client.get_response(footprint_request)
         return response

webull/data/quotes/market_data.py

@@ -11,9 +11,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+from webull.data.common.category import Category
 from webull.data.request.get_batch_historical_bars_request import BatchHistoricalBarsRequest
 from webull.data.request.get_corp_action_request import GetCorpActionRequest
 from webull.data.request.get_eod_bars_request import GetEodBarsRequest
+from webull.data.request.get_footprint_request import GetFootprintRequest
 from webull.data.request.get_historical_bars_request import GetHistoricalBarsRequest
 from webull.data.request.get_quotes_request import GetQuotesRequest
 from webull.data.request.get_snapshot_request import GetSnapshotRequest
@@ -183,3 +185,25 @@ def get_corp_action(self, instrument_ids, event_types, start_date=None, end_date
             eod_corp_action_request.set_last_update_time(last_update_time)
         response = self.client.get_response(eod_corp_action_request)
         return response
+
+    def get_footprint(self, symbols, category, timespan, count=None,
+                      real_time_required=None, trading_sessions=None):
+        """
+         Search the footprint based on the list of security codes and security types.
+
+        :param symbols: Securities symbol, such as: 00700,00981.
+        :param category: Security type, enumeration.
+        :param timespan: Time granularity.
+        :param count: Number of entries: 200 by default, maximum 1200.
+        :param real_time_required: Whether to include the latest data or candlestick charts that are not yet finalized. The default is false, meaning they are not included. This option is only used for minute candlestick charts.
+        :param trading_sessions: RTH: During trading hours, PRE: Before trading hours, ATH: After trading hours. Default: RTH.
+        """
+        footprint_request = GetFootprintRequest()
+        footprint_request.set_symbols(symbols)
+        footprint_request.set_category(category)
+        footprint_request.set_timespan(timespan)
+        footprint_request.set_count(count)
+        footprint_request.set_real_time_required(real_time_required)
+        footprint_request.set_trading_sessions(trading_sessions)
+        response = self.client.get_response(footprint_request)
+        return response

webull/data/request/get_footprint_request.py

@@ -0,0 +1,45 @@
+# Copyright 2022 Webull
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# coding=utf-8
+from webull.core.request import ApiRequest
+
+class GetFootprintRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/market-data/stock/footprint", version='v2', method="GET", query_params={})
+
+    def set_symbols(self, symbols):
+        if isinstance(symbols, str):
+            self.add_query_param("symbols", symbols)
+        elif isinstance(symbols, list):
+            self.add_query_param("symbols", ",".join(symbols))
+
+    def set_category(self, category):
+        self.add_query_param("category", category)
+
+    def set_timespan(self, timespan):
+        if timespan:
+            self.add_query_param("timespan", timespan)
+
+    def set_count(self, count):
+        if count:
+            self.add_query_param("count", count)
+
+    def set_real_time_required(self, real_time_required):
+        if real_time_required:
+            self.add_query_param("real_time_required", real_time_required)
+
+    def set_trading_sessions(self, trading_sessions):
+        if trading_sessions:
+            self.add_query_param("trading_sessions", trading_sessions)

webull/data/request/get_futures_footprint_request.py

@@ -0,0 +1,45 @@
+# Copyright 2022 Webull
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# coding=utf-8
+from webull.core.request import ApiRequest
+
+class GetFuturesFootprintRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/market-data/futures/footprint", version='v2', method="GET", query_params={})
+
+    def set_symbols(self, symbols):
+        if isinstance(symbols, str):
+            self.add_query_param("symbols", symbols)
+        elif isinstance(symbols, list):
+            self.add_query_param("symbols", ",".join(symbols))
+
+    def set_category(self, category):
+        self.add_query_param("category", category)
+
+    def set_timespan(self, timespan):
+        if timespan:
+            self.add_query_param("timespan", timespan)
+
+    def set_count(self, count):
+        if count:
+            self.add_query_param("count", count)
+
+    def set_real_time_required(self, real_time_required):
+        if real_time_required:
+            self.add_query_param("real_time_required", real_time_required)
+
+    def set_trading_sessions(self, trading_sessions):
+        if trading_sessions:
+            self.add_query_param("trading_sessions", trading_sessions)