btgsolutions-dataservices-python-client 4.4.2__tar.gz → 4.5.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 (49) hide show
  1. {btgsolutions_dataservices_python_client-4.4.2/btgsolutions_dataservices_python_client.egg-info → btgsolutions_dataservices_python_client-4.5.1}/PKG-INFO +14 -1
  2. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/README.md +19 -6
  3. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/__init__.py +1 -1
  4. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/alternative_data_catalog.py +171 -39
  5. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/alternative_data_companies.py +127 -18
  6. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/alternative_data_funds.py +18 -5
  7. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/alternative_data_metadata.py +8 -2
  8. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/alternative_data_ownership.py +66 -7
  9. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1/btgsolutions_dataservices_python_client.egg-info}/PKG-INFO +14 -1
  10. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/LICENSE +0 -0
  11. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/MANIFEST.in +0 -0
  12. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/config.py +0 -0
  13. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/exceptions.py +0 -0
  14. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/__init__.py +0 -0
  15. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py +0 -0
  16. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/alternative_data_people.py +0 -0
  17. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/authenticator.py +0 -0
  18. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/book_scope.py +0 -0
  19. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/broker_analytics.py +0 -0
  20. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/broker_reference.py +0 -0
  21. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/bulk_data.py +0 -0
  22. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/company_data.py +0 -0
  23. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/corporate_events.py +0 -0
  24. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/dataservices_catalog.py +0 -0
  25. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/hfn.py +0 -0
  26. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/historical_candles.py +0 -0
  27. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/historical_candles_crypto.py +0 -0
  28. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/intraday_candles.py +0 -0
  29. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/intraday_tick_data.py +0 -0
  30. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/public_sources.py +0 -0
  31. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/quotes.py +0 -0
  32. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/reference_data.py +0 -0
  33. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/stock_loan.py +0 -0
  34. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/ticker_last_event.py +0 -0
  35. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/rest/ticker_last_event_polling.py +0 -0
  36. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/websocket/__init__.py +0 -0
  37. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/websocket/broker_analytics.py +0 -0
  38. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/websocket/hfn_websocket_client.py +0 -0
  39. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/websocket/market_data_feed.py +0 -0
  40. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/websocket/market_data_websocket_client.py +0 -0
  41. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices/websocket/websocket_default_functions.py +0 -0
  42. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices_python_client.egg-info/SOURCES.txt +0 -0
  43. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices_python_client.egg-info/dependency_links.txt +0 -0
  44. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices_python_client.egg-info/requires.txt +0 -0
  45. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/btgsolutions_dataservices_python_client.egg-info/top_level.txt +0 -0
  46. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/pyproject.toml +0 -0
  47. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/requirements.txt +0 -0
  48. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/setup.cfg +0 -0
  49. {btgsolutions_dataservices_python_client-4.4.2 → btgsolutions_dataservices_python_client-4.5.1}/setup.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: btgsolutions_dataservices_python_client
3
- Version: 4.4.2
3
+ Version: 4.5.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
@@ -620,6 +620,12 @@ companies.get_disclosures(company_id='PETR4', document_type='repurchase')
620
620
  companies.get_disclosures(company_id='PETR4', document_type='insider')
621
621
  ```
622
622
 
623
+ For Brazilian governance endpoints, current board and summary responses prefer
624
+ the latest raw FRE filing when available. Returned governance summaries can
625
+ include `latest_reference_date`, `latest_version`, `latest_document_id` and
626
+ `structure_source`; alternate B3 tickers/units such as `BPAC11` can resolve to
627
+ the underlying listed company when covered by the source metadata.
628
+
623
629
  #### Alternative Data - People
624
630
 
625
631
  ```python
@@ -661,6 +667,13 @@ ownership.get_institutional_holders(identifier='VALE3')
661
667
  ownership.get_fund_holders(identifier='PETR4', identifier_type='b3_ticker')
662
668
  ```
663
669
 
670
+ For Brazilian ownership/free-float endpoints, current control and free-float
671
+ responses use the latest FRE source document/version for the selected reference
672
+ date when available. Repeated older source documents are deduplicated where
673
+ possible, while distinct rows for the same holder across classes, roles or
674
+ ownership categories are preserved. Zero free-float or independence percentages
675
+ can be valid source values, not missing data.
676
+
664
677
  #### Alternative Data - Macro & Markets
665
678
 
666
679
  ```python
@@ -593,9 +593,15 @@ companies.get_board_changes(company_id='VALE3', event='elected')
593
593
  companies.get_assemblies(company_id='PINE4')
594
594
  companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='4T24')
595
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
- ```
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.
599
605
 
600
606
  #### Alternative Data - People
601
607
 
@@ -634,9 +640,16 @@ ownership.get_notice_summary(url='https://www.rad.cvm.gov.br/ENETWEB/frmGerencia
634
640
  ownership.get_ownership_control_group(company_id='VALE3')
635
641
  ownership.get_ownership_free_float(company_id='PETR4')
636
642
  ownership.get_shareholder_holdings(shareholder_id='00.000.000/0001-91')
637
- ownership.get_institutional_holders(identifier='VALE3')
638
- ownership.get_fund_holders(identifier='PETR4', identifier_type='b3_ticker')
639
- ```
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.
640
653
 
641
654
  #### Alternative Data - Macro & Markets
642
655
 
@@ -1,4 +1,4 @@
1
- __version__ = "4.4.2"
1
+ __version__ = "4.5.1"
2
2
 
3
3
  from .websocket import *
4
4
  from .rest import *
@@ -12,9 +12,12 @@ PUBLIC_SOURCES_CONVENTIONS: dict[str, str] = {
12
12
  ),
13
13
  "fund_id": (
14
14
  "Fund identifier accepted by fund endpoints. It can be a fund CNPJ; "
15
- "holdings, exposures, history and look-through also accept supported "
16
- "Brazilian ETF tickers such as BOVA11. ETFs and funds are not resolved "
17
- "through the listed-company directory."
15
+ "Brazilian ETF-aware endpoints also accept supported BR ETF tickers "
16
+ "such as BOVA11. Holdings can also accept covered US ETF/fund "
17
+ "identifiers such as SPY when issuer-official or N-PORT coverage is "
18
+ "loaded, but exposures and look-through are limited to Brazilian fund "
19
+ "CNPJs or BR ETF tickers. ETFs and funds are not resolved through the "
20
+ "listed-company directory."
18
21
  ),
19
22
  "shareholder_id": (
20
23
  "Shareholder identifier used for reverse ownership lookup, usually a "
@@ -50,12 +53,16 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
50
53
  "can change matches."
51
54
  ),
52
55
  "get_company_board": (
53
- "For Brazilian companies, body='board' can include Conselho Fiscal rows "
56
+ "For Brazilian companies, current board/executive composition prefers "
57
+ "the latest raw FRE rows over older materialized snapshots and orders "
58
+ "FRE versions numerically. body='board' can include Conselho Fiscal rows "
54
59
  "alongside Conselho de Administracao rows depending on the filing. For "
55
60
  "a board-of-directors answer, filter returned rows by governance_body "
56
- "or role to keep Conselho de Administracao only. Committee responses "
57
- "can include broad aggregates such as Outros Comites; do not infer "
58
- "granular committee names unless they are present in returned fields."
61
+ "or role to keep Conselho de Administracao only. body='executive' "
62
+ "deduplicates mixed board/executive rows by person where possible. "
63
+ "Committee responses can include broad aggregates such as Outros "
64
+ "Comites; do not infer granular committee names unless they are present "
65
+ "in returned fields."
59
66
  ),
60
67
  "get_board_changes": (
61
68
  "Brazilian board-change rows can be materialized from FRE snapshot "
@@ -82,7 +89,10 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
82
89
  "issuer exposure can be based on ticker-like issuer labels and country "
83
90
  "exposure can be empty when the source does not classify country. Use "
84
91
  "holdings for constituent-level economic exposure and exposures for "
85
- "aggregate context."
92
+ "aggregate context. The exposures and look-through endpoints accept "
93
+ "Brazilian fund CNPJs and supported BR ETF tickers; US ETF tickers can "
94
+ "be available through holdings while still being rejected by exposures "
95
+ "or look-through."
86
96
  ),
87
97
  "get_fund_lookthrough": (
88
98
  "Look-through is useful when a fund holds other funds that can be "
@@ -102,10 +112,11 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
102
112
  "get_ownership_free_float and get_ownership_official_notices when this "
103
113
  "endpoint returns no rows. "
104
114
  "This endpoint does not synthesize top holders from current ownership "
105
- "or free-float tables. Some responses can include multiple rows for "
106
- "the same holder across share classes, ownership categories, filings "
107
- "or source protocols; inspect category, class, protocol/source and "
108
- "reference date before aggregating percentages."
115
+ "or free-float tables. The API deduplicates repeated rows from older "
116
+ "FRE source documents for the same reference date where possible, while "
117
+ "preserving distinct rows for the same holder across share classes, "
118
+ "ownership categories or roles; inspect category, class, protocol/source "
119
+ "and reference date before aggregating percentages."
109
120
  ),
110
121
  "ownership_reporting_dates": (
111
122
  "Brazilian ownership and free-float reference_date fields often come "
@@ -113,7 +124,9 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
113
124
  "structures. They are reporting/reference dates, not necessarily the "
114
125
  "calendar date when the data was loaded or a strict as-of timestamp; a "
115
126
  "reference_date can be after the current calendar date when it denotes "
116
- "a filing year/base period."
127
+ "a filing year/base period. For FRE tables with multiple filed versions "
128
+ "on the same reference date, current control/free-float/governance "
129
+ "responses prefer the latest source document or numeric version."
117
130
  ),
118
131
  "get_ownership_history": (
119
132
  "Ownership history uses the same normalized ownership_snapshot layer as "
@@ -143,10 +156,13 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
143
156
  "liquidity endpoints separately when contextualizing the margin data."
144
157
  ),
145
158
  "get_beneficial_ownership": (
146
- "Coverage is UK/US oriented: UK Companies House PSC and US SEC proxy "
147
- "beneficial-owner data. Brazilian listed companies are not available in "
148
- "this endpoint and can return 404; use ownership-current, control-group "
149
- "and free-float endpoints for Brazilian ownership context."
159
+ "Coverage is primarily US SEC proxy beneficial-owner data, with "
160
+ "Companies House PSC rows only when upstream UK coverage is loaded for "
161
+ "the requested identifier. Brazilian listed companies are not available "
162
+ "in this endpoint and can return 404; use ownership-current, "
163
+ "control-group and free-float endpoints for Brazilian ownership context. "
164
+ "For US companies, ticker, CIK or ISIN can work directly even when the "
165
+ "company-directory search endpoint does not resolve that CIK or ISIN."
150
166
  ),
151
167
  "get_asset_institutional_holders": (
152
168
  "Institutional-holder coverage comes from the precomputed asset-holder "
@@ -157,7 +173,10 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
157
173
  "that ticker-to-ISIN fallback was used. This endpoint still does not run "
158
174
  "the live fund-portfolio/ETF holding lookup used by "
159
175
  "get_asset_fund_holders; use get_asset_fund_holders when this endpoint "
160
- "is empty or when ETF/fund-holder coverage is needed."
176
+ "is empty or when ETF/fund-holder coverage is needed. Do not describe "
177
+ "these rows as SEC 13F unless the returned source fields explicitly "
178
+ "identify a 13F source; fund_asset_ownership rows are fund/ETF holder "
179
+ "snapshots, not issuer top-shareholder or 13F summaries."
161
180
  ),
162
181
  "get_disclosure_documents_repurchase": (
163
182
  "Share-repurchase disclosure coverage can be thin for many companies. "
@@ -342,13 +361,16 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
342
361
  "method": "GET",
343
362
  "client": "AlternativeDataMetadata",
344
363
  "description": (
345
- "Search listed-company metadata by name, ticker, CNPJ, CVM code, "
346
- "CIK or ISIN. Use this to resolve a company identifier before "
347
- "governance, ownership, sector, financial-statement or disclosure "
348
- "endpoints."
364
+ "Search listed-company metadata by name, ticker, CNPJ or CVM code; "
365
+ "US rows can include CIK and ISIN fields in the response. Use this "
366
+ "to resolve a company identifier before governance, ownership, "
367
+ "sector, financial-statement or disclosure endpoints. If a CIK, "
368
+ "ISIN or LEI search returns no directory match, try the relevant "
369
+ "company endpoint directly when its parameter documentation accepts "
370
+ "that identifier."
349
371
  ),
350
372
  "parameters": {
351
- "query": "Free-text query over company name, ticker, CNPJ, CVM code, CIK or ISIN.",
373
+ "query": "Free-text query over company name, ticker, CNPJ or CVM code; returned US rows can include CIK and ISIN fields.",
352
374
  "jurisdiction": "Optional jurisdiction filter such as 'BR' or 'US'.",
353
375
  "limit": "Maximum number of results.",
354
376
  "offset": "Pagination offset.",
@@ -387,7 +409,10 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
387
409
  "List ETFs available in the public-sources ETF registry. Use this "
388
410
  "for ETF discovery because ETFs are not returned by listed-company "
389
411
  "search endpoints. Use include_metrics=False for lightweight "
390
- "autocomplete/search responses."
412
+ "autocomplete/search responses. Returned rows can combine fund "
413
+ "identity, issuer, index metadata and latest NAV/AUM/holder metrics "
414
+ "from sources such as CVM/FNET, B3 index composition or manager/"
415
+ "issuer official holdings, depending on coverage."
391
416
  ),
392
417
  "parameters": {
393
418
  "query": "Free-text filter over ticker, fund name, CNPJ or issuer.",
@@ -614,9 +639,10 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
614
639
  "description": (
615
640
  "Get members of a company's governance body. body can be board, "
616
641
  "executive or committee; committee filters a specific committee when "
617
- "body='committee'. For Brazilian filings, body='board' can include "
618
- "Conselho Fiscal rows; filter governance_body/role for Conselho de "
619
- "Administracao when answering board-of-directors questions."
642
+ "body='committee'. For Brazilian filings, latest raw FRE rows are "
643
+ "preferred when present; body='board' can include Conselho Fiscal "
644
+ "rows; filter governance_body/role for Conselho de Administracao "
645
+ "when answering board-of-directors questions."
620
646
  ),
621
647
  "parameters": {
622
648
  "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
@@ -637,8 +663,11 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
637
663
  "client": "AlternativeDataCompanies",
638
664
  "description": (
639
665
  "Get a compact latest governance snapshot for a company as a "
640
- "composite object. It can include board size, committees, CEO and "
641
- "free-float-related fields when available."
666
+ "composite object. For Brazilian companies, current counts are "
667
+ "derived from the latest raw FRE filing when available and can "
668
+ "include latest_reference_date, latest_version, latest_document_id, "
669
+ "structure_source, board size, independent members, fiscal council "
670
+ "size, executives, committees and CEO."
642
671
  ),
643
672
  "parameters": {"company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"]},
644
673
  "relationships": ["company_resolution", "company_trading_bridge"],
@@ -733,13 +762,15 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
733
762
  "method": "GET",
734
763
  "client": "AlternativeDataCompanies",
735
764
  "description": (
736
- "Get beneficial-owner records from UK Companies House PSC or US SEC "
737
- "proxy DEF14A data. Brazilian companies are not available here."
765
+ "Get beneficial-owner records from US SEC proxy DEF14A data and, "
766
+ "when loaded upstream, UK Companies House PSC data. Brazilian "
767
+ "companies are not available here."
738
768
  ),
739
769
  "parameters": {
740
770
  "company_id": (
741
- "UK company number, SEC ticker/CIK, ISIN, LEI or company name. "
742
- "Use values such as AAPL or 0000320193 for US coverage."
771
+ "SEC ticker/CIK/ISIN, or a UK company number/name when "
772
+ "Companies House PSC coverage is loaded. Use values such as "
773
+ "AAPL, 0000320193 or US0378331005 for US coverage."
743
774
  ),
744
775
  "holder_type": (
745
776
  "Optional holder classification such as individual, institution, "
@@ -754,6 +785,62 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
754
785
  ],
755
786
  "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_beneficial_ownership"]],
756
787
  },
788
+ "AlternativeDataCompanies.get_sec_filings": {
789
+ "category": "companies",
790
+ "path": "companies/sec-filings",
791
+ "method": "GET",
792
+ "client": "AlternativeDataCompanies",
793
+ "description": (
794
+ "Get SEC EDGAR filing metadata for a US company. Use form_type='8-K' "
795
+ "with item='5.02' for director/officer change events, form_type='DEF 14A' "
796
+ "for proxy/governance context, and SC 13D/SC 13G forms for beneficial "
797
+ "ownership filing metadata. This endpoint returns filing metadata and "
798
+ "source URLs, not full filing-text parsing."
799
+ ),
800
+ "parameters": {
801
+ "company_id": "SEC ticker, CIK, ISIN or company name.",
802
+ "form_type": "Optional SEC form type filter; accepts comma-separated values such as '8-K,DEF 14A'.",
803
+ "item": "Optional 8-K item filter such as '5.02'.",
804
+ "start_date": "Start filing date in YYYY-MM-DD.",
805
+ "end_date": "End filing date in YYYY-MM-DD.",
806
+ "limit": "Maximum number of filings.",
807
+ "offset": "Pagination offset.",
808
+ },
809
+ "relationships": [
810
+ "company_resolution", "document_market_event_bridge",
811
+ "ownership_fallback",
812
+ ],
813
+ "caveats": [
814
+ "10-K metadata is not currently loaded when this endpoint returns zero rows for form_type='10-K'.",
815
+ "8-K item metadata can exist without a parsed event narrative; inspect primary_document before summarizing.",
816
+ ],
817
+ },
818
+ "AlternativeDataCompanies.get_sec_schedule_13d_13g": {
819
+ "category": "companies",
820
+ "path": "companies/sec-schedule-13d-13g",
821
+ "method": "GET",
822
+ "client": "AlternativeDataCompanies",
823
+ "description": (
824
+ "Get parsed SEC Schedule 13D/13G beneficial-ownership rows for a US "
825
+ "company, including reporting owner, beneficially owned shares and "
826
+ "percent of class when available. Use get_sec_filings for filing "
827
+ "metadata/source URLs and this endpoint for holder/share fields."
828
+ ),
829
+ "parameters": {
830
+ "company_id": "SEC ticker, CIK, ISIN or company name.",
831
+ "start_date": "Start filing date in YYYY-MM-DD.",
832
+ "end_date": "End filing date in YYYY-MM-DD.",
833
+ "limit": "Maximum number of rows.",
834
+ "offset": "Pagination offset.",
835
+ },
836
+ "relationships": [
837
+ "company_resolution", "ownership_fallback",
838
+ "ownership_liquidity_bridge", "document_market_event_bridge",
839
+ ],
840
+ "caveats": [
841
+ "Schedule 13D/G rows are US SEC beneficial-ownership filings and should not be treated as Brazilian ownership snapshots.",
842
+ ],
843
+ },
757
844
  "AlternativeDataCompanies.get_corporate_registry": {
758
845
  "category": "companies",
759
846
  "path": "companies/corporate-registry",
@@ -781,8 +868,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
781
868
  "method": "GET",
782
869
  "client": "AlternativeDataCompanies",
783
870
  "description": (
784
- "Get US SEC insider-trading transactions for a US company ticker or "
785
- "CIK. This endpoint is not for Brazilian companies."
871
+ "Get US SEC insider-trading transactions from Forms 3/4/5 for a US "
872
+ "company ticker or CIK. In practice, populated rows are commonly "
873
+ "source='SEC/Form4'. This endpoint is not for Brazilian companies."
786
874
  ),
787
875
  "parameters": {
788
876
  "company_id": "US SEC ticker or CIK.",
@@ -983,6 +1071,10 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
983
1071
  "Get a fund or ETF portfolio holdings/positions for a reference date. "
984
1072
  "Use this for constituent assets and weights or values, not NAV history. "
985
1073
  "Use summary=True and include_raw=False for a compact payload. "
1074
+ "Rows expose source/snapshot_type fields such as B3 index composition, "
1075
+ "manager official holdings, issuer-official holdings or SEC N-PORT "
1076
+ "depending on the covered fund. US official ETF holdings can identify "
1077
+ "assets by CUSIP when ticker/ISIN enrichment is unavailable. "
986
1078
  "For CVM/CDA rows without same-day daily NAV, position_weight may be "
987
1079
  "computed from the latest prior daily report within seven days; "
988
1080
  "company_nav_reference_date and company_nav_source identify that "
@@ -1089,7 +1181,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
1089
1181
  "description": (
1090
1182
  "Get top shareholders for a company from the normalized "
1091
1183
  "ownership_snapshot layer when shareholder-level snapshots are "
1092
- "available. Brazilian CVM/FRE rows are periodic filing snapshots."
1184
+ "available. Brazilian CVM/FRE rows are periodic filing snapshots; "
1185
+ "older repeated FRE source documents for the same reference date "
1186
+ "are deduplicated where possible."
1093
1187
  ),
1094
1188
  "parameters": {
1095
1189
  "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
@@ -1117,7 +1211,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
1117
1211
  "client": "AlternativeDataOwnership",
1118
1212
  "description": (
1119
1213
  "Get current ownership structure of a listed company as a composite "
1120
- "object. Use this for latest control, free-float and ownership summary context."
1214
+ "object. Use this for latest control, free-float and ownership summary "
1215
+ "context. For Brazilian FRE data, current control/free-float blocks "
1216
+ "prefer the latest source document for the selected reference date."
1121
1217
  ),
1122
1218
  "parameters": {"company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"]},
1123
1219
  "relationships": [
@@ -1218,6 +1314,34 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
1218
1314
  },
1219
1315
  "relationships": ["document_summary", "document_market_event_bridge"],
1220
1316
  },
1317
+ "AlternativeDataOwnership.get_sec_13f_holdings": {
1318
+ "category": "ownership",
1319
+ "path": "sec/13f-holdings",
1320
+ "method": "GET",
1321
+ "client": "AlternativeDataOwnership",
1322
+ "description": (
1323
+ "Get SEC 13F-HR institutional investment-manager holding rows by "
1324
+ "manager_id and/or asset_id. manager_id accepts manager CIK, manager "
1325
+ "name or a SEC registrant ticker when the manager is itself a SEC "
1326
+ "company. asset_id accepts issuer ticker, CUSIP, ISIN or issuer name."
1327
+ ),
1328
+ "parameters": {
1329
+ "manager_id": "Optional SEC manager CIK, manager name or SEC registrant ticker.",
1330
+ "asset_id": "Optional issuer ticker, CUSIP, ISIN or issuer name.",
1331
+ "start_date": "Start filing date in YYYY-MM-DD.",
1332
+ "end_date": "End filing date in YYYY-MM-DD.",
1333
+ "limit": "Maximum number of rows.",
1334
+ "offset": "Pagination offset.",
1335
+ },
1336
+ "relationships": [
1337
+ "company_resolution", "ownership_fallback",
1338
+ "ownership_liquidity_bridge", "document_market_event_bridge",
1339
+ ],
1340
+ "caveats": [
1341
+ "13F rows are manager filing disclosures, not issuer top-shareholder tables.",
1342
+ "13F does not cover all holders, short positions or non-reporting investors.",
1343
+ ],
1344
+ },
1221
1345
  "AlternativeDataOwnership.get_ownership_control_group": {
1222
1346
  "category": "ownership",
1223
1347
  "path": "companies/ownership-control-group",
@@ -1226,7 +1350,10 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
1226
1350
  "description": (
1227
1351
  "Get controlling shareholders, shareholder agreements and control "
1228
1352
  "evidence for a company as a composite object. Use this for who "
1229
- "controls the company, not for all holder positions."
1353
+ "controls the company, not for all holder positions. For Brazilian "
1354
+ "FRE rows, current control holders are restricted to the latest "
1355
+ "source document for the selected reference date when protocols "
1356
+ "identify multiple filed versions."
1230
1357
  ),
1231
1358
  "parameters": {"company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"]},
1232
1359
  "relationships": [
@@ -1242,7 +1369,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
1242
1369
  "client": "AlternativeDataOwnership",
1243
1370
  "description": (
1244
1371
  "Get free-float percentage and share-class details for a company as "
1245
- "a composite object. Use this for investable-float questions."
1372
+ "a composite object. Use this for investable-float questions. "
1373
+ "Brazilian FRE distribution-of-capital versions are ordered "
1374
+ "numerically; returned zero percentages can be valid source values."
1246
1375
  ),
1247
1376
  "parameters": {
1248
1377
  "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
@@ -1377,6 +1506,8 @@ PUBLIC_SOURCES_TOOL_ENDPOINTS: dict[str, str] = {
1377
1506
  "get_governance_compensation": "AlternativeDataCompanies.get_governance_compensation",
1378
1507
  "get_related_party": "AlternativeDataCompanies.get_governance_related_party",
1379
1508
  "get_beneficial_ownership": "AlternativeDataCompanies.get_governance_beneficial_ownership",
1509
+ "get_sec_filings": "AlternativeDataCompanies.get_sec_filings",
1510
+ "get_sec_schedule_13d_13g": "AlternativeDataCompanies.get_sec_schedule_13d_13g",
1380
1511
  "get_corporate_registry": "AlternativeDataCompanies.get_corporate_registry",
1381
1512
  "get_insider_trades": "AlternativeDataCompanies.get_insider_trades",
1382
1513
  "get_board_changes": "AlternativeDataCompanies.get_board_changes",
@@ -1400,6 +1531,7 @@ PUBLIC_SOURCES_TOOL_ENDPOINTS: dict[str, str] = {
1400
1531
  "get_ownership_change_events": "AlternativeDataOwnership.get_ownership_change_events",
1401
1532
  "get_ownership_official_notices": "AlternativeDataOwnership.get_ownership_official_notices",
1402
1533
  "get_notice_summary": "AlternativeDataOwnership.get_notice_summary",
1534
+ "get_sec_13f_holdings": "AlternativeDataOwnership.get_sec_13f_holdings",
1403
1535
  "get_control_group": "AlternativeDataOwnership.get_ownership_control_group",
1404
1536
  "get_free_float": "AlternativeDataOwnership.get_ownership_free_float",
1405
1537
  "get_shareholder_holdings": "AlternativeDataOwnership.get_shareholder_holdings",
@@ -75,7 +75,10 @@ class AlternativeDataCompanies:
75
75
  Parameters
76
76
  ----------------
77
77
  query: str
78
- Free-text search over company name, ticker, CNPJ, or CIK.
78
+ Free-text search over company name, ticker, CNPJ, or CVM code.
79
+ US rows can include CIK and ISIN in the response, but directory
80
+ search by CIK/ISIN/LEI is not a guaranteed resolver; call the
81
+ target endpoint directly when it documents those identifiers.
79
82
  Field is not required. Example: 'PETROBRAS'.
80
83
  jurisdiction: str
81
84
  Filter by jurisdiction: 'BR' or 'US'.
@@ -105,22 +108,30 @@ class AlternativeDataCompanies:
105
108
  offset: int = 0,
106
109
  ) -> dict:
107
110
  """
108
- Board and executive composition for a company (BR, US, or UK).
111
+ Board and executive composition for a company. Brazilian and US SEC
112
+ coverage are the primary loaded sources; UK Companies House coverage is
113
+ conditional on upstream UK data for the identifier.
109
114
  Use get_board_changes() for appointment/departure events and
110
115
  get_governance_history() for historical snapshot series.
111
116
 
112
- For Brazilian filings, ``body='board'`` can include Conselho Fiscal
113
- rows alongside Conselho de Administracao rows. For a board-of-directors
114
- answer, filter returned rows by governance_body or role. Committee
115
- responses can include broad aggregate groups such as Outros Comites; do
116
- not infer granular committee names unless they are present in returned
117
- fields.
117
+ For Brazilian filings, the latest FRE raw rows are preferred over
118
+ older materialized snapshots and numeric FRE versions are ordered
119
+ numerically (for example version 13 is newer than version 9).
120
+ ``body='board'`` preserves the historical contract and can include
121
+ Conselho Fiscal rows alongside Conselho de Administracao rows; for a
122
+ board-of-directors answer, filter returned rows by governance_body or
123
+ role. ``body='executive'`` returns one row per person after resolving
124
+ duplicate mixed board/executive FRE rows. Committee responses can
125
+ include broad aggregate groups such as Outros Comites; do not infer
126
+ granular committee names unless they are present in returned fields.
118
127
 
119
128
  Parameters
120
129
  ----------------
121
130
  company_id: str
122
- Company identifier. Accepts CNPJ, CVM code, B3 ticker, ISIN, LEI,
123
- UK company number, SEC ticker/CIK, or company name.
131
+ Company identifier. Accepts CNPJ, CVM code, B3 ticker, SEC
132
+ ticker/CIK and, where endpoint resolution supports it, ISIN or
133
+ company name. LEI and UK company-number resolution depend on
134
+ upstream coverage and should be verified with the returned data.
124
135
  Field is required. Example: 'PETR4'.
125
136
  reference_date: str
126
137
  Reference date in YYYY-MM-DD format. Defaults to the most recent filing.
@@ -154,7 +165,13 @@ class AlternativeDataCompanies:
154
165
  def get_governance_summary(self, company_id: str) -> dict:
155
166
  """
156
167
  Latest governance snapshot for a company (board size, independence,
157
- committees, CEO name, etc.).
168
+ fiscal council size, executive count, committees, CEO name, etc.).
169
+ For Brazilian companies, the API derives current counts from the
170
+ latest available FRE raw filing when present, exposes
171
+ latest_reference_date/latest_version/latest_document_id and can mark
172
+ structure_source='fre_raw'. This avoids stale materialized summaries
173
+ and fixes B3 tickers that resolve through alternate traded classes
174
+ such as units.
158
175
  Use get_board() for individual directors/officers and
159
176
  AlternativeDataOwnership.get_ownership_free_float() for detailed
160
177
  free-float breakdowns.
@@ -352,18 +369,18 @@ class AlternativeDataCompanies:
352
369
  offset: int = 0,
353
370
  ) -> dict:
354
371
  """
355
- Beneficial ownership records from UK Companies House PSC or US SEC
356
- proxy DEF14A data. Brazilian companies are not available in this
357
- endpoint and can return 404 / "Company not found". For Brazilian
358
- listed-company ownership context, prefer
372
+ Beneficial ownership records from US SEC proxy DEF14A data and, when
373
+ loaded upstream, UK Companies House PSC data. Brazilian companies are
374
+ not available in this endpoint and can return 404 / "Company not
375
+ found". For Brazilian listed-company ownership context, prefer
359
376
  AlternativeDataOwnership.get_ownership_current(),
360
377
  get_ownership_control_group() or get_ownership_free_float().
361
378
 
362
379
  Parameters
363
380
  ----------------
364
381
  company_id: str
365
- UK company number, SEC ticker/CIK, ISIN, LEI or company name.
366
- Field is required. Example: 'AAPL'.
382
+ SEC ticker/CIK/ISIN, or a UK company number/name when Companies
383
+ House PSC coverage is loaded. Field is required. Example: 'AAPL'.
367
384
  holder_type: str
368
385
  Holder classification filter such as individual, institution,
369
386
  director, officer or ten_percent_owner.
@@ -382,6 +399,95 @@ class AlternativeDataCompanies:
382
399
  "offset": offset,
383
400
  })
384
401
 
402
+ def get_sec_filings(
403
+ self,
404
+ company_id: str,
405
+ form_type: Optional[Union[str, Sequence[str]]] = None,
406
+ item: Optional[str] = None,
407
+ start_date: Optional[str] = None,
408
+ end_date: Optional[str] = None,
409
+ limit: int = 100,
410
+ offset: int = 0,
411
+ ) -> dict:
412
+ """
413
+ SEC EDGAR filing metadata for a US company. Use this when the filing
414
+ itself is the analytical object, for example 8-K Item 5.02 director or
415
+ executive changes, DEF 14A proxy statements, or SC 13D/13G ownership
416
+ filings. This endpoint returns filing metadata and source document
417
+ URLs; it does not parse full filing text.
418
+
419
+ Parameters
420
+ ----------------
421
+ company_id: str
422
+ SEC ticker, CIK, ISIN or company name.
423
+ Field is required. Example: 'AAPL'.
424
+ form_type: str or sequence
425
+ Optional SEC form type filter, comma-separated or a sequence.
426
+ Examples: '8-K', 'DEF 14A', 'SC 13D,SC 13G'.
427
+ item: str
428
+ Optional 8-K item filter. Example: '5.02'.
429
+ start_date: str
430
+ Start filing date in YYYY-MM-DD format.
431
+ Field is not required.
432
+ end_date: str
433
+ End filing date in YYYY-MM-DD format.
434
+ Field is not required.
435
+ limit: int
436
+ Maximum number of filings to return.
437
+ Field is not required. Default: 100.
438
+ offset: int
439
+ Number of results to skip for pagination.
440
+ Field is not required. Default: 0.
441
+ """
442
+ return self._get("companies/sec-filings", {
443
+ "company_id": company_id,
444
+ "form_type": self._csv_param(form_type),
445
+ "item": item,
446
+ "start_date": start_date,
447
+ "end_date": end_date,
448
+ "limit": limit,
449
+ "offset": offset,
450
+ })
451
+
452
+ def get_sec_schedule_13d_13g(
453
+ self,
454
+ company_id: str,
455
+ start_date: Optional[str] = None,
456
+ end_date: Optional[str] = None,
457
+ limit: int = 100,
458
+ offset: int = 0,
459
+ ) -> dict:
460
+ """
461
+ Parsed SEC Schedule 13D/13G beneficial-ownership filing rows for a US
462
+ company. Use get_sec_filings() for the filing metadata and this endpoint
463
+ for holder, share-count and percent-of-class fields.
464
+
465
+ Parameters
466
+ ----------------
467
+ company_id: str
468
+ SEC ticker, CIK, ISIN or company name.
469
+ Field is required. Example: 'AAPL'.
470
+ start_date: str
471
+ Start filing date in YYYY-MM-DD format.
472
+ Field is not required.
473
+ end_date: str
474
+ End filing date in YYYY-MM-DD format.
475
+ Field is not required.
476
+ limit: int
477
+ Maximum number of rows to return.
478
+ Field is not required. Default: 100.
479
+ offset: int
480
+ Number of results to skip for pagination.
481
+ Field is not required. Default: 0.
482
+ """
483
+ return self._get("companies/sec-schedule-13d-13g", {
484
+ "company_id": company_id,
485
+ "start_date": start_date,
486
+ "end_date": end_date,
487
+ "limit": limit,
488
+ "offset": offset,
489
+ })
490
+
385
491
  def get_corporate_registry(
386
492
  self,
387
493
  company_id: str,
@@ -439,7 +545,10 @@ class AlternativeDataCompanies:
439
545
  limit: int = 100,
440
546
  ) -> dict:
441
547
  """
442
- Insider trade transactions from SEC Forms 3/4/5 (US only).
548
+ Insider trade transactions from SEC Forms 3/4/5 (US only). Populated
549
+ rows are commonly Form 4 rows and carry source fields such as
550
+ ``SEC/Form4``; inspect source/accession_number before stating which
551
+ SEC form supplied a transaction.
443
552
  Do not use this endpoint for Brazilian companies; use get_disclosures()
444
553
  with document_type='insiders' for Brazilian insider-trading disclosures.
445
554
 
@@ -66,7 +66,10 @@ class AlternativeDataFunds:
66
66
  """
67
67
  List ETFs available in the public-sources ETF registry.
68
68
  Use this for ETF discovery because ETFs are not returned by listed-
69
- company search endpoints.
69
+ company search endpoints. Rows can combine fund identity, issuer,
70
+ index metadata and latest NAV/AUM/holder metrics from sources such as
71
+ CVM/FNET, B3 index composition or manager/issuer official holdings,
72
+ depending on coverage.
70
73
 
71
74
  Parameters
72
75
  ----------------
@@ -130,7 +133,11 @@ class AlternativeDataFunds:
130
133
  asset ticker. For CVM/CDA rows without same-day daily NAV, the API may
131
134
  compute position_weight from the latest prior daily report within seven
132
135
  days; company_nav_reference_date and company_nav_source identify that
133
- NAV source when it differs from the holdings reference date.
136
+ NAV source when it differs from the holdings reference date. Rows expose
137
+ source/snapshot_type fields such as B3 index composition, manager
138
+ official holdings, issuer-official holdings or SEC N-PORT depending on
139
+ coverage. US official ETF holdings can identify assets by CUSIP when
140
+ ticker/ISIN enrichment is unavailable.
134
141
 
135
142
  Parameters
136
143
  ----------------
@@ -180,7 +187,10 @@ class AlternativeDataFunds:
180
187
  ) -> dict:
181
188
  """
182
189
  Portfolio exposures for a Brazilian CVM fund or ETF (asset class,
183
- issuer, sector, indexer, maturity, country).
190
+ issuer, sector, indexer, maturity, country). This endpoint accepts
191
+ Brazilian fund CNPJs and supported BR ETF tickers. US ETF tickers can
192
+ be available in get_holdings() while still being outside exposures
193
+ coverage.
184
194
  Use sector exposure with company sector endpoints when comparing fund
185
195
  exposure with B3 company peer groups.
186
196
  Exposure dimensions are source-dependent: for Brazilian ETFs, issuer
@@ -250,8 +260,11 @@ class AlternativeDataFunds:
250
260
  limit: int = 100,
251
261
  ) -> dict:
252
262
  """
253
- Look-through resolution for a fund or ETF (resolves nested fund
254
- positions to underlying assets when available).
263
+ Look-through resolution for a Brazilian fund or ETF (resolves nested
264
+ fund positions to underlying assets when available). This endpoint
265
+ accepts Brazilian fund CNPJs and supported BR ETF tickers; US ETF
266
+ tickers can be available in get_holdings() while still being outside
267
+ look-through coverage.
255
268
  Use this after holdings when nested fund positions need to be expanded
256
269
  into underlying assets.
257
270
  For direct-equity ETFs, look-through can return opaque asset_key values
@@ -125,7 +125,10 @@ class AlternativeDataMetadata:
125
125
  Parameters
126
126
  ----------------
127
127
  query: str
128
- Free-text search over company name, ticker, CNPJ, or CIK.
128
+ Free-text search over company name, ticker, CNPJ, or CVM code.
129
+ US rows can include CIK and ISIN in the response, but directory
130
+ search by CIK/ISIN/LEI is not a guaranteed resolver; call the
131
+ target endpoint directly when it documents those identifiers.
129
132
  Field is not required. Example: 'PETROBRAS'.
130
133
  jurisdiction: str
131
134
  Filter by jurisdiction: 'BR' or 'US'.
@@ -157,7 +160,10 @@ class AlternativeDataMetadata:
157
160
  Parameters
158
161
  ----------------
159
162
  query: str
160
- Free-text search over company name, ticker, CNPJ, or CIK.
163
+ Free-text search over company name, ticker, CNPJ, or CVM code.
164
+ US rows can include CIK and ISIN in the response, but directory
165
+ search by CIK/ISIN/LEI is not a guaranteed resolver; call the
166
+ target endpoint directly when it documents those identifiers.
161
167
  Field is not required. Example: 'PETROBRAS'.
162
168
  jurisdiction: str
163
169
  Filter by jurisdiction: 'BR' or 'US'.
@@ -73,10 +73,11 @@ class AlternativeDataOwnership:
73
73
  filter. For Brazilian ownership questions, call get_ownership_current(),
74
74
  get_ownership_control_group(), get_ownership_free_float() and
75
75
  get_ownership_official_notices() when this endpoint returns no rows.
76
- Some responses can include multiple rows for the same holder across
77
- share classes, ownership categories, filings or source protocols;
78
- inspect category, class, protocol/source and reference date before
79
- aggregating percentages.
76
+ The API deduplicates repeated rows from older FRE source documents for
77
+ the same reference date where possible, while still preserving distinct
78
+ rows for the same holder when they represent different share classes,
79
+ ownership categories or roles. Inspect category, class, protocol/source
80
+ and reference date before aggregating percentages.
80
81
 
81
82
  Parameters
82
83
  ----------------
@@ -108,7 +109,9 @@ class AlternativeDataOwnership:
108
109
  Use this as the primary current ownership summary when top-shareholder
109
110
  snapshots are empty or when a compact ownership object is sufficient.
110
111
  Reference dates usually come from CVM/FRE reporting periods or parsed
111
- IR structures and are not necessarily strict as-of timestamps.
112
+ IR structures and are not necessarily strict as-of timestamps. For
113
+ Brazilian FRE data, control/free-float blocks are based on the latest
114
+ source document for the selected reference date when available.
112
115
 
113
116
  Parameters
114
117
  ----------------
@@ -291,7 +294,9 @@ class AlternativeDataOwnership:
291
294
  Use this for who controls the company; use get_shareholder_holdings()
292
295
  for a reverse lookup of one holder across companies.
293
296
  Reference dates usually come from CVM/FRE reporting periods and can
294
- denote a filing year/base period rather than the load date.
297
+ denote a filing year/base period rather than the load date. The API
298
+ filters current control rows to the latest FRE source document for the
299
+ selected reference date when protocols identify multiple filed versions.
295
300
 
296
301
  Parameters
297
302
  ----------------
@@ -306,7 +311,10 @@ class AlternativeDataOwnership:
306
311
  Free float breakdown for a company.
307
312
  Reference dates usually come from CVM/FRE reporting periods or parsed
308
313
  IR structures and can denote a filing year/base period rather than the
309
- load date.
314
+ load date. For Brazilian FRE distribution-of-capital tables, numeric
315
+ versions are ordered numerically so version 13 is treated as newer than
316
+ version 9. Returned zero values can be valid source values rather than
317
+ missing data.
310
318
 
311
319
  Parameters
312
320
  ----------------
@@ -364,6 +372,57 @@ class AlternativeDataOwnership:
364
372
  "offset": offset,
365
373
  })
366
374
 
375
+ def get_sec_13f_holdings(
376
+ self,
377
+ manager_id: Optional[str] = None,
378
+ asset_id: Optional[str] = None,
379
+ start_date: Optional[str] = None,
380
+ end_date: Optional[str] = None,
381
+ limit: int = 100,
382
+ offset: int = 0,
383
+ ) -> dict:
384
+ """
385
+ SEC 13F-HR institutional investment-manager holdings. Use ``manager_id``
386
+ for manager-level filings (CIK, manager name or SEC ticker when the
387
+ manager is itself a SEC registrant) and ``asset_id`` for issuer exposure
388
+ lookup (ticker, CUSIP, ISIN or issuer name).
389
+
390
+ 13F rows are manager filing disclosures, not issuer top-shareholder
391
+ tables. They do not cover every holder, non-reporting investors, short
392
+ positions or all economic exposure. Use this endpoint with SEC filings,
393
+ beneficial ownership and market data when the question needs
394
+ institutional-holder context for US-listed assets.
395
+
396
+ Parameters
397
+ ----------------
398
+ manager_id: str
399
+ Optional SEC manager CIK, manager name or registrant ticker.
400
+ Example: '0000886982' or 'GOLDMAN SACHS'.
401
+ asset_id: str
402
+ Optional issuer ticker, CUSIP, ISIN or issuer name.
403
+ Example: 'AAPL' or 'US0378331005'.
404
+ start_date: str
405
+ Start filing date in YYYY-MM-DD format.
406
+ Field is not required.
407
+ end_date: str
408
+ End filing date in YYYY-MM-DD format.
409
+ Field is not required.
410
+ limit: int
411
+ Maximum number of rows to return.
412
+ Field is not required. Default: 100.
413
+ offset: int
414
+ Number of results to skip for pagination.
415
+ Field is not required. Default: 0.
416
+ """
417
+ return self._get("sec/13f-holdings", {
418
+ "manager_id": manager_id,
419
+ "asset_id": asset_id,
420
+ "start_date": start_date,
421
+ "end_date": end_date,
422
+ "limit": limit,
423
+ "offset": offset,
424
+ })
425
+
367
426
  def get_institutional_holders(
368
427
  self,
369
428
  identifier: str,
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: btgsolutions_dataservices_python_client
3
- Version: 4.4.2
3
+ Version: 4.5.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
@@ -620,6 +620,12 @@ companies.get_disclosures(company_id='PETR4', document_type='repurchase')
620
620
  companies.get_disclosures(company_id='PETR4', document_type='insider')
621
621
  ```
622
622
 
623
+ For Brazilian governance endpoints, current board and summary responses prefer
624
+ the latest raw FRE filing when available. Returned governance summaries can
625
+ include `latest_reference_date`, `latest_version`, `latest_document_id` and
626
+ `structure_source`; alternate B3 tickers/units such as `BPAC11` can resolve to
627
+ the underlying listed company when covered by the source metadata.
628
+
623
629
  #### Alternative Data - People
624
630
 
625
631
  ```python
@@ -661,6 +667,13 @@ ownership.get_institutional_holders(identifier='VALE3')
661
667
  ownership.get_fund_holders(identifier='PETR4', identifier_type='b3_ticker')
662
668
  ```
663
669
 
670
+ For Brazilian ownership/free-float endpoints, current control and free-float
671
+ responses use the latest FRE source document/version for the selected reference
672
+ date when available. Repeated older source documents are deduplicated where
673
+ possible, while distinct rows for the same holder across classes, roles or
674
+ ownership categories are preserved. Zero free-float or independence percentages
675
+ can be valid source values, not missing data.
676
+
664
677
  #### Alternative Data - Macro & Markets
665
678
 
666
679
  ```python