form4api 0.7.1__tar.gz → 0.9.0__tar.gz

{form4api-0.7.1 → form4api-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: form4api
-Version: 0.7.1
+Version: 0.9.0
 Summary: Python client for the Form4API — real-time SEC Form 4 insider trading, Form 144 intent-to-sell, institutional 13F-HR, and congressional STOCK Act trading data, including the insider/Congress convergence signal
 License-Expression: MIT
 Project-URL: Homepage, https://www.form4api.com
@@ -81,6 +81,7 @@ asyncio.run(main())
 
 | Resource | Methods |
 |---|---|
+| `client.search(q, limit=None)` | Combined company + insider lookup — not namespaced under a resource |
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
 | `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.directory(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
 | `client.companies` | `.get(ticker)`, `.insiders(ticker)`, `.list(**params)` |
@@ -94,6 +95,19 @@ asyncio.run(main())
 | `client.status` | `.history(**params)` |
 | `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
 
+**Congress date quality.** Each congress trade (and convergence leg) has
+`disclosure_lag_days: int | None` and `date_quality: str | None`. When the
+filing's own dates are impossible or implausible, the lag is `None` and
+`date_quality` is one of `"transaction_after_disclosure"`,
+`"future_transaction_date"` or `"implausible_lag"`; the raw dates are still
+returned. A lag over 45 days is not a legal finding.
+
+```python
+for t in client.congress.trades(ticker="NVDA"):
+    lag = f"dates unreliable ({t.date_quality})" if t.disclosure_lag_days is None else f"{t.disclosure_lag_days}d"
+    print(t.politician.full_name, t.transaction_date, lag)
+```
+
 Every plan-gated endpoint the API exposes has a typed method here. Calling one
 your key isn't entitled to raises `PlanError` (HTTP 402) carrying
 `required_plan`, `current_plan`, and `upgrade_url` rather than failing opaquely.
@@ -108,16 +122,21 @@ For LLM workflows, `form4api-mcp` exposes the same endpoints as tools.
 
 ```python
 client.transactions.list(
-    ticker="AAPL",        # filter by ticker
+    ticker="AAPL",        # filter by ticker — accepts up to 25 comma-separated symbols
     cik="0000320193",     # or by company CIK
     insider_cik="...",    # filter by insider CIK
     code="P",             # transaction code: P=purchase, S=sale, A=grant, etc.
     from_date="2026-01-01",
     to_date="2026-12-31",
+    filed_from="2026-01-01",  # filters on Filing.FiledAt (when it hit EDGAR), not the trade date
+    filed_to="2026-12-31",
     exclude_10b5=True,    # omit trades filed under a Rule 10b5-1 plan
     per_page=100,
     page=1,
 )
+
+# Multi-ticker lookup in one call
+client.transactions.list(ticker="AAPL,MSFT,NVDA")
 ```
 
 ### Granular filtering (v0.4.0+)
@@ -166,6 +185,11 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 | `is_derivative` | `bool` | Derivative security flag |
 | `transaction_date` | `str` | ISO datetime |
 | `period_of_report` | `str` | ISO datetime |
+| `return1d`/`return1w`/`return1m`/`return3m`/`return6m` | `float \| None` | Forward return since the transaction date, as a fraction (0.109 = +10.9%); `None` until enough time/price data has elapsed |
+| `value_quality` | `str \| None` | Confidence flag on `total_value`'s pricing source |
+| `accepted_at` | `str \| None` | Precise UTC SEC-acceptance instant; `None` if not captured |
+| `document_url` | `str \| None` | Public SEC document URL |
+| `institutional_ownership` | `InstitutionalOwnership \| None` | Latest 13F institutional ownership snapshot for the ticker, when available |
 
 ### Company fields
 
@@ -181,6 +205,27 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 | `state_of_incorporation` | `str \| None` | Two-letter state code |
 | `website` | `str \| None` | Company website as filed with SEC |
 
+### Search
+
+`client.search(q, limit=None)` looks up companies and insiders by name or
+ticker in a single call — useful for a combined search box where you don't
+know in advance whether the user typed a ticker or a person's name. `q` must
+be 2-64 characters; outside that range the API returns HTTP 400 and the SDK
+raises `Form4ApiError` with `error_code` `"QUERY_TOO_SHORT"` or
+`"QUERY_TOO_LONG"`. Insider matching is whitespace-tokenised, so `"tim cook"`
+matches an insider named `"Cook Timothy D"`. `limit` caps the number of
+results per array (1-20, API default 8).
+
+```python
+result = client.search("tim cook")
+for c in result.companies:
+    print(c.ticker, c.name, c.cik)
+for i in result.insiders:
+    # i.ticker is a ticker associated with the insider and may be None —
+    # its exact meaning is still settling on the backend.
+    print(i.cik, i.name, i.title, i.ticker)
+```
+
 ### Pagination
 
 `paginate()` pages through the data until it runs out (a short or empty page)

{form4api-0.7.1 → form4api-0.9.0}/README.md

@@ -62,6 +62,7 @@ asyncio.run(main())
 
 | Resource | Methods |
 |---|---|
+| `client.search(q, limit=None)` | Combined company + insider lookup — not namespaced under a resource |
 | `client.transactions` | `.list(**params)`, `.paginate(**params)` |
 | `client.insiders` | `.search(name, **params)`, `.get(cik)`, `.list(**params)`, `.directory(**params)`, `.transactions(cik, **params)`, `.summary(cik)` *(Pro)*, `.scorecard(cik)` *(Pro)*, `.leaderboard(**params)` *(Business)* |
 | `client.companies` | `.get(ticker)`, `.insiders(ticker)`, `.list(**params)` |
@@ -75,6 +76,19 @@ asyncio.run(main())
 | `client.status` | `.history(**params)` |
 | `client.webhooks` | `.create(url, event_types)`, `.list()`, `.delete(id)`, `.events(**params)` |
 
+**Congress date quality.** Each congress trade (and convergence leg) has
+`disclosure_lag_days: int | None` and `date_quality: str | None`. When the
+filing's own dates are impossible or implausible, the lag is `None` and
+`date_quality` is one of `"transaction_after_disclosure"`,
+`"future_transaction_date"` or `"implausible_lag"`; the raw dates are still
+returned. A lag over 45 days is not a legal finding.
+
+```python
+for t in client.congress.trades(ticker="NVDA"):
+    lag = f"dates unreliable ({t.date_quality})" if t.disclosure_lag_days is None else f"{t.disclosure_lag_days}d"
+    print(t.politician.full_name, t.transaction_date, lag)
+```
+
 Every plan-gated endpoint the API exposes has a typed method here. Calling one
 your key isn't entitled to raises `PlanError` (HTTP 402) carrying
 `required_plan`, `current_plan`, and `upgrade_url` rather than failing opaquely.
@@ -89,16 +103,21 @@ For LLM workflows, `form4api-mcp` exposes the same endpoints as tools.
 
 ```python
 client.transactions.list(
-    ticker="AAPL",        # filter by ticker
+    ticker="AAPL",        # filter by ticker — accepts up to 25 comma-separated symbols
     cik="0000320193",     # or by company CIK
     insider_cik="...",    # filter by insider CIK
     code="P",             # transaction code: P=purchase, S=sale, A=grant, etc.
     from_date="2026-01-01",
     to_date="2026-12-31",
+    filed_from="2026-01-01",  # filters on Filing.FiledAt (when it hit EDGAR), not the trade date
+    filed_to="2026-12-31",
     exclude_10b5=True,    # omit trades filed under a Rule 10b5-1 plan
     per_page=100,
     page=1,
 )
+
+# Multi-ticker lookup in one call
+client.transactions.list(ticker="AAPL,MSFT,NVDA")
 ```
 
 ### Granular filtering (v0.4.0+)
@@ -147,6 +166,11 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 | `is_derivative` | `bool` | Derivative security flag |
 | `transaction_date` | `str` | ISO datetime |
 | `period_of_report` | `str` | ISO datetime |
+| `return1d`/`return1w`/`return1m`/`return3m`/`return6m` | `float \| None` | Forward return since the transaction date, as a fraction (0.109 = +10.9%); `None` until enough time/price data has elapsed |
+| `value_quality` | `str \| None` | Confidence flag on `total_value`'s pricing source |
+| `accepted_at` | `str \| None` | Precise UTC SEC-acceptance instant; `None` if not captured |
+| `document_url` | `str \| None` | Public SEC document URL |
+| `institutional_ownership` | `InstitutionalOwnership \| None` | Latest 13F institutional ownership snapshot for the ticker, when available |
 
 ### Company fields
 
@@ -162,6 +186,27 @@ client.transactions.list(min_shares=10_000, max_shares=100_000)
 | `state_of_incorporation` | `str \| None` | Two-letter state code |
 | `website` | `str \| None` | Company website as filed with SEC |
 
+### Search
+
+`client.search(q, limit=None)` looks up companies and insiders by name or
+ticker in a single call — useful for a combined search box where you don't
+know in advance whether the user typed a ticker or a person's name. `q` must
+be 2-64 characters; outside that range the API returns HTTP 400 and the SDK
+raises `Form4ApiError` with `error_code` `"QUERY_TOO_SHORT"` or
+`"QUERY_TOO_LONG"`. Insider matching is whitespace-tokenised, so `"tim cook"`
+matches an insider named `"Cook Timothy D"`. `limit` caps the number of
+results per array (1-20, API default 8).
+
+```python
+result = client.search("tim cook")
+for c in result.companies:
+    print(c.ticker, c.name, c.cik)
+for i in result.insiders:
+    # i.ticker is a ticker associated with the insider and may be None —
+    # its exact meaning is still settling on the backend.
+    print(i.cik, i.name, i.title, i.ticker)
+```
+
 ### Pagination
 
 `paginate()` pages through the data until it runs out (a short or empty page)

{form4api-0.7.1 → form4api-0.9.0}/form4api/__init__.py

@@ -11,6 +11,11 @@ from form4api._types import (
     Company,
     Insider,
     InsiderSignal,
+    InstitutionalOwnership,
+    SearchCompany,
+    SearchInsider,
+    SearchResults,
+    TopHolder,
     Transaction,
     WebhookCreated,
     WebhookEvent,
@@ -31,6 +36,11 @@ __all__ = [
     "Insider",
     "Company",
     "InsiderSignal",
+    "InstitutionalOwnership",
+    "SearchCompany",
+    "SearchInsider",
+    "SearchResults",
+    "TopHolder",
     "WebhookCreated",
     "WebhookEvent",
     "WebhookSubscription",

{form4api-0.7.1 → form4api-0.9.0}/form4api/_client.py

@@ -9,6 +9,7 @@ from typing import Any, TypeVar
 import httpx
 
 from form4api._errors import AuthError, Form4ApiError, NotFoundError, PlanError, RateLimitError
+from form4api._types import SearchResults
 
 # Sent as the User-Agent so the backend can attribute traffic to the Python SDK
 # channel (the admin dashboard buckets by client). Read from installed package
@@ -105,6 +106,22 @@ class Form4ApiClient:
     def close(self) -> None:
         self._http.close()
 
+    def search(self, q: str, limit: int | None = None) -> SearchResults:
+        """Search companies and insiders by name or ticker in one call.
+
+        ``q`` must be 2-64 characters, or the API raises `Form4ApiError`
+        (HTTP 400) with `error_code` `QUERY_TOO_SHORT` or `QUERY_TOO_LONG`.
+        Insider matching is whitespace-tokenised, so `"tim cook"` matches an
+        insider named `"Cook Timothy D"`. `limit` caps the number of results
+        per array (1-20, API default 8) and defaults to the API's own default
+        when omitted. Free tier, no plan gate.
+        """
+        params: dict[str, str] = {"q": q}
+        if limit is not None:
+            params["limit"] = str(limit)
+        data = self._get("/v1/search", params)
+        return SearchResults._from_dict(data)
+
     def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
         url = self._base_url + path
         last_exc: Exception | None = None
@@ -224,6 +241,14 @@ class AsyncForm4ApiClient:
     async def close(self) -> None:
         await self._http.aclose()
 
+    async def search(self, q: str, limit: int | None = None) -> SearchResults:
+        """Async twin of `Form4ApiClient.search`. See there for parameter details."""
+        params: dict[str, str] = {"q": q}
+        if limit is not None:
+            params["limit"] = str(limit)
+        data = await self._get("/v1/search", params)
+        return SearchResults._from_dict(data)
+
     async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
         url = self._base_url + path
         last_exc: Exception | None = None