Skip to content

Changelog

Changes to the API. During the beta, changes that break existing use are announced here at least 30 days ahead, except when a change is needed for security or legal reasons.

1.0.0-beta.6

A figure can be read from a company's own XBRL concept, an extension the filer defines for a line no standard concept fits, once Thaler has reviewed the concept against the filing and has read the filing's own instance. Such a figure fills a period no standard concept states for the company; it never replaces a figure read from a standard concept.

  • A lineage row for such a figure carries taxonomy: "ext" and the concept's local name in concept, as before, and fact_ledger: "report". Its report_fact adds concept_qname, the concept as the filing names it (the filer's prefix and the local name, such as jpm:CommonEquityTier1Capital), and concept_label, the filer's label for it. The label is the one in the latest filing that describes the concept, which can differ from the label in the filing the figure was read from.
  • A revision row carries the same report_fact, with both fields; it has no taxonomy or concept of its own.
  • Both fields are absent on a row whose concept is a standard one.

What changes for a request that names nothing new, once a company's figures are read this way: GET /v1/securities/{ticker}/metrics can return figures for periods it returned none for (the company's own concept states them, and no standard concept does), and free cash flow where such a figure supplies its capital expenditures; GET /v1/screen can carry a figure it had as null for the same reason. No figure read from a standard concept changes. A figure read from a company's own concept gives way to the standard one once a standard concept states its period, in a later filing or once company facts catch up with a filing Thaler read first. Where a company states a quarter only through its own concept, the stated quarter now stands where clients that subtract year-to-date figures derived one; the two can differ by the filer's rounding.

A client generated from the previous document keeps working; generate it again to pick up the two fields.

1.0.0-beta.5

The catalog has a fourth statement, notes: lines a company states in its notes and regulatory disclosures, among them a bank's capital ratios and amounts, an insurer's statutory capital and surplus and its prior-year reserve development, a company's remaining performance obligation, and an energy company's standardized measure of proved reserves. Some are read from facts the filing itself tags by member, such as a parent company's ratio under the standardized approach.

  • GET /v1/securities/{ticker}/metrics takes statement=notes, and meta.statement can be notes on such a read.
  • GET /v1/metrics lists the fourteen notes lines. A mapping that reads a fact by its members carries dimensions: the axis and member each one requires, exactly.
  • Lineage and revision rows carry fact_ledger (raw or report). A row read from a filing's own instance carries report_fact: its accession number, its ordinal in the instance, its fact_id in the inline document, and its dimensions with the filer's labels where it gives them. For such a row raw_fact_id is a version-8 UUID from the sha256 of report:{accession}:{ordinal}, not a company-facts id.
  • A ratio is a fraction, as the catalog's ratios are: 0.155 is 15.5%.

Three things change for a request that names nothing new. GET /v1/metrics answers fourteen more entries. A read of /v1/securities/{ticker}/metrics with no keys and no statement (and period=latest) now includes a company's notes lines, so its 500-row window reaches back less far for a company that states them; name keys or a statement to read exactly what you read before. And every lineage and revision row carries fact_ledger.

A client generated from the previous document keeps working; generate it again to pick up the new fields.

1.0.0-beta.4

The Screener reads a company the way its statements are read, and the catalog has six ratios on a bank's and an insurer's lines. A request that names nothing new answers as it did; each Screener row carries forty more fields.

  • GET /v1/screen takes model (general, bank, insurance, reit, utility or energy): the rows are the companies read under that model, and meta.total, meta.set_aside and meta.universe all count within it. meta.model names it. general takes in the companies the SEC has not classified. Without model, the Screener covers every company, as before.
  • Each Screener row carries sic, the company's SIC code (null while it is unclassified), and industry_model, the model its statements are read under, and thirty-eight industry figures. Each figure is a where and sort column, and columns accepts all forty names; sic and industry_model are text, so they filter and sort nothing. - A bank's: net_interest_income, noninterest_income, noninterest_expense, provision_for_credit_losses, net_interest_income_after_provision, loans_gross, loans_net, allowance_for_credit_losses_on_loans, deposits, noninterest_bearing_deposits, and the ratios efficiency_ratio, loans_to_deposits, allowance_to_loans and noninterest_bearing_deposit_share. - An insurer's: premiums_earned, net_investment_income, policyholder_benefits_and_claims, benefits_losses_and_expenses, liability_for_unpaid_claims, future_policy_benefits, unearned_premiums, deferred_policy_acquisition_costs, and the ratios benefits_and_claims_to_premiums and benefits_and_expenses_to_premiums. - A REIT's: rental_income, property_operating_expenses, real_estate_tax_expense, real_estate_acquisitions, real_estate_net, real_estate_at_cost and real_estate_accumulated_depreciation. - A utility's: utility_operation_and_maintenance, utility_plant_net, regulatory_assets_noncurrent and regulatory_liabilities_noncurrent. - An energy and mining company's: exploration_expense, oil_and_gas_property_additions and oil_and_gas_properties_net.

A flow is the fiscal year's and a balance is the latest balance date's, as for every other figure, and a ratio is read at the period of its lines. A model labels a figure and never hides it: a company that states a line carries it whatever its model, and the figure is null where the company does not state it.

  • GET /v1/metrics lists the six ratios, each with unit ratio, no statement, and its model (bank or insurance), and GET /v1/securities/{ticker}/metrics serves them by key for every period in which a company states their lines. A ratio is a fraction: 0.52 is 52%.

A client generated from the previous document keeps working; generate it again to pick up model and the new fields.

1.0.0-beta.3

Three additions, and a catalog nearly five times as wide (275 lines, from 57). A read of a company's metrics without keys or statement returns every line the company states, newest first, so its 500 rows now reach back fewer periods than before; for a line's whole history, name it in keys or read its statement, with collapse=true (up to 5,000 rows). Every other request answers as it did.

  • GET /v1/securities/{ticker}/metrics takes statement (income_statement, balance_sheet or cash_flow): every line the catalog places on that statement that the company states, or with keys, those of them on it. A statement read with collapse=true takes the 5,000-row limit a keyed read does, so a company's three statements are three requests.
  • A company's profile carries industry: its SIC code, the SEC's title for it, and the model its statements are read under (general, bank, insurance, reit, utility or energy), which follows from the code. It is absent while the SEC has not classified the company.
  • Each entry of GET /v1/metrics carries models, the industry models the line belongs to; it is empty for a line every company can state. The catalog holds the lines a bank, an insurer, a REIT, a utility and an energy company state beside every company's own.

IndustryModel is a new enum in responses; a model added to it later will be announced here first.

1.0.0-beta.2

The OpenAPI document now matches what the API sends. No request changed, and no documented field of a response.

  • Every figure is a Decimal or NullableDecimal: a string of digits with a sign and a fraction when there is one, never a number, so a client can parse it without losing digits. Prices, holders, segments and the filings of a day now say so as the metrics did.
  • A value that can be null says so the OpenAPI 3.1 way, with null in its type. The 3.0 keyword the document used before is ignored by tools that read 3.1.
  • keys, forms, items and tickers are arrays sent comma-separated (style: form, explode: false), as they always were on the wire.
  • value_kind on a metric value is reported or derived, as it is in the catalog.
  • A filing’s details and documents, a day’s counts by form and by day, and IEX’s attribution have named schemas.
  • Endpoints are tagged by resource: securities, metrics, filings, insiders, holders, segments, prices, screen, releases.
  • Filings no longer include a reading object, and lineage rows no longer include two review fields. Neither was in the document, so a client generated from it never read them.

A client generated from the previous document keeps working; generate it again to pick up the types.

1.0.0-beta.1

The first beta.

  • Nineteen read-only endpoints: companies, metrics with point-in-time reads, lineage, revisions, raw concepts, filings, insider trades, institutional holders, segments, prices, the Screener and the current release.
  • API keys, up to ten per account, with optional expiry.
  • Limits of 60 requests a minute, 20,000 a month and 4 at a time per account, reported in the IETF RateLimit headers.
  • Errors as RFC 9457 problem details.