btgsolutions-dataservices-python-client 4.9.0__tar.gz → 4.9.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/PKG-INFO +30 -7
- btgsolutions_dataservices_python_client-4.9.0/btgsolutions_dataservices_python_client.egg-info/PKG-INFO → btgsolutions_dataservices_python_client-4.9.1/README.md +29 -16
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/__init__.py +1 -1
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/book_scope.py +112 -59
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/dataservices_catalog.py +33 -14
- btgsolutions_dataservices_python_client-4.9.0/README.md → btgsolutions_dataservices_python_client-4.9.1/btgsolutions_dataservices_python_client.egg-info/PKG-INFO +39 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/LICENSE +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/MANIFEST.in +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/book_by_order.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/config.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/exceptions.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/__init__.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/algohunter.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_catalog.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_companies.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_funds.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_metadata.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_ownership.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_people.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/authenticator.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/broker_analytics.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/broker_reference.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/bulk_data.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/company_data.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/corporate_events.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/hfn.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/historical_candles.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/historical_candles_crypto.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/intraday_candles.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/intraday_tick_data.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/market_events.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/public_sources.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/quotes.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/reference_data.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/stock_loan.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/ticker_last_event.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/ticker_last_event_polling.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/trades_and_book_events.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/__init__.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/broker_analytics.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/hfn_websocket_client.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/market_data_feed.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/market_data_websocket_client.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/realtime_book_events.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/websocket_default_functions.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/SOURCES.txt +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/dependency_links.txt +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/requires.txt +3 -3
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/top_level.txt +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/pyproject.toml +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/requirements.txt +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/setup.cfg +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/setup.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/tests/test_book_by_order.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/tests/test_market_data_websocket_client_book_events.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/tests/test_realtime_book_events.py +0 -0
- {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/tests/test_trades_and_book_events.py +0 -0
|
@@ -1,18 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: btgsolutions_dataservices_python_client
|
|
3
|
-
Version: 4.9.
|
|
3
|
+
Version: 4.9.1
|
|
4
4
|
Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
|
|
5
5
|
Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
|
|
6
6
|
Author: BTG Solutions Data Services powered by BTG Pactual Solutions
|
|
7
7
|
Requires-Python: >=3.9,<3.15
|
|
8
8
|
Description-Content-Type: text/markdown
|
|
9
9
|
License-File: LICENSE
|
|
10
|
-
Requires-Dist: pandas>=2.2.2
|
|
11
|
-
Requires-Dist: websocket-client>=1.8.0
|
|
12
|
-
Requires-Dist: PyJWT>=2.8.0
|
|
13
|
-
Requires-Dist: requests>=2.32.3
|
|
14
|
-
Requires-Dist: pyarrow>=17.0.0
|
|
15
|
-
Requires-Dist: sortedcontainers>=2.4.0
|
|
16
10
|
|
|
17
11
|
# BTG Solutions - Data Services
|
|
18
12
|
|
|
@@ -848,6 +842,35 @@ single_file_result = book_scope.get(
|
|
|
848
842
|
)
|
|
849
843
|
```
|
|
850
844
|
|
|
845
|
+
##### Book Scope, NUAM Colombia / NUAM Chile / BIVA (Mexico) / BMV (Mexico)
|
|
846
|
+
|
|
847
|
+
These exchanges expose a single combined `book` dataset instead of B3's
|
|
848
|
+
`book_snapshot`/`book_incremental` split (every row already carries the full
|
|
849
|
+
bid/ask state), and take no `market_type` parameter.
|
|
850
|
+
|
|
851
|
+
```python
|
|
852
|
+
import btgsolutions_dataservices as btg
|
|
853
|
+
book_scope = btg.BookScope(api_key='YOUR_API_KEY')
|
|
854
|
+
|
|
855
|
+
# NUAM Colombia
|
|
856
|
+
book_scope.get(
|
|
857
|
+
symbol='PFDAVIGRP',
|
|
858
|
+
market='nuam_colombia',
|
|
859
|
+
start_time='2026-05-28T14:12:00Z',
|
|
860
|
+
end_time='2026-05-28T14:15:00Z',
|
|
861
|
+
select=['trades', 'book'], # choose one or both; default is both
|
|
862
|
+
)
|
|
863
|
+
|
|
864
|
+
# NUAM Chile
|
|
865
|
+
book_scope.get(symbol='<TICKER>', market='nuam_chile', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
866
|
+
|
|
867
|
+
# BIVA (Mexico)
|
|
868
|
+
book_scope.get(symbol='<TICKER>', market='biva_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
869
|
+
|
|
870
|
+
# BMV (Mexico)
|
|
871
|
+
book_scope.get(symbol='<TICKER>', market='bmv_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
872
|
+
```
|
|
873
|
+
|
|
851
874
|
#### Broker Analytics
|
|
852
875
|
|
|
853
876
|
```python
|
|
@@ -1,19 +1,3 @@
|
|
|
1
|
-
Metadata-Version: 2.1
|
|
2
|
-
Name: btgsolutions_dataservices_python_client
|
|
3
|
-
Version: 4.9.0
|
|
4
|
-
Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
|
|
5
|
-
Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
|
|
6
|
-
Author: BTG Solutions Data Services powered by BTG Pactual Solutions
|
|
7
|
-
Requires-Python: >=3.9,<3.15
|
|
8
|
-
Description-Content-Type: text/markdown
|
|
9
|
-
License-File: LICENSE
|
|
10
|
-
Requires-Dist: pandas>=2.2.2
|
|
11
|
-
Requires-Dist: websocket-client>=1.8.0
|
|
12
|
-
Requires-Dist: PyJWT>=2.8.0
|
|
13
|
-
Requires-Dist: requests>=2.32.3
|
|
14
|
-
Requires-Dist: pyarrow>=17.0.0
|
|
15
|
-
Requires-Dist: sortedcontainers>=2.4.0
|
|
16
|
-
|
|
17
1
|
# BTG Solutions - Data Services
|
|
18
2
|
|
|
19
3
|
Real time and historical Financial Market Data, News, Corporate Events and more.
|
|
@@ -848,6 +832,35 @@ single_file_result = book_scope.get(
|
|
|
848
832
|
)
|
|
849
833
|
```
|
|
850
834
|
|
|
835
|
+
##### Book Scope, NUAM Colombia / NUAM Chile / BIVA (Mexico) / BMV (Mexico)
|
|
836
|
+
|
|
837
|
+
These exchanges expose a single combined `book` dataset instead of B3's
|
|
838
|
+
`book_snapshot`/`book_incremental` split (every row already carries the full
|
|
839
|
+
bid/ask state), and take no `market_type` parameter.
|
|
840
|
+
|
|
841
|
+
```python
|
|
842
|
+
import btgsolutions_dataservices as btg
|
|
843
|
+
book_scope = btg.BookScope(api_key='YOUR_API_KEY')
|
|
844
|
+
|
|
845
|
+
# NUAM Colombia
|
|
846
|
+
book_scope.get(
|
|
847
|
+
symbol='PFDAVIGRP',
|
|
848
|
+
market='nuam_colombia',
|
|
849
|
+
start_time='2026-05-28T14:12:00Z',
|
|
850
|
+
end_time='2026-05-28T14:15:00Z',
|
|
851
|
+
select=['trades', 'book'], # choose one or both; default is both
|
|
852
|
+
)
|
|
853
|
+
|
|
854
|
+
# NUAM Chile
|
|
855
|
+
book_scope.get(symbol='<TICKER>', market='nuam_chile', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
856
|
+
|
|
857
|
+
# BIVA (Mexico)
|
|
858
|
+
book_scope.get(symbol='<TICKER>', market='biva_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
859
|
+
|
|
860
|
+
# BMV (Mexico)
|
|
861
|
+
book_scope.get(symbol='<TICKER>', market='bmv_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
862
|
+
```
|
|
863
|
+
|
|
851
864
|
#### Broker Analytics
|
|
852
865
|
|
|
853
866
|
```python
|
|
@@ -8,18 +8,57 @@ from io import BytesIO
|
|
|
8
8
|
import pyarrow as pa
|
|
9
9
|
import pyarrow.parquet as pq
|
|
10
10
|
|
|
11
|
-
VALID_SELECT_OPTIONS = {"trades", "book_snapshot", "book_incremental"}
|
|
12
11
|
VALID_MARKET_TYPES = {"derivatives", "options", "stocks"}
|
|
13
12
|
MAX_MARKET_SCOPE_WINDOW = timedelta(minutes=10)
|
|
14
|
-
|
|
13
|
+
DEFAULT_ROW_LIMIT = 10000
|
|
14
|
+
|
|
15
|
+
# One entry per exchange covered by the book-scope service. "path_prefix" is the
|
|
16
|
+
# "/marketdata/<prefix>/book-scope" segment; "datasets" maps each select option to
|
|
17
|
+
# its URL dataset segment. B3 is the only market with a market_type path segment
|
|
18
|
+
# and a 3-way split between trades, book_snapshot and book_incremental. NUAM
|
|
19
|
+
# Colombia, NUAM Chile, BIVA (Mexico) and BMV (Mexico) share the same shape: no
|
|
20
|
+
# market_type segment, and a single "book" dataset instead of a snapshot/incremental
|
|
21
|
+
# split (every row from those exchanges already carries the full bid/ask state).
|
|
22
|
+
_MARKET_CONFIGS = {
|
|
23
|
+
"b3": {
|
|
24
|
+
"path_prefix": "br/b3",
|
|
25
|
+
"requires_market_type": True,
|
|
26
|
+
"datasets": {
|
|
27
|
+
"trades": "trades",
|
|
28
|
+
"book_snapshot": "book-snapshot",
|
|
29
|
+
"book_incremental": "book-incremental",
|
|
30
|
+
},
|
|
31
|
+
},
|
|
32
|
+
"nuam_colombia": {
|
|
33
|
+
"path_prefix": "co/nuam",
|
|
34
|
+
"requires_market_type": False,
|
|
35
|
+
"datasets": {"trades": "trades", "book": "book"},
|
|
36
|
+
},
|
|
37
|
+
"nuam_chile": {
|
|
38
|
+
"path_prefix": "cl/nuam",
|
|
39
|
+
"requires_market_type": False,
|
|
40
|
+
"datasets": {"trades": "trades", "book": "book"},
|
|
41
|
+
},
|
|
42
|
+
"biva_mexico": {
|
|
43
|
+
"path_prefix": "mx/biva",
|
|
44
|
+
"requires_market_type": False,
|
|
45
|
+
"datasets": {"trades": "trades", "book": "book"},
|
|
46
|
+
},
|
|
47
|
+
"bmv_mexico": {
|
|
48
|
+
"path_prefix": "mx/bmv",
|
|
49
|
+
"requires_market_type": False,
|
|
50
|
+
"datasets": {"trades": "trades", "book": "book"},
|
|
51
|
+
},
|
|
52
|
+
}
|
|
15
53
|
|
|
16
54
|
|
|
17
55
|
class BookScope:
|
|
18
56
|
"""
|
|
19
|
-
This class provides market scope data (trades
|
|
20
|
-
|
|
57
|
+
This class provides market scope data (trades and book state) for a given
|
|
58
|
+
symbol and time window, across B3 (Brazil), NUAM Colombia, NUAM Chile,
|
|
59
|
+
BIVA (Mexico) and BMV (Mexico).
|
|
21
60
|
|
|
22
|
-
* Main use case:
|
|
61
|
+
* Main use case (B3):
|
|
23
62
|
|
|
24
63
|
>>> from btgsolutions_dataservices import BookScope
|
|
25
64
|
>>> book_scope = BookScope(
|
|
@@ -32,6 +71,15 @@ class BookScope:
|
|
|
32
71
|
>>> end_time='2026-05-28T14:15:00Z',
|
|
33
72
|
>>> )
|
|
34
73
|
|
|
74
|
+
* NUAM Colombia / NUAM Chile / BIVA (Mexico) / BMV (Mexico):
|
|
75
|
+
|
|
76
|
+
>>> book_scope.get(
|
|
77
|
+
>>> symbol='PFDAVIGRP',
|
|
78
|
+
>>> market='nuam_colombia',
|
|
79
|
+
>>> start_time='2026-05-28T14:12:00Z',
|
|
80
|
+
>>> end_time='2026-05-28T14:15:00Z',
|
|
81
|
+
>>> )
|
|
82
|
+
|
|
35
83
|
Parameters
|
|
36
84
|
----------------
|
|
37
85
|
api_key: str
|
|
@@ -48,35 +96,17 @@ class BookScope:
|
|
|
48
96
|
self.base_url = url_api_v1
|
|
49
97
|
|
|
50
98
|
def _fetch_all_pages(self, endpoint_url: str, params: dict) -> bytes:
|
|
51
|
-
"""
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
try:
|
|
63
|
-
error_body = response.json()
|
|
64
|
-
detail = error_body.get("detail", error_body.get("error", response.text))
|
|
65
|
-
except Exception:
|
|
66
|
-
detail = response.text
|
|
67
|
-
raise BadResponse(f"Error: {detail}")
|
|
68
|
-
|
|
69
|
-
table = pq.read_table(BytesIO(response.content))
|
|
70
|
-
tables.append(table)
|
|
71
|
-
|
|
72
|
-
if table.num_rows < ROW_LIMIT:
|
|
73
|
-
break
|
|
74
|
-
rpt_seq = table.column("rpt_seq")[-1].as_py()
|
|
75
|
-
|
|
76
|
-
combined = pa.concat_tables(tables)
|
|
77
|
-
buffer = BytesIO()
|
|
78
|
-
pq.write_table(combined, buffer)
|
|
79
|
-
return buffer.getvalue()
|
|
99
|
+
"""Sends a single request with the default row limit; the server paginates internally."""
|
|
100
|
+
page_params = {**params, "limit": DEFAULT_ROW_LIMIT}
|
|
101
|
+
response = requests.get(endpoint_url, params=page_params, headers=self.headers)
|
|
102
|
+
if response.status_code != 200:
|
|
103
|
+
try:
|
|
104
|
+
error_body = response.json()
|
|
105
|
+
detail = error_body.get("detail", error_body.get("error", response.text))
|
|
106
|
+
except Exception:
|
|
107
|
+
detail = response.text
|
|
108
|
+
raise BadResponse(f"Error: {detail}")
|
|
109
|
+
return response.content
|
|
80
110
|
|
|
81
111
|
@staticmethod
|
|
82
112
|
def _combine_parquets(parquet_payloads: List[bytes]) -> bytes:
|
|
@@ -123,38 +153,46 @@ class BookScope:
|
|
|
123
153
|
def get(
|
|
124
154
|
self,
|
|
125
155
|
symbol: str,
|
|
126
|
-
market_type: str,
|
|
127
156
|
start_time: str,
|
|
128
157
|
end_time: str,
|
|
129
|
-
|
|
158
|
+
market: str = "b3",
|
|
159
|
+
market_type: Optional[str] = None,
|
|
160
|
+
select: Optional[List[str]] = None,
|
|
130
161
|
aggregate_info: bool = False,
|
|
131
162
|
):
|
|
132
163
|
"""
|
|
133
|
-
Returns trades
|
|
164
|
+
Returns trades and book state data for the given symbol and time window,
|
|
165
|
+
on the requested market/exchange.
|
|
134
166
|
|
|
135
|
-
Pagination is handled automatically
|
|
136
|
-
|
|
137
|
-
in the requested horizon are retrieved. The caller always receives a single,
|
|
138
|
-
complete DataFrame per dataset.
|
|
167
|
+
Pagination is handled automatically by the API. The caller always receives
|
|
168
|
+
a single, complete parquet file per dataset.
|
|
139
169
|
|
|
140
170
|
Parameters
|
|
141
171
|
----------------
|
|
142
172
|
symbol: str
|
|
143
173
|
The ticker symbol to query.
|
|
144
|
-
Field is required. Example: 'PETR4', 'DOLM26'.
|
|
145
|
-
market_type: str
|
|
146
|
-
Market type.
|
|
147
|
-
Field is required. Allowed values: 'derivatives', 'options', 'stocks'.
|
|
174
|
+
Field is required. Example: 'PETR4', 'DOLM26' (B3), 'PFDAVIGRP' (NUAM Colombia).
|
|
148
175
|
start_time: str
|
|
149
176
|
Start of the analysis window in ISO-8601 UTC format.
|
|
150
177
|
Field is required. Example: '2026-05-28T14:12:00Z'.
|
|
151
178
|
end_time: str
|
|
152
179
|
End of the analysis window in ISO-8601 UTC format.
|
|
153
180
|
Field is required. Example: '2026-05-28T14:15:00Z'.
|
|
181
|
+
market: str
|
|
182
|
+
Exchange to query.
|
|
183
|
+
Field is optional. Default: 'b3'.
|
|
184
|
+
Allowed values: 'b3' (Brazil), 'nuam_colombia', 'nuam_chile',
|
|
185
|
+
'biva_mexico', 'bmv_mexico'.
|
|
186
|
+
market_type: str
|
|
187
|
+
Market type. Only used (and required) when market='b3'; ignored for
|
|
188
|
+
every other market.
|
|
189
|
+
Allowed values: 'derivatives', 'options', 'stocks'.
|
|
154
190
|
select: list of str
|
|
155
191
|
Which datasets to return.
|
|
156
|
-
Field is optional. Default: ['trades', 'book_snapshot',
|
|
157
|
-
|
|
192
|
+
Field is optional. Default: for market='b3', ['trades', 'book_snapshot',
|
|
193
|
+
'book_incremental']; for every other market, ['trades', 'book'].
|
|
194
|
+
Allowed values: 'trades', 'book_snapshot', 'book_incremental' (market='b3'
|
|
195
|
+
only) or 'trades', 'book' (every other market).
|
|
158
196
|
aggregate_info: bool
|
|
159
197
|
When True, returns a single pandas.DataFrame containing the selected datasets.
|
|
160
198
|
Field is optional. Default: False.
|
|
@@ -162,21 +200,37 @@ class BookScope:
|
|
|
162
200
|
Returns
|
|
163
201
|
----------------
|
|
164
202
|
dict or pandas.DataFrame
|
|
165
|
-
When aggregate_info is False (default): dictionary with the selected keys
|
|
166
|
-
|
|
167
|
-
|
|
203
|
+
When aggregate_info is False (default): dictionary with the selected keys,
|
|
204
|
+
each mapping directly to a pandas.DataFrame with all rows for the requested
|
|
205
|
+
time window.
|
|
168
206
|
When aggregate_info is True: returns a single pandas.DataFrame with all
|
|
169
207
|
selected datasets combined.
|
|
170
208
|
"""
|
|
171
|
-
|
|
172
|
-
if
|
|
209
|
+
normalized_market = market.lower()
|
|
210
|
+
if normalized_market not in _MARKET_CONFIGS:
|
|
173
211
|
raise ValueError(
|
|
174
|
-
f"Invalid
|
|
212
|
+
f"Invalid market: {market}. Valid options are: {sorted(_MARKET_CONFIGS)}"
|
|
175
213
|
)
|
|
214
|
+
config = _MARKET_CONFIGS[normalized_market]
|
|
215
|
+
|
|
216
|
+
if config["requires_market_type"]:
|
|
217
|
+
if not market_type:
|
|
218
|
+
raise ValueError(f"market_type is required when market='{normalized_market}'.")
|
|
219
|
+
normalized_market_type = market_type.lower()
|
|
220
|
+
if normalized_market_type not in VALID_MARKET_TYPES:
|
|
221
|
+
raise ValueError(
|
|
222
|
+
f"Invalid market_type: {market_type}. Valid options are: {VALID_MARKET_TYPES}"
|
|
223
|
+
)
|
|
224
|
+
path_prefix = f"{config['path_prefix']}/book-scope/{{scope}}/{normalized_market_type}"
|
|
225
|
+
else:
|
|
226
|
+
path_prefix = f"{config['path_prefix']}/book-scope/{{scope}}"
|
|
176
227
|
|
|
177
|
-
|
|
228
|
+
valid_select_options = set(config["datasets"])
|
|
229
|
+
if select is None:
|
|
230
|
+
select = list(config["datasets"])
|
|
231
|
+
invalid = set(select) - valid_select_options
|
|
178
232
|
if invalid:
|
|
179
|
-
raise ValueError(f"Invalid select options: {invalid}. Valid options are: {
|
|
233
|
+
raise ValueError(f"Invalid select options: {invalid}. Valid options are: {valid_select_options}")
|
|
180
234
|
|
|
181
235
|
parsed_start_time = self._parse_iso8601(start_time, "start_time")
|
|
182
236
|
parsed_end_time = self._parse_iso8601(end_time, "end_time")
|
|
@@ -187,14 +241,13 @@ class BookScope:
|
|
|
187
241
|
if parsed_end_time - parsed_start_time > MAX_MARKET_SCOPE_WINDOW:
|
|
188
242
|
raise ValueError("The maximum allowed range between start_time and end_time is 10 minutes.")
|
|
189
243
|
|
|
190
|
-
base_params = dict(symbol=symbol, start_time=start_time, end_time=end_time
|
|
244
|
+
base_params = dict(symbol=symbol, start_time=start_time, end_time=end_time)
|
|
191
245
|
|
|
192
246
|
scope = self._resolve_scope(parsed_end_time)
|
|
193
247
|
|
|
194
248
|
endpoint_map = {
|
|
195
|
-
|
|
196
|
-
"
|
|
197
|
-
"book_incremental": f"{self.base_url}/marketdata/br/b3/book-scope/{scope}/{normalized_market_type}/book-incremental",
|
|
249
|
+
key: f"{self.base_url}/marketdata/{path_prefix.format(scope=scope)}/{dataset}"
|
|
250
|
+
for key, dataset in config["datasets"].items()
|
|
198
251
|
}
|
|
199
252
|
|
|
200
253
|
result = {}
|
|
@@ -74,9 +74,10 @@ DATASERVICES_ENDPOINT_RELATIONSHIPS: dict[str, str] = {
|
|
|
74
74
|
"requesting ticker/date bulk data or compressed market-data files."
|
|
75
75
|
),
|
|
76
76
|
"book_scope_microstructure": (
|
|
77
|
-
"get_book_scope combines trades
|
|
78
|
-
"
|
|
79
|
-
"questions after a ticker,
|
|
77
|
+
"get_book_scope combines trades and book state for one symbol and a "
|
|
78
|
+
"short time window, on B3, NUAM Colombia, NUAM Chile, BIVA (Mexico) or "
|
|
79
|
+
"BMV (Mexico). Use it for microstructure questions after a ticker, "
|
|
80
|
+
"market/market_type and event window are known."
|
|
80
81
|
),
|
|
81
82
|
"company_identifier_bridge": (
|
|
82
83
|
"Use search_companies or resolve_company_identifier to translate company "
|
|
@@ -205,9 +206,11 @@ DATASERVICES_RESULT_CONTRACTS: dict[str, str] = {
|
|
|
205
206
|
"position or inventory database."
|
|
206
207
|
),
|
|
207
208
|
"book_scope": (
|
|
208
|
-
"MCP result is a dataset handle with selected book-scope datasets
|
|
209
|
-
"
|
|
210
|
-
"
|
|
209
|
+
"MCP result is a dataset handle with selected book-scope datasets: "
|
|
210
|
+
"trades, book_snapshot and book_incremental for B3, or trades and book "
|
|
211
|
+
"for NUAM Colombia, NUAM Chile, BIVA (Mexico) and BMV (Mexico). "
|
|
212
|
+
"Timestamps are UTC ISO datetimes and the request window is capped at "
|
|
213
|
+
"10 minutes."
|
|
211
214
|
),
|
|
212
215
|
}
|
|
213
216
|
|
|
@@ -970,21 +973,37 @@ DATASERVICES_ENDPOINTS: dict[str, dict[str, Any]] = {
|
|
|
970
973
|
},
|
|
971
974
|
"BookScope.get": {
|
|
972
975
|
"category": "book_scope",
|
|
973
|
-
"path": "/v1/marketdata/
|
|
976
|
+
"path": "/v1/marketdata/{exchange_path}/book-scope/{scope}/{dataset}",
|
|
974
977
|
"method": "GET",
|
|
975
978
|
"client": "BookScope",
|
|
976
979
|
"description": (
|
|
977
|
-
"Return trades
|
|
978
|
-
"one
|
|
979
|
-
"
|
|
980
|
-
"
|
|
980
|
+
"Return trades and book state (plus, for B3 only, a separate "
|
|
981
|
+
"incremental book feed) for one symbol over a short ISO datetime "
|
|
982
|
+
"window, on B3 (Brazil), NUAM Colombia, NUAM Chile, BIVA (Mexico) or "
|
|
983
|
+
"BMV (Mexico). The Python client chooses intraday or historical scope "
|
|
984
|
+
"from end_time and the server paginates internally."
|
|
981
985
|
),
|
|
982
986
|
"parameters": {
|
|
983
|
-
"symbol":
|
|
984
|
-
|
|
987
|
+
"symbol": (
|
|
988
|
+
"Ticker or symbol such as PETR4 or DOLM26 (B3) or PFDAVIGRP "
|
|
989
|
+
"(NUAM Colombia)."
|
|
990
|
+
),
|
|
991
|
+
"market": (
|
|
992
|
+
"Exchange to query: b3 (default), nuam_colombia, nuam_chile, "
|
|
993
|
+
"biva_mexico or bmv_mexico."
|
|
994
|
+
),
|
|
995
|
+
"market_type": (
|
|
996
|
+
"Market segment: stocks, derivatives or options. Required only "
|
|
997
|
+
"when market=b3; unused for every other market."
|
|
998
|
+
),
|
|
985
999
|
"start_time": "UTC ISO datetime such as 2026-05-28T14:12:00Z.",
|
|
986
1000
|
"end_time": "UTC ISO datetime such as 2026-05-28T14:15:00Z.",
|
|
987
|
-
"select":
|
|
1001
|
+
"select": (
|
|
1002
|
+
"Datasets to return. For market=b3: trades, book_snapshot "
|
|
1003
|
+
"and/or book_incremental. For every other market: trades "
|
|
1004
|
+
"and/or book (a single dataset already carrying full bid/ask "
|
|
1005
|
+
"state, since those exchanges have no separate snapshot step)."
|
|
1006
|
+
),
|
|
988
1007
|
"aggregate_info": "If true, combine selected datasets into one table.",
|
|
989
1008
|
},
|
|
990
1009
|
"relationships": [
|
|
@@ -1,3 +1,13 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: btgsolutions-dataservices-python-client
|
|
3
|
+
Version: 4.9.1
|
|
4
|
+
Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
|
|
5
|
+
Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
|
|
6
|
+
Author: BTG Solutions Data Services powered by BTG Pactual Solutions
|
|
7
|
+
Requires-Python: >=3.9,<3.15
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
|
|
1
11
|
# BTG Solutions - Data Services
|
|
2
12
|
|
|
3
13
|
Real time and historical Financial Market Data, News, Corporate Events and more.
|
|
@@ -832,6 +842,35 @@ single_file_result = book_scope.get(
|
|
|
832
842
|
)
|
|
833
843
|
```
|
|
834
844
|
|
|
845
|
+
##### Book Scope, NUAM Colombia / NUAM Chile / BIVA (Mexico) / BMV (Mexico)
|
|
846
|
+
|
|
847
|
+
These exchanges expose a single combined `book` dataset instead of B3's
|
|
848
|
+
`book_snapshot`/`book_incremental` split (every row already carries the full
|
|
849
|
+
bid/ask state), and take no `market_type` parameter.
|
|
850
|
+
|
|
851
|
+
```python
|
|
852
|
+
import btgsolutions_dataservices as btg
|
|
853
|
+
book_scope = btg.BookScope(api_key='YOUR_API_KEY')
|
|
854
|
+
|
|
855
|
+
# NUAM Colombia
|
|
856
|
+
book_scope.get(
|
|
857
|
+
symbol='PFDAVIGRP',
|
|
858
|
+
market='nuam_colombia',
|
|
859
|
+
start_time='2026-05-28T14:12:00Z',
|
|
860
|
+
end_time='2026-05-28T14:15:00Z',
|
|
861
|
+
select=['trades', 'book'], # choose one or both; default is both
|
|
862
|
+
)
|
|
863
|
+
|
|
864
|
+
# NUAM Chile
|
|
865
|
+
book_scope.get(symbol='<TICKER>', market='nuam_chile', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
866
|
+
|
|
867
|
+
# BIVA (Mexico)
|
|
868
|
+
book_scope.get(symbol='<TICKER>', market='biva_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
869
|
+
|
|
870
|
+
# BMV (Mexico)
|
|
871
|
+
book_scope.get(symbol='<TICKER>', market='bmv_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
|
|
872
|
+
```
|
|
873
|
+
|
|
835
874
|
#### Broker Analytics
|
|
836
875
|
|
|
837
876
|
```python
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|