Trading Agent Data
Methodology and data dictionary
Where every figure comes from, what was done to it, and what was deliberately left out. This page is the reference the API's notes and schema fields summarise. Changes are dated on the changelog.
1. What point-in-time means here
Every value is stored with the date it became public (filed). A query with as_of returns only rows whose filed is on or before that date, so a backtest or a study at any past date sees exactly what was knowable then.
The stored figure is the one FIRST reported for a period. When a later filing restates the same period, the original is kept and the restatement is not stored; the dataset is “as first reported”, a single vintage per period. Full multi-vintage history (every restatement with its own date) is on the roadmap and will be additive when it lands.
2. Markets, sources, licences
| Market | Source / licence | Coverage | `filed` | Basis | Update |
|---|---|---|---|---|---|
| United States .US | SEC EDGAR, XBRL company facts Public domain | ~7,000 filers from 2014 | SEC filing date of the 10-K / 10-Q | consolidated | weekly (automated) |
| Taiwan .TW | TWSE OpenAPI (MOPS) Taiwan Open Government Data License 1.0 — attribution embedded in every response | ~2,700 listed from 2013 | the statutory reporting deadline for the period — a deliberately LATE proxy, never earlier than the real release | consolidated | weekly (automated) |
| Korea .KR | FSS OpenDART, fnlttSinglAcntAll (fs_div=CFS) Public data; FSS confirmed in writing (27 Aug 2026) no separate approval is needed for commercial use | ~2,200 listed from 2015 | DART receipt date | consolidated | weekly (automated) |
| France .FR | INPI, Registre national des entreprises — comptes annuels (bulk stock + register API) Licence de réutilisation des informations du RNE, homologated under CRPA L.323-2 — attribution WITH last-update date required; deletions propagated | ~1.4 million (850,000 until the full stock finishes loading) from 2017 | dateDepot — the register's deposit date | solo (C complet / S simplifié), and consolidated (K) as separate rows where filed | weekly increment (automated), full stock reload from INPI's bulk file periodically |
| Belgium .BE | National Bank of Belgium, Central Balance Sheet Office — daily deposit batches (references + accountingData) NBB webservice conditions art. 5: use of downloaded annual-accounts data is free and unlimited | ~674,000 from April 2022 (structured deposits begin) | NBB deposit date | solo (statutory accounts, never group consolidation) | monthly (manual until automated) |
| Denmark .DK | Erhvervsstyrelsen — published annual reports (XBRL via distribution.virk.dk) Danish Business Authority open data | ~549,000 from 2013 (earlier filings are scans) | the register's publication timestamp | reported (the entity's published report; a parent with subsidiaries publishes the group) | monthly (manual until automated) |
| New Zealand charities .NZC | Charities Services, Charities Register annual returns CC BY 3.0 NZ | ~27,000 from FY2008 | the register's record date (after the balance date; moves later on amendment, never earlier) | solo | quarterly (manual) |
- United States: Revenue takes the first available of RevenueFromContractWithCustomerExcludingAssessedTax, Revenues, RevenueFromContractWithCustomerIncludingAssessedTax, SalesRevenueNet, chosen per period so a series does not stop where a filer changed tag. Equity is StockholdersEquity, the PARENT's share: for groups with minority partners, assets − liabilities − equity equals the non-controlling interest plus any redeemable (temporary) equity, which is a real line and not an error. 52/53-week years ending 1–7 January are labelled with the year they mostly belong to.
- Taiwan: Income-statement figures are cumulative year-to-date by Taiwan convention: Q2 = H1 total, Q4 = full year. Difference adjacent quarters for a single quarter.
- Korea: Consolidated statements only (CFS). Separate (OFS) statements are not loaded.
- France: See the liasse mapping below. Turnover lawfully absent from ~45% of deposits (confidentiality declarations).
- Belgium: Rubric 70 (turnover) is legitimately absent for abbreviated and micro filers; gross profit (9900) is reported instead. A parent's revenue here is the holding company's own, not the group's.
- Denmark: Only the reported year's undimensioned context is read; prior-year comparatives and dimensioned breakdowns are excluded. Earliest publication per company-period, not later corrections. Turnover on ~12% of filings (class B may publish gross profit). Liabilities = assets − equity.
- New Zealand charities: Registered charities, not companies. Assets/liabilities/equity appear only where the three balance; small filers leave fields blank and the register serves blank as 0.
3. Fields
| ticker / t | AAPL, 2330.TW, 005930.KS, 775670417.FR (SIREN), 0403091220.BE (KBO), 35651594.DK (CVR), CC21860.NZC (charity number) |
| issuer_id / c | the register's identifier: CIK, corp_code, SIREN, KBO, CVR, charity number |
| metric / m | revenue, gross_profit, operating_income, pretax_income, net_income, eps_diluted, assets, liabilities, equity, long_term_debt, cash (where the source carries it); derived: net_margin, gross_margin, operating_margin, asset_turnover, roa, roe, debt_to_equity |
| fy | fiscal year of the period end (52/53-week years ending 1–7 January are rolled back one year) |
| fp | FY, or Q1–Q4 for quarterly markets |
| period_end / end | last day of the period |
| filed | THE POINT-IN-TIME KEY: the date the figure became public, per market as in the table above. `as_of` filters filed <= as_of. |
| form | 10-K, 10-Q, annual; for France the reporting model and confidentiality flag (K/Public, C/Public, S/Confidential …); `derived` for ratios |
| basis | consolidated | solo | reported — which entity the figure describes. Compare like with like. |
| value / v, unit / u | the filer's figure in the filer's unit: USD, EUR, DKK, KRW, TWD, NZD; USD/shares for EPS; ratio for derived |
| company | name, activity_code (APE/NAF where stated), address (postcode + commune where stated), basis, and `source.url`: the register's own page for the entity |
4. Field mappings by source
France — INPI liasse cells (page | code | column)
The same code means different things on different pages, and the column that holds the current-year figure differs by line type (balance-sheet assets: column 3 = net; liabilities, equity and income lines: column 1). Each cell was verified against the printed Cerfa forms.
| Model | Cell | Metric |
|---|---|---|
| C / K (complete) | page 1, code CO, column 3 (net) | assets |
| C / K | page 2, code DL, column 1 | equity |
| C / K | page 2, code EE, column 1 | balance total (used only to derive liabilities when it equals assets) |
| C / K | page 3, code FJ, column 3 | revenue |
| C / K | page 3, code GG, column 3 | operating_income |
| C | page 4, code HN, column 1 | net_income |
| K | page 4, code R8, column 1 | net_income (group share); R6 = consolidated result |
| S (simplified) | page 1, codes 110 / 142 / 180, column 3 | assets / equity / balance total |
| S | page 2, codes 209 + 210 + 214 + 215 + 217 + 218, column 1 | revenue (sales of goods, services, production sold — code 232 is NOT used: it includes subsidies) |
| S | page 2, codes 270 / 310, column 1 | operating_income / net_income |
Belgium — NBB rubrics
20/58 → assets · 10/15 → equity · 70 → revenue · 9900 → gross_profit · 9901 → operating_income · 9903 → pretax_income · 9904 → net_income · 17 → long_term_debt. Liabilities = total − equity. Dates and currency come from the references file joined on the deposit reference; accountingData alone carries neither.
Denmark — XBRL (fsa namespace)
Revenue → revenue · GrossProfitLoss → gross_profit · ProfitLossFromOrdinaryOperatingActivities → operating_income · ProfitLoss → net_income · Assets → assets · Equity → equity; liabilities = assets − equity. The namespace prefix is resolved from the document's xmlns (it is arbitrary per filing); only the reported period's undimensioned context is read. NameOfReportingEntity is the company; NameOfSubmittingEnterprise is often the accountant and is not used.
United States — us-gaap concepts
revenue: RevenueFromContractWithCustomerExcludingAssessedTax → Revenues → RevenueFromContractWithCustomerIncludingAssessedTax → SalesRevenueNet (first available, per period) · net_income: NetIncomeLoss · eps_diluted: EarningsPerShareDiluted · assets: Assets · liabilities: Liabilities · equity: StockholdersEquity → StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest.
5. Exclusion and deduplication rules
- Period length: France drops deposits whose stated duration is under 11 or over 13 months (year-end changes leave stub periods that would sit under an annual label).
- Empty cells: a zero on a balance-sheet total is the register's empty cell and is excluded; assets, liabilities and equity are never served as 0 except for NZ charities, where the three are checked to balance at ingest.
- Derived liabilities (FR, BE, DK) are computed only when the passif total equals the actif total within 0.5%.
- Future dates: rows with a period end or filing date after today (filer typos) are dropped.
- One row per (ticker, metric, fiscal year, period, basis): the period that ends latest wins the label (52/53-week calendars), and within a period the EARLIEST filing wins — the as-first-reported rule.
- Deletions: records the register marks deleted are dropped at ingest, removed on the next increment when the deletion arrives later, and published at /api/v1/fundamentals/deletions.
- Nothing is imputed. A metric the filer lawfully omitted is absent.
6. Derived ratios
Computed on read from the facts of the same ticker, year, period and basis; form = derived, rounded to six decimals, absent when a denominator is missing or zero. Not included in bulk files.
| net_margin | net_income / revenue |
| gross_margin | gross_profit / revenue |
| operating_margin | operating_income / revenue |
| asset_turnover | revenue / assets |
| roa | net_income / assets |
| roe | net_income / equity |
| debt_to_equity | liabilities / equity |
7. Verification
Before each load, every market is checked for the balance-sheet identity (assets = liabilities + equity where all three are present, 0.5% tolerance), negative assets, equity above assets, revenue coverage and unit mix; a load is refused when the identity fails on more than 1% of periods. After each deploy, a set of hand-verified figures (each traced to the filer's own report — Apple FY2023 net sales, Microsoft FY2023 revenue, LVMH 2023 consolidated revenue, and growing) is compared with the live API. The set and the checker are in the repository (scripts/verify-warehouse.mjs); a failure blocks the release.
8. Attribution and the conditions that travel with the data
Every response, CSV and bulk file carries attributionper market, with the market's last-update date. For Taiwan (OGDL 1.0) and France (INPI RNE licence, art. 2.4 and 4.4) the attribution is a licence condition; for France so is mirroring deletions, and the licence forbids building searches by insolvency, disqualification, sanction or criminal status. The data licences pass these three conditions to licensees.
Questions about a specific figure: email the ticker, metric and period to contact@tradingagentapp.com with what you expected and where you read it. A confirmed mapping error is fixed in the next load and noted on the changelog.