btgsolutions-dataservices-python-client 4.5.1__tar.gz → 4.6.0__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 (49) hide show
  1. {btgsolutions_dataservices_python_client-4.5.1/btgsolutions_dataservices_python_client.egg-info → btgsolutions_dataservices_python_client-4.6.0}/PKG-INFO +11 -15
  2. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/README.md +122 -113
  3. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/__init__.py +1 -1
  4. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/bulk_data.py +40 -2
  5. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0/btgsolutions_dataservices_python_client.egg-info}/PKG-INFO +12 -16
  6. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/LICENSE +0 -0
  7. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/MANIFEST.in +0 -0
  8. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/config.py +0 -0
  9. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/exceptions.py +0 -0
  10. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/__init__.py +0 -0
  11. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/alternative_data_catalog.py +0 -0
  12. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/alternative_data_companies.py +0 -0
  13. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/alternative_data_funds.py +0 -0
  14. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py +0 -0
  15. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/alternative_data_metadata.py +0 -0
  16. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/alternative_data_ownership.py +0 -0
  17. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/alternative_data_people.py +0 -0
  18. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/authenticator.py +0 -0
  19. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/book_scope.py +0 -0
  20. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/broker_analytics.py +0 -0
  21. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/broker_reference.py +0 -0
  22. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/company_data.py +0 -0
  23. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/corporate_events.py +0 -0
  24. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/dataservices_catalog.py +0 -0
  25. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/hfn.py +0 -0
  26. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/historical_candles.py +0 -0
  27. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/historical_candles_crypto.py +0 -0
  28. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/intraday_candles.py +0 -0
  29. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/intraday_tick_data.py +0 -0
  30. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/public_sources.py +0 -0
  31. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/quotes.py +0 -0
  32. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/reference_data.py +0 -0
  33. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/stock_loan.py +0 -0
  34. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/ticker_last_event.py +0 -0
  35. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/rest/ticker_last_event_polling.py +0 -0
  36. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/websocket/__init__.py +0 -0
  37. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/websocket/broker_analytics.py +0 -0
  38. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/websocket/hfn_websocket_client.py +0 -0
  39. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/websocket/market_data_feed.py +0 -0
  40. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/websocket/market_data_websocket_client.py +0 -0
  41. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices/websocket/websocket_default_functions.py +0 -0
  42. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices_python_client.egg-info/SOURCES.txt +0 -0
  43. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices_python_client.egg-info/dependency_links.txt +0 -0
  44. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices_python_client.egg-info/requires.txt +0 -0
  45. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/btgsolutions_dataservices_python_client.egg-info/top_level.txt +0 -0
  46. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/pyproject.toml +0 -0
  47. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/requirements.txt +0 -0
  48. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/setup.cfg +0 -0
  49. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.6.0}/setup.py +0 -0
@@ -1,25 +1,12 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.1
2
2
  Name: btgsolutions_dataservices_python_client
3
- Version: 4.5.1
3
+ Version: 4.6.0
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
- Dynamic: author
16
- Dynamic: description
17
- Dynamic: description-content-type
18
- Dynamic: home-page
19
- Dynamic: license-file
20
- Dynamic: requires-dist
21
- Dynamic: requires-python
22
- Dynamic: summary
23
10
 
24
11
  # BTG Solutions - Data Services
25
12
 
@@ -351,6 +338,15 @@ bulk_data.get_data(ticker='DI1F18', date='2017-01-02', data_type='trades')
351
338
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='instrument-status')
352
339
  ```
353
340
 
341
+ ##### Get Data With Billing Headers
342
+
343
+ ```python
344
+ import btgsolutions_dataservices as btg
345
+ bulk_data = btg.BulkData(api_key='YOUR_API_KEY')
346
+ df, billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', return_billing_headers=True)
347
+ # billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', dry_run=True)
348
+ ```
349
+
354
350
  ##### Security List
355
351
 
356
352
  ```python
@@ -328,6 +328,15 @@ bulk_data.get_data(ticker='DI1F18', date='2017-01-02', data_type='trades')
328
328
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='instrument-status')
329
329
  ```
330
330
 
331
+ ##### Get Data With Billing Headers
332
+
333
+ ```python
334
+ import btgsolutions_dataservices as btg
335
+ bulk_data = btg.BulkData(api_key='YOUR_API_KEY')
336
+ df, billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', return_billing_headers=True)
337
+ # billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', dry_run=True)
338
+ ```
339
+
331
340
  ##### Security List
332
341
 
333
342
  ```python
@@ -494,71 +503,71 @@ company_data.interims(ticker='PETR4')
494
503
 
495
504
  ```python
496
505
  import btgsolutions_dataservices as btg
497
- company_data = btg.CompanyData(api_key='YOUR_API_KEY')
498
- company_data.all_financial_tables(ticker='PETR4')
499
- ```
500
-
501
- #### REST Technical Catalogs
502
-
503
- Technical endpoint descriptions for REST APIs are exported by the package so
504
- MCPs and other connectors can reuse the same source of truth instead of
505
- duplicating endpoint semantics locally.
506
-
507
- ```python
508
- from btgsolutions_dataservices.rest import (
509
- DATASERVICES_ENDPOINTS,
510
- DATASERVICES_ENDPOINT_RELATIONSHIPS,
511
- get_dataservices_tool_description,
512
- )
513
-
514
- print(get_dataservices_tool_description("get_quotes"))
515
- print(get_dataservices_tool_description("get_book_scope"))
516
- ```
517
-
518
- The Data Services catalog covers quotes, candles, intraday trades, last events,
519
- reference data, corporate events, company fundamental data, HFN news,
520
- stock-loan data, bulk market data, broker reference, broker analytics and
521
- book-scope endpoints. It documents parameters, endpoint relationships such as
522
- available-ticker discovery before market-data calls, broker-reference discovery
523
- before broker analytics, HFN filter discovery before news queries, corporate
524
- events before adjusted price analysis, and book-scope constraints for
525
- microstructure analysis.
526
-
527
- The REST catalogs also document cross-domain relationships between Public
528
- Sources and market-data services: company directory resolution feeds ticker
529
- reference, quotes, candles, stock-loan, broker analytics and book-scope tools;
530
- sector classification feeds peer-market comparisons; fund holdings feed
531
- underlying ticker market analysis; ownership/free-float feeds liquidity context;
532
- and disclosures, official notices, HFN news and corporate events feed event
533
- window analysis.
534
-
535
- #### Alternative Data - Metadata
536
-
537
- Technical endpoint descriptions for the public-sources alternative-data APIs are
538
- exported by the package so MCPs and other connectors can reuse the same source
539
- of truth:
540
-
541
- ```python
542
- from btgsolutions_dataservices.rest import (
543
- PUBLIC_SOURCES_ENDPOINTS,
544
- PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS,
545
- get_public_sources_tool_description,
546
- )
547
-
548
- print(get_public_sources_tool_description("get_company_board"))
549
- ```
550
-
551
- The catalog documents endpoint parameters, known data gaps, excluded endpoints,
552
- and relationships such as: company metadata resolving identifiers for governance
553
- and ownership calls; macro indicator metadata feeding macro observations; asset
554
- metadata feeding maximum-theoretical-margin calls; financial statement type
555
- metadata feeding statement queries; assemblies and ownership notices feeding
556
- notice summaries; and fund holdings/asset fund holders linking funds with
557
- company tickers.
558
-
559
- ```python
560
- import btgsolutions_dataservices as btg
561
- meta = btg.AlternativeDataMetadata(api_key='YOUR_API_KEY')
506
+ company_data = btg.CompanyData(api_key='YOUR_API_KEY')
507
+ company_data.all_financial_tables(ticker='PETR4')
508
+ ```
509
+
510
+ #### REST Technical Catalogs
511
+
512
+ Technical endpoint descriptions for REST APIs are exported by the package so
513
+ MCPs and other connectors can reuse the same source of truth instead of
514
+ duplicating endpoint semantics locally.
515
+
516
+ ```python
517
+ from btgsolutions_dataservices.rest import (
518
+ DATASERVICES_ENDPOINTS,
519
+ DATASERVICES_ENDPOINT_RELATIONSHIPS,
520
+ get_dataservices_tool_description,
521
+ )
522
+
523
+ print(get_dataservices_tool_description("get_quotes"))
524
+ print(get_dataservices_tool_description("get_book_scope"))
525
+ ```
526
+
527
+ The Data Services catalog covers quotes, candles, intraday trades, last events,
528
+ reference data, corporate events, company fundamental data, HFN news,
529
+ stock-loan data, bulk market data, broker reference, broker analytics and
530
+ book-scope endpoints. It documents parameters, endpoint relationships such as
531
+ available-ticker discovery before market-data calls, broker-reference discovery
532
+ before broker analytics, HFN filter discovery before news queries, corporate
533
+ events before adjusted price analysis, and book-scope constraints for
534
+ microstructure analysis.
535
+
536
+ The REST catalogs also document cross-domain relationships between Public
537
+ Sources and market-data services: company directory resolution feeds ticker
538
+ reference, quotes, candles, stock-loan, broker analytics and book-scope tools;
539
+ sector classification feeds peer-market comparisons; fund holdings feed
540
+ underlying ticker market analysis; ownership/free-float feeds liquidity context;
541
+ and disclosures, official notices, HFN news and corporate events feed event
542
+ window analysis.
543
+
544
+ #### Alternative Data - Metadata
545
+
546
+ Technical endpoint descriptions for the public-sources alternative-data APIs are
547
+ exported by the package so MCPs and other connectors can reuse the same source
548
+ of truth:
549
+
550
+ ```python
551
+ from btgsolutions_dataservices.rest import (
552
+ PUBLIC_SOURCES_ENDPOINTS,
553
+ PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS,
554
+ get_public_sources_tool_description,
555
+ )
556
+
557
+ print(get_public_sources_tool_description("get_company_board"))
558
+ ```
559
+
560
+ The catalog documents endpoint parameters, known data gaps, excluded endpoints,
561
+ and relationships such as: company metadata resolving identifiers for governance
562
+ and ownership calls; macro indicator metadata feeding macro observations; asset
563
+ metadata feeding maximum-theoretical-margin calls; financial statement type
564
+ metadata feeding statement queries; assemblies and ownership notices feeding
565
+ notice summaries; and fund holdings/asset fund holders linking funds with
566
+ company tickers.
567
+
568
+ ```python
569
+ import btgsolutions_dataservices as btg
570
+ meta = btg.AlternativeDataMetadata(api_key='YOUR_API_KEY')
562
571
  meta.get_company_directory(query='PETROBRAS', jurisdiction='BR')
563
572
  meta.list_companies(query='PETROBRAS', jurisdiction='BR')
564
573
  meta.list_etfs(query='BOVA')
@@ -581,27 +590,27 @@ companies = btg.AlternativeDataCompanies(api_key='YOUR_API_KEY')
581
590
  companies.list_companies(query='PETROBRAS', jurisdiction='BR')
582
591
  companies.get_board(company_id='VALE3', body='board')
583
592
  companies.get_governance_summary(company_id='ITUB4')
584
- companies.get_governance_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
585
- companies.get_governance_documents(company_id='PETR4', start_date='2024-01-01', end_date='2024-12-31')
586
- companies.get_governance_compensation(company_id='VALE3', fiscal_year='2024')
587
- companies.get_governance_related_party(company_id='ITUB4')
588
- companies.get_governance_beneficial_ownership(company_id='AAPL') # UK PSC / US SEC proxy data; not BR listed-company ownership
589
- companies.get_corporate_registry(company_id='PETR4', direction='partners')
590
- companies.get_corporate_registry(company_id='PETR4', direction='investees')
591
- companies.get_insider_trades(company_id='AAPL', start_date='2024-01-01', end_date='2024-12-31')
592
- companies.get_board_changes(company_id='VALE3', event='elected')
593
+ companies.get_governance_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
594
+ companies.get_governance_documents(company_id='PETR4', start_date='2024-01-01', end_date='2024-12-31')
595
+ companies.get_governance_compensation(company_id='VALE3', fiscal_year='2024')
596
+ companies.get_governance_related_party(company_id='ITUB4')
597
+ companies.get_governance_beneficial_ownership(company_id='AAPL') # UK PSC / US SEC proxy data; not BR listed-company ownership
598
+ companies.get_corporate_registry(company_id='PETR4', direction='partners')
599
+ companies.get_corporate_registry(company_id='PETR4', direction='investees')
600
+ companies.get_insider_trades(company_id='AAPL', start_date='2024-01-01', end_date='2024-12-31')
601
+ companies.get_board_changes(company_id='VALE3', event='elected')
593
602
  companies.get_assemblies(company_id='PINE4')
594
- companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='4T24')
595
- companies.get_financial_notes(company_id='VALE3', quarter='4T24')
596
- companies.get_disclosures(company_id='PETR4', document_type='repurchase')
597
- companies.get_disclosures(company_id='PETR4', document_type='insider')
598
- ```
599
-
600
- For Brazilian governance endpoints, current board and summary responses prefer
601
- the latest raw FRE filing when available. Returned governance summaries can
602
- include `latest_reference_date`, `latest_version`, `latest_document_id` and
603
- `structure_source`; alternate B3 tickers/units such as `BPAC11` can resolve to
604
- the underlying listed company when covered by the source metadata.
603
+ companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='4T24')
604
+ companies.get_financial_notes(company_id='VALE3', quarter='4T24')
605
+ companies.get_disclosures(company_id='PETR4', document_type='repurchase')
606
+ companies.get_disclosures(company_id='PETR4', document_type='insider')
607
+ ```
608
+
609
+ For Brazilian governance endpoints, current board and summary responses prefer
610
+ the latest raw FRE filing when available. Returned governance summaries can
611
+ include `latest_reference_date`, `latest_version`, `latest_document_id` and
612
+ `structure_source`; alternate B3 tickers/units such as `BPAC11` can resolve to
613
+ the underlying listed company when covered by the source metadata.
605
614
 
606
615
  #### Alternative Data - People
607
616
 
@@ -616,14 +625,14 @@ people.get_appointments(person_id='slug:Jean Paul Lemann', group_by='company')
616
625
 
617
626
  ```python
618
627
  import btgsolutions_dataservices as btg
619
- funds = btg.AlternativeDataFunds(api_key='YOUR_API_KEY')
620
- funds.list_etfs(query='BOVA')
621
- funds.get_holdings(fund_id='BOVA11', reference_date='2024-12-31')
622
- funds.get_exposures(fund_id='BOVA11', exposure_type='asset_class')
623
- funds.get_history(fund_id='BOVA11', start_date='2024-01-01', end_date='2024-12-31')
624
- funds.get_lookthrough(fund_id='BOVA11')
625
- # Manager aggregation requires an exact covered manager CNPJ/name, not ETF issuer slugs, ETF tickers or fund CNPJs.
626
- # funds.get_manager_aggregate_holdings(manager_id='...')
628
+ funds = btg.AlternativeDataFunds(api_key='YOUR_API_KEY')
629
+ funds.list_etfs(query='BOVA')
630
+ funds.get_holdings(fund_id='BOVA11', reference_date='2024-12-31')
631
+ funds.get_exposures(fund_id='BOVA11', exposure_type='asset_class')
632
+ funds.get_history(fund_id='BOVA11', start_date='2024-01-01', end_date='2024-12-31')
633
+ funds.get_lookthrough(fund_id='BOVA11')
634
+ # Manager aggregation requires an exact covered manager CNPJ/name, not ETF issuer slugs, ETF tickers or fund CNPJs.
635
+ # funds.get_manager_aggregate_holdings(manager_id='...')
627
636
  ```
628
637
 
629
638
  #### Alternative Data - Ownership
@@ -640,16 +649,16 @@ ownership.get_notice_summary(url='https://www.rad.cvm.gov.br/ENETWEB/frmGerencia
640
649
  ownership.get_ownership_control_group(company_id='VALE3')
641
650
  ownership.get_ownership_free_float(company_id='PETR4')
642
651
  ownership.get_shareholder_holdings(shareholder_id='00.000.000/0001-91')
643
- ownership.get_institutional_holders(identifier='VALE3')
644
- ownership.get_fund_holders(identifier='PETR4', identifier_type='b3_ticker')
645
- ```
646
-
647
- For Brazilian ownership/free-float endpoints, current control and free-float
648
- responses use the latest FRE source document/version for the selected reference
649
- date when available. Repeated older source documents are deduplicated where
650
- possible, while distinct rows for the same holder across classes, roles or
651
- ownership categories are preserved. Zero free-float or independence percentages
652
- can be valid source values, not missing data.
652
+ ownership.get_institutional_holders(identifier='VALE3')
653
+ ownership.get_fund_holders(identifier='PETR4', identifier_type='b3_ticker')
654
+ ```
655
+
656
+ For Brazilian ownership/free-float endpoints, current control and free-float
657
+ responses use the latest FRE source document/version for the selected reference
658
+ date when available. Repeated older source documents are deduplicated where
659
+ possible, while distinct rows for the same holder across classes, roles or
660
+ ownership categories are preserved. Zero free-float or independence percentages
661
+ can be valid source values, not missing data.
653
662
 
654
663
  #### Alternative Data - Macro & Markets
655
664
 
@@ -657,16 +666,16 @@ can be valid source values, not missing data.
657
666
  import btgsolutions_dataservices as btg
658
667
  macro = btg.AlternativeDataMacroMarkets(api_key='YOUR_API_KEY')
659
668
  macro.get_macro_indicators(indicator='selic')
660
- macro.get_macro_indicators(indicator='ipca_contributions', start_date='2024-01', end_date='2024-12')
661
- macro.get_macro_indicators(indicator='gdp', type='yoy')
662
- macro.get_macro_indicators(indicator='comexstat', year='2024', state='SP')
663
- macro.get_macro_indicators(indicator='comexstat', aggregate='states', start_date='2024-01', end_date='2024-12')
664
- macro.get_macro_indicators(indicator='comexstat', aggregate='timeline', group_by='country', state='SP')
665
- macro.get_macro_indicators(indicator='rreo', year='2024', period='6')
666
- macro.get_maximum_theoretical_margin(asset='PETR4', report_date='2024-12-31')
667
- macro.get_dpmfi(start_date='2024-01', end_date='2024-12', status='dados_oficiais')
668
- macro.get_dpmfi(snapshot_date='2026-06-24', limit=10) # reproducible scoped snapshot
669
- macro.get_dpmfi_composition(bond_type='IPCA')
669
+ macro.get_macro_indicators(indicator='ipca_contributions', start_date='2024-01', end_date='2024-12')
670
+ macro.get_macro_indicators(indicator='gdp', type='yoy')
671
+ macro.get_macro_indicators(indicator='comexstat', year='2024', state='SP')
672
+ macro.get_macro_indicators(indicator='comexstat', aggregate='states', start_date='2024-01', end_date='2024-12')
673
+ macro.get_macro_indicators(indicator='comexstat', aggregate='timeline', group_by='country', state='SP')
674
+ macro.get_macro_indicators(indicator='rreo', year='2024', period='6')
675
+ macro.get_maximum_theoretical_margin(asset='PETR4', report_date='2024-12-31')
676
+ macro.get_dpmfi(start_date='2024-01', end_date='2024-12', status='dados_oficiais')
677
+ macro.get_dpmfi(snapshot_date='2026-06-24', limit=10) # reproducible scoped snapshot
678
+ macro.get_dpmfi_composition(bond_type='IPCA')
670
679
  ```
671
680
 
672
681
  `AlternativeDataMacroMarkets` exposes the public-sources market-data endpoint for B3 maximum theoretical margin. The direct market-data `investor-categories` endpoint is intentionally not exposed in this package.
@@ -1,4 +1,4 @@
1
- __version__ = "4.5.1"
1
+ __version__ = "4.6.0"
2
2
 
3
3
  from .websocket import *
4
4
  from .rest import *
@@ -1,5 +1,5 @@
1
1
  import os
2
- from typing import Optional
2
+ from typing import Dict, Optional
3
3
  from ..exceptions import BadResponse
4
4
  import requests
5
5
  from ..config import url_api_v1, url_apis, url_apis_v3
@@ -9,6 +9,25 @@ import pandas as pd
9
9
  from io import BytesIO
10
10
  import pyarrow.parquet as pq
11
11
 
12
+ BILLING_HEADER_NAMES = (
13
+ "X-Dry-Run",
14
+ "X-Billable",
15
+ "X-Requested-Rows",
16
+ "X-Current-Rows",
17
+ "X-Contracted-Limit-Rows",
18
+ "X-Remaining-Rows",
19
+ "X-Already-Billed",
20
+ "X-Would-Exceed-Limit",
21
+ )
22
+
23
+
24
+ def extract_billing_headers(headers) -> Dict[str, str]:
25
+ return {
26
+ header_name: headers.get(header_name)
27
+ for header_name in BILLING_HEADER_NAMES
28
+ if headers.get(header_name) is not None
29
+ }
30
+
12
31
  def download_compressed_file(url, headers):
13
32
 
14
33
  with requests.get(url, headers=headers, stream=True) as response:
@@ -164,7 +183,9 @@ class BulkData:
164
183
  ticker:str,
165
184
  date:str,
166
185
  data_type:str='trades',
167
- raw_data:bool=False
186
+ raw_data:bool=False,
187
+ return_billing_headers:bool=False,
188
+ dry_run:bool=False,
168
189
  ):
169
190
  """
170
191
  This method provides tick-by-tick market data (trades, book events, book snapshots) for a given ticker and date.
@@ -184,11 +205,24 @@ class BulkData:
184
205
  raw_data: bool
185
206
  If false, returns data in a dataframe. If true, returns raw data.
186
207
  Field is not required. Default: False.
208
+ return_billing_headers: bool
209
+ If true, returns billing headers with the data.
210
+ Field is not required. Default: False.
211
+ dry_run: bool
212
+ If true, checks billing quota without downloading data and returns billing headers.
213
+ Field is not required. Default: False.
187
214
  """
188
215
 
189
216
  url = f"{url_apis}/marketdata/bulkdata/{data_type}?ticker={ticker}&date={date}"
217
+ if dry_run:
218
+ url = f"{url}&dry_run=true"
190
219
 
191
220
  response = requests.request("GET", url, headers=self.headers)
221
+ billing_headers = extract_billing_headers(response.headers)
222
+
223
+ if response.status_code == 204 and dry_run:
224
+ return billing_headers
225
+
192
226
  if response.status_code == 200:
193
227
 
194
228
  try:
@@ -198,6 +232,8 @@ class BulkData:
198
232
  parquet_file = pq.ParquetFile(parquet_buffer)
199
233
  df = parquet_file.read().to_pandas()
200
234
 
235
+ if return_billing_headers:
236
+ return df, billing_headers
201
237
  return df
202
238
 
203
239
  else:
@@ -207,6 +243,8 @@ class BulkData:
207
243
  # Write the content to a file
208
244
  with open(filename, 'wb') as file:
209
245
  file.write(response.content)
246
+ if return_billing_headers:
247
+ return billing_headers
210
248
  return None
211
249
 
212
250
  except Exception as e:
@@ -1,25 +1,12 @@
1
- Metadata-Version: 2.4
2
- Name: btgsolutions_dataservices_python_client
3
- Version: 4.5.1
1
+ Metadata-Version: 2.1
2
+ Name: btgsolutions-dataservices-python-client
3
+ Version: 4.6.0
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
- Dynamic: author
16
- Dynamic: description
17
- Dynamic: description-content-type
18
- Dynamic: home-page
19
- Dynamic: license-file
20
- Dynamic: requires-dist
21
- Dynamic: requires-python
22
- Dynamic: summary
23
10
 
24
11
  # BTG Solutions - Data Services
25
12
 
@@ -351,6 +338,15 @@ bulk_data.get_data(ticker='DI1F18', date='2017-01-02', data_type='trades')
351
338
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='instrument-status')
352
339
  ```
353
340
 
341
+ ##### Get Data With Billing Headers
342
+
343
+ ```python
344
+ import btgsolutions_dataservices as btg
345
+ bulk_data = btg.BulkData(api_key='YOUR_API_KEY')
346
+ df, billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', return_billing_headers=True)
347
+ # billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', dry_run=True)
348
+ ```
349
+
354
350
  ##### Security List
355
351
 
356
352
  ```python