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.
Files changed (58) hide show
  1. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/PKG-INFO +30 -7
  2. 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
  3. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/__init__.py +1 -1
  4. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/book_scope.py +112 -59
  5. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/dataservices_catalog.py +33 -14
  6. 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
  7. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/LICENSE +0 -0
  8. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/MANIFEST.in +0 -0
  9. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/book_by_order.py +0 -0
  10. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/config.py +0 -0
  11. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/exceptions.py +0 -0
  12. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/__init__.py +0 -0
  13. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/algohunter.py +0 -0
  14. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_catalog.py +0 -0
  15. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_companies.py +0 -0
  16. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_funds.py +0 -0
  17. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py +0 -0
  18. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_metadata.py +0 -0
  19. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_ownership.py +0 -0
  20. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_people.py +0 -0
  21. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/authenticator.py +0 -0
  22. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/broker_analytics.py +0 -0
  23. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/broker_reference.py +0 -0
  24. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/bulk_data.py +0 -0
  25. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/company_data.py +0 -0
  26. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/corporate_events.py +0 -0
  27. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/hfn.py +0 -0
  28. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/historical_candles.py +0 -0
  29. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/historical_candles_crypto.py +0 -0
  30. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/intraday_candles.py +0 -0
  31. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/intraday_tick_data.py +0 -0
  32. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/market_events.py +0 -0
  33. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/public_sources.py +0 -0
  34. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/quotes.py +0 -0
  35. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/reference_data.py +0 -0
  36. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/stock_loan.py +0 -0
  37. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/ticker_last_event.py +0 -0
  38. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/ticker_last_event_polling.py +0 -0
  39. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/trades_and_book_events.py +0 -0
  40. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/__init__.py +0 -0
  41. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/broker_analytics.py +0 -0
  42. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/hfn_websocket_client.py +0 -0
  43. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/market_data_feed.py +0 -0
  44. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/market_data_websocket_client.py +0 -0
  45. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/realtime_book_events.py +0 -0
  46. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/websocket_default_functions.py +0 -0
  47. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/SOURCES.txt +0 -0
  48. {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
  49. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/requires.txt +3 -3
  50. {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
  51. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/pyproject.toml +0 -0
  52. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/requirements.txt +0 -0
  53. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/setup.cfg +0 -0
  54. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/setup.py +0 -0
  55. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/tests/test_book_by_order.py +0 -0
  56. {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
  57. {btgsolutions_dataservices_python_client-4.9.0 → btgsolutions_dataservices_python_client-4.9.1}/tests/test_realtime_book_events.py +0 -0
  58. {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.0
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
@@ -1,4 +1,4 @@
1
- __version__ = "4.9.0"
1
+ __version__ = "4.9.1"
2
2
 
3
3
  from .websocket import *
4
4
  from .rest import *
@@ -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
- ROW_LIMIT = 10000
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, book snapshots, book incremental)
20
- for a given symbol and time window.
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
- """Fetches all pages via rpt_seq cursor and returns a single combined parquet."""
52
- tables = []
53
- rpt_seq = None
54
-
55
- while True:
56
- page_params = {**params}
57
- if rpt_seq is not None:
58
- page_params["rpt_seq"] = rpt_seq
59
-
60
- response = requests.get(endpoint_url, params=page_params, headers=self.headers, timeout=50)
61
- if response.status_code != 200:
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
- select: List[str] = ["trades", "book_snapshot", "book_incremental"],
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, book snapshot and book incremental data for the given symbol and time window.
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: if the API returns the maximum number of rows
136
- (10 000), additional pages are fetched using the rpt_seq cursor until all events
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', 'book_incremental'].
157
- Allowed values: 'trades', 'book_snapshot', 'book_incremental'.
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
- ('trades', 'book_snapshot', 'book_incremental'), each mapping directly to
167
- a pandas.DataFrame with all rows for the requested time window.
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
- normalized_market_type = market_type.lower()
172
- if normalized_market_type not in VALID_MARKET_TYPES:
209
+ normalized_market = market.lower()
210
+ if normalized_market not in _MARKET_CONFIGS:
173
211
  raise ValueError(
174
- f"Invalid market_type: {market_type}. Valid options are: {VALID_MARKET_TYPES}"
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
- invalid = set(select) - VALID_SELECT_OPTIONS
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: {VALID_SELECT_OPTIONS}")
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, limit=ROW_LIMIT)
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
- "trades": f"{self.base_url}/marketdata/br/b3/book-scope/{scope}/{normalized_market_type}/trades",
196
- "book_snapshot": f"{self.base_url}/marketdata/br/b3/book-scope/{scope}/{normalized_market_type}/book-snapshot",
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, book snapshots and incremental book "
78
- "events for one symbol and a short time window. Use it for microstructure "
79
- "questions after a ticker, market_type and event window are known."
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 such "
209
- "as trades, book_snapshot and book_incremental. Timestamps are UTC ISO "
210
- "datetimes and the request window is capped at 10 minutes."
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/br/b3/book-scope/{scope}/{market_type}/{dataset}",
976
+ "path": "/v1/marketdata/{exchange_path}/book-scope/{scope}/{dataset}",
974
977
  "method": "GET",
975
978
  "client": "BookScope",
976
979
  "description": (
977
- "Return trades, book snapshots and/or incremental book events for "
978
- "one B3 symbol over a short ISO datetime window. The Python client "
979
- "chooses intraday or historical scope from end_time and paginates "
980
- "by rpt_seq."
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": "Ticker or symbol such as PETR4 or DOLM26.",
984
- "market_type": "Market segment: stocks, derivatives or options.",
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": "Datasets to return: trades, book_snapshot and/or book_incremental.",
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
@@ -1,6 +1,6 @@
1
- pandas>=2.2.2
2
- websocket-client>=1.8.0
3
1
  PyJWT>=2.8.0
4
- requests>=2.32.3
2
+ pandas>=2.2.2
5
3
  pyarrow>=17.0.0
4
+ requests>=2.32.3
6
5
  sortedcontainers>=2.4.0
6
+ websocket-client>=1.8.0