API · Companies

Compare companies

Side-by-side KPIs for 2–5 issuers, Nordic + US can be mixed.

POST/api/v1/data/companies/compare

Fetches financials for each company in the input list and returns a structured comparison object. Nordic and US issuers can be mixed in a single call (e.g. "Neste vs ExxonMobil").

When to use this

A peer table on a company page.
Cross-market comparison ("how does the Helsinki gas peer compare to ExxonMobil?").
One-click answer to "who is winning?" for a small competitive set.

Body

Field	Type	Description
companiesrequired	string[]	2–5 names or tickers.
years	integer default: 3	Recent years per company (1–10).

Example

bash

curl https://api.clarifo.com/api/v1/data/companies/compare \
  -H "Authorization: Bearer $CLARIFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": ["Neste", "ExxonMobil"],
    "years": 3
  }'

Response

json

{
  "companies": [
    {
      "company_name": "Neste",
      "display_name": "Neste Oyj",
      "market": "nordic",
      "currency": "EUR",
      "latest_year": {
        "year": "2024",
        "revenue": 21990000000,
        "operating_income": 1850000000,
        "operating_margin": 8.4,
        "ebitda": 2400000000,
        "ebitda_margin": 10.9,
        "net_income": 640000000,
        "net_margin": 2.9,
        "roe": 7.0,
        "…": "…",
        "_provenance": {"primary_source": "nordic_avainluvut+keymetrics", "page_ids": ["…"]}
      },
      "by_year": {
        "2024": {"revenue": 21990000000, "ebitda": 2400000000, "ebitda_margin": 10.9, "net_income": 640000000, "…": "…"},
        "2023": {"revenue": 22458000000, "…": "…"}
      }
    },
    {
      "company_name": "Exxon Mobil Corp",
      "display_name": "Exxon Mobil Corp",
      "market": "us",
      "currency": "USD",
      "ticker": "XOM",
      "exchange": "NYSE",
      "latest_year": {"year": "2024", "revenue": 344582000000, "net_margin": 9.8, "…": "…"},
      "by_year": {"2024": {"…": "…"}, "2023": {"…": "…"}}
    }
  ],
  "kpis": [
    "revenue", "gross_profit", "gross_margin", "operating_income", "operating_margin",
    "ebit", "ebit_margin", "ebitda", "ebitda_margin", "net_income", "net_margin",
    "eps_diluted", "total_assets", "total_equity", "roe", "roa",
    "operating_cash_flow", "free_cash_flow", "capital_expenditures", "fcf_margin"
  ],
  "not_found": [],
  "computations": {
    "gross_margin": "gross_profit / revenue * 100",
    "operating_margin": "operating_income / revenue * 100",
    "roe": "net_income / total_equity * 100",
    "…": "…"
  },
  "data_quality_warnings": [
    {
      "type": "mixed_currency_comparison",
      "severity": "high",
      "currencies": ["EUR", "USD"],
      "by_company": {"Neste Oyj": "EUR", "Exxon Mobil Corp": "USD"},
      "message": "Companies in this comparison report in different currencies (EUR, USD). …"
    }
  ]
}

Margins and return ratios are percentages (8.4 = 8.4 %), computed from the reported figures with the formulas listed in computations. Absolute figures are in each company's own reporting currency and are never FX-converted; compare across currencies on the margins and ratios instead. Empty fields are omitted rather than sent as null.

Output shape

companies -- one entry per resolved issuer with currency, latest_year (a flat dict of the kpis for the newest year with data, plus year), and by_year (the same KPI keys per year, newest first). Keys are the lowercase KPI names in both (ebitda, ebit). Both carry _provenance per year, as on the financials endpoint. US entries add ticker and exchange. An entry may also carry latest_quarter (newest quarter's figures), latest_price (most recent stored close, typically one trading day old) and data_quality_warnings (Nordic source conflicts, at most three).
kpis -- the metric keys used for latest_year and by_year. The set depends on the companies' sector (banks, for example, get no gross profit or EBITDA). Use it to drive table rows or column headers.
not_found -- input strings the resolver could not map. Surface these to the user instead of silently dropping them.
computations -- the formula behind each derived margin and ratio.
data_quality_warnings (top level) -- a mixed_currency_comparison entry when the companies report in different currencies.
fiscal_calendar_warning -- present when the companies' fiscal years end months apart (e.g. August vs. January), listing each company's period_end.
coverage_gaps -- companies that resolved but have no detailed financial data, with reason and explanation.

Limits

2 to 5 companies per call.
1 to 10 historical years per company.