API · Companies

Screen the company universe

Rank companies by growth or absolute value of a metric, with filters.

POST/api/v1/data/companies/screen

Ranks the entire Clarifo universe by a financial metric, optionally filtered by country, industry, or tag taxonomy. Designed for cross-company questions:

"Which Finnish companies grew revenue most in 2024?"
"Top 20 Swedish companies by EBITDA."
"Which construction-sector companies had the largest order book?"

Body

Field	Type	Description
metric	string default: revenue	Metric key — see coverage below.
mode	string default: growth	growth \| value.
year	integer	Anchor year. Default: latest available.
compare_years	integer default: 1	Growth mode only: how many years back (1 = YoY, 4 = 4-year CAGR).
country	string	FI \| SE \| US. Omit to scan both markets.
industry	string	Free-text substring on companies.industry.
tag_slugs	string[]	Precise sector / theme filter via the company_tags taxonomy.
top_n	integer default: 20	1–100.
direction	string default: desc	desc \| asc.
min_value	number	Drop micro-caps from a value ranking.

Example

bash

curl https://api.clarifo.com/api/v1/data/companies/screen \
  -H "Authorization: Bearer $CLARIFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "revenue",
    "mode": "growth",
    "year": 2024,
    "country": "FI",
    "top_n": 20
  }'

Response

json

{
  "metric": "revenue",
  "mode": "growth",
  "year": 2024,
  "compare_year": 2023,
  "filters": {"country": "FI", "industry": null, "tag_slugs": null},
  "companies": [
    {
      "company_name": "fiskars",
      "display_name": "Fiskars Oyj Abp",
      "ticker": "FSKRS.HE",
      "country": "FI",
      "industry": "Consumer Goods",
      "entity_type": "operating",
      "market": "nordic",
      "currency": "EUR",
      "value_anchor": 1320.0,
      "value_compare": 1250.0,
      "growth_pct": 5.6,
      "delta_absolute": 70.0,
      "trend": "growing",
      "signs_consistent": true,
      "value_anchor_eur": 1320.0,
      "value_compare_eur": 1250.0
    }
  ],
  "coverage": {
    "total_in_scope": 120,
    "with_data": 47,
    "returned": 20
  },
  "coverage_warning": null
}

Company fields

Field	Description
`entity_type`	`"operating"`, `"holding"`, `"reit"`, `"bank"`, etc.
`value_anchor` / `value_compare`	Metric value at the anchor year and the comparison year.
`growth_pct`	Year-over-year growth percentage. `null` when anchor and compare have different signs.
`delta_absolute`	Absolute change (`value_anchor - value_compare`).
`trend`	`"growing"`, `"shrinking"`, `"turned_positive"`, `"turned_negative"`, etc.
`signs_consistent`	Whether anchor and compare values have the same sign.
`value_anchor_eur` / `value_compare_eur`	EUR-converted values (for cross-currency comparisons).

Coverage

The coverage object reports how broadly the screen matched:

Field	Description
`total_in_scope`	Companies matching the filters (before checking metric data).
`with_data`	Companies with data for the requested metric and year.
`returned`	Companies returned (capped by `top_n`).

coverage_warning is a string when data coverage is below 20%, null otherwise.

Metric coverage

The screener picks the right backend automatically based on the metric key.

Pre-aggregated Nordic metrics (fastest): revenue, gross_profit, ebit, ebitda, net_income, operating_cash_flow, free_cash_flow, marketcap, personnel, eps_diluted, shares_outstanding.
Granular IFRS line items (Nordic ESEF facts): cost_of_sales, operating_profit, profit_before_tax, income_tax_expense, research_and_development_expense, selling_and_marketing_expense, administrative_expense, finance_costs, finance_income, total_assets, current_assets, non_current_assets, total_equity, equity_attributable_to_owners, total_liabilities, current_liabilities, non_current_liabilities, cash_and_equivalents, investing_cash_flow, financing_cash_flow.
Filing-extracted KPIs (Nordic): order_book, order_intake, equity_ratio, …
US (US-GAAP tags): every metric above except a few Nordic-only items (ebit, ebitda, free_cash_flow, marketcap, personnel, eps_diluted, shares_outstanding, order_book, order_intake, equity_ratio).

The same metric key always means the same concept across markets.