Skip to main content
Exact filed magnitudes are decimal strings, not floats. Schema 2 may put them in compact v cells or in aligned data.fields arrays. Parse exact strings with a decimal type so no precision is lost.

​
Magnitudes are strings

Exact cells are strings: "416161000000" or { "v": "416161000000", "d": "≈$416.2B" }. Use Decimal in Python or a decimal library in JS; never float, which would silently drop precision on a large magnitude. Only convert to a display number at the very edge, and label the conversion. Ratios can be plain JSON numbers.

​
The unit vocabulary

Money units are the filer’s ISO-4217 reporting currency, not a fixed USD vocabulary. Statement blocks carry reporting.reporting_currency; overview and price responses can also expose subject.entity.reporting_currency and subject.security.trading_currency. The unit policies are served by stock_reference with { "catalog": "units" }. A ratio is a fraction, not percentage points: 0.1561 means 15.61%. Multiply by 100 only at display.

​
Currency locations

Always format from these currency fields. If a value is 36800000000 with reporting_currency: "EUR", write EUR 36.8B, not USD 36.8B. Price-derived ratios that would mix reporting and trading currencies refuse with missing_operand: "currency_conversion" instead of inventing an FX rate.

​
The decimals scale

decimals mirrors XBRL’s reporting scale — the power of ten the filer rounded to. -6 means the value was reported in millions, -3 in thousands, and a positive value (like 2 on EPS) means places after the decimal point. It tells you the precision the filer actually reported; the value string is already the full magnitude, so you rarely need decimals for math — it is there for faithful display.

​
Status and provenance

Higher detail can carry:
  • direct/derived markers — whether the value came from one tagged concept or proven operands.
  • concept — the XBRL concept the value came from, e.g. us-gaap:NetIncomeLoss.
  • provenance — on price-derived cells: licensed_market_data or computed_from_prices.
The concepts catalog in stock_reference maps each served field to its XBRL concept.

​
Signs are meaningful

A negative number is information — preserve the sign end to end.
A negative retained_earnings is a real accumulated deficit; a negative financing_cash_flow is normal (cash paid out). Stripping the minus to make a value “look clean” changes its meaning.

​
Dates

Date-only fields use YYYY-MM-DD ("period_end": "2025-09-27"); timestamps in meta are UTC ISO-8601 with a Z ("published_at": "2026-06-26T18:42:30.172304Z"). Business dates (period_end, filed, transaction_date) are not data-currency signals — the clocks in Clocks and provenance are.

​
Absent values

A value you expected may instead be a refusal: { "unavailable": "not_reported" }. Check unavailable before doing math on any field. The Response model owns the value-cell and refusal shapes.