Secedgar Compare Companies
secedgar_compare_companiesCompare 2-10 named companies across 1-8 XBRL concepts, aligned on fiscal years (annual) or calendar quarters (quarterly). This is the middle shape between secedgar_get_financials (one company, one concept, full history) and secedgar_fetch_frames (one concept, one period, every reporting company) — reach for it when the question names the companies. One companyfacts read per company, resolved through the same frame dedup and tag priority as secedgar_get_financials so the numbers agree. Balance-sheet and entity-info concepts are filed as point-in-time values: an annual matrix takes each company’s fiscal-year-end snapshot and places it in the period of the fiscal year it closes, beside that year’s income-statement lines (interim and cover-date snapshots stay out), and a quarterly matrix aligns each snapshot on the calendar quarter it falls in. The inline matrix covers the most recent periods up to periods, trimmed further when companies x concepts x periods is too large to return in one response; the full aligned series is materialized as df_ for growth rates and spreads — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query. A company that fails to resolve is reported in failed_companies and the comparison proceeds with the rest, and a company that does not report a concept is reported in gaps with the tags that were tried — never interpolated or zero-filled. A company named twice (a ticker and its CIK) is read once, under the first input. Where the schema accepts a longer list, companies past the first 10 and concepts past the first 8 distinct are not read; they come back in deferred_companies and deferred_concepts to re-call with. A company that reports a concept only for periods older than the inline window is named in caveats with its newest period. A concept that is neither a friendly name nor an XBRL tag is reported once in unknown_concepts with the closest supported names, and fails the call only when every concept is one. Off-calendar filers and unit mismatches are surfaced in caveats rather than silently mixed.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"companies": "<companies>",
"concepts": "<concepts>"
},
"name": "secedgar_compare_companies"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| periods | No | Upper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query. Capped at 12: a larger value, up to 1000, returns what 12 returns. | |
| concepts | Yes | Concepts to compare — friendly names like "revenue" or "net_income", in any spelling secedgar_get_financials accepts (discover them with secedgar_search_concepts), or raw XBRL tags. The first 8 distinct concepts are compared, spellings of one concept counting once and an unrecognized name not at all; a longer list, up to 100, returns each input naming a further concept unread in deferred_concepts. | |
| taxonomy | No | XBRL taxonomy to resolve concepts under. Use ifrs-full only when every company in the list reports under IFRS; mixing IFRS and US GAAP filers in one call resolves them all under the same taxonomy. | us-gaap |
| companies | Yes | Companies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs. The first 10 inputs are read; a longer list, up to 100, returns the rest unread in deferred_companies. | |
| period_type | No | Align on fiscal years, each under the calendar-year key SEC frames it as (annual), or on calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats. | annual |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The periods cap applied. | |
| gaps | No | Company-concept pairs with no value in any period, never zero-filled; a pair with values only before the inline window is in caveats instead. | |
| cells | No | Inline matrix values, covering the periods listed in periods[]. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of periods shown inline. | |
| notice | No | Guidance on deferred inputs, periods the inline matrix dropped, or the staged dataframe. | |
| caveats | No | Comparability warnings (company ones prefixed with the name): missing quarters; a concept 2+ years behind the company's other lines; an annual instant with no fiscal-year-end value; differing period ends or units; values only before the inline window; merged inputs; how a ticker was read. | |
| dataset | No | Dataframe of the full aligned series, every period, with cells[] columns. Absent when canvas is unavailable. | |
| periods | No | Inline period keys, newest first; fewer than requested when the cell count shrank the window (see notice). | |
| concepts | No | Concepts covered, in input order; spellings of one concept appear once, under the first. | |
| taxonomy | No | Taxonomy the concepts were resolved under, echoed from input. | |
| companies | No | Companies included in the comparison. | |
| truncated | No | True when the aligned series has more periods than the inline matrix shows. | |
| period_type | No | Period alignment used, echoed from input. | |
| failed_companies | No | Companies excluded from the matrix; the rest still compare. | |
| unknown_concepts | No | Concepts neither a supported name nor an XBRL tag, reported once rather than as per-company gaps; secedgar_search_concepts lists the supported names. | |
| deferred_concepts | No | Inputs naming a concept past the first 8 distinct, unread, as supplied. | |
| deferred_companies | No | Company inputs past the first 10, unread, as supplied. |