Units and currency
Interpret monetary values, percentages, ratios, per-share metrics, share counts, and display-currency conversion correctly.
Rangler returns machine-readable unit rules. Clients should not guess scale from a filing label or apply the frontend's display formatting to raw API numbers.
Unit classes
| Unit class | Representation | Example |
|---|---|---|
currency | Base units of period.display_currency | 1250000000 means NGN 1.25 billion when display_currency is NGN. |
per_share | Major currency units per share | 4.25 means NGN 4.25 per share when the display currency is NGN. |
shares | Individual shares | 1500000000 means 1.5 billion shares. |
percent | Decimal fraction | 0.184 means 18.4%. |
ratio | Decimal multiple | 2.3 means 2.3×. |
currency_per_share | Major currency units per share | Interpret with the period display currency. |
The response's unit_convention map and the metric catalog are authoritative. Each metric definition declares its unit class and value representation.
Never multiply every value by the filing's printed thousands or millions label. Standardized currency values have already been converted to base units by Rangler.
Reported and display currency
Each period distinguishes:
reported_currency: the statement currency selected from the issuer's filingdisplay_currency: the currency of monetary values returned inmetricscurrency: a compatibility field for the period's returned monetary and per-share values
With display_currency=native, reported and display currency are normally identical. With an ISO 4217 target, only monetary unit classes are converted.
{
"reported_currency": "NGN",
"display_currency": "USD",
"currency_conversion": {
"source_currency": "NGN",
"target_currency": "USD",
"rate": 0.00064,
"rate_date": "2025-12-31",
"status": "converted"
}
}currency_conversion records the rate and period date used. Conversion does not change whether an accounting value was reported or derived; that classification remains in metric_origins.
Selecting a native currency
Some company histories contain more than one reported currency. available_reported_currencies lists the valid native choices and selected_reported_currency records the selected lane.
GET /v1/financials/statements?ticker=ACCESSCORP&country_code=NG&display_currency=native&reported_currency=NGNreported_currency is only valid with native display. To convert a selected series, first choose the appropriate native series, then request the desired display_currency according to the endpoint contract.
Display formatting belongs at the edge
The API owns unit semantics and conversion. A UI may abbreviate 1250000000 as 1.25bn or render 0.184 as 18.4%, but it must not change the underlying meaning. Preserve the raw number and unit metadata for exports and calculations.
Financial response model
Understand issuer identity, fiscal periods, standardized metrics, ratios, metadata, and filing sources in statement responses.
Periods, derived quarters, and restatements
Store financial periods correctly across calendar and fiscal reporting, cumulative interim values, derived periods, and restated comparatives.