API · Companies

Get revenue by country and region

Where the company's revenue comes from — ISO alpha-2 country codes + region rollups.

GET/api/v1/data/companies/{company}/revenue-geography

Returns the company's revenue split by country and region for one reporting period. Mappable country rows come back with ISO alpha-2 codes so you can colour a world map directly.

When to use this

"Where does Apple sell?"
Building a revenue heatmap on a company page.
Quantifying geographic exposure ahead of a market-shift event.

Path

Field	Type	Description
companyrequired	string	Nordic: company name as it appears in Clarifo, case-insensitive, no fuzzy matching (e.g. "Neste"). US: name, ticker or CIK (e.g. "Apple", "AAPL", "0000320193"). Nordic tickers are not resolved here.

Query

Field	Type	Description
year	integer	Fiscal year to query; the full-year disclosure is preferred, else that year's latest interim one. Default: the most recent disclosure of any kind, which can be a quarterly one.

Example

bash

curl "https://api.clarifo.com/api/v1/data/companies/Apple/revenue-geography?year=2025" \
  -H "Authorization: Bearer $CLARIFO_API_KEY"

Response

json

{
  "company_name": "Apple Inc.",
  "company_id": "aapl",
  "market": "us",
  "year": 2025,
  "period_type": "annual",
  "currency": "USD",
  "unit": "milj_usd",
  "total_revenue": 416161.0,
  "total_revenue_mappable": 216167.0,
  "additive_layer": "country+other",
  "overlap_warning": "Regions and countries overlap; total_revenue uses the country+other rows only. Do not sum all rows across categories.",
  "total_revenue_reconciliation": {
    "group_revenue": 416161.0,
    "group_revenue_source": "us_snapshot",
    "coverage_of_group_revenue": 1.0,
    "explanation": "group_revenue is the consolidated figure for the same period, in the same unit as the rows here. …"
  },
  "countries": [
    {"name": "United States", "iso_alpha2": "US",
     "revenue": 151790.0, "page_id": "0000320193-25-000079"}
  ],
  "regions": [
    {"name": "Asia Pacific", "entity_type": "multi_region",
     "revenue": 67680.0, "page_id": "0000320193-25-000079"}
  ],
  "other": [
    {"name": "Other countries (US filing)",
     "entity_type": "other", "revenue": 199994.0,
     "page_id": "0000320193-25-000079"}
  ]
}

Revenue figures are in millions of currency; unit names the scale (e.g. "milj_usd", "milj_euro"). Empty fields, including a null name_native or quarter, are omitted rather than sent as null.

Top-level fields

Field	Description
`quarter`	Quarter number (1--4) for quarterly data; absent for annual data.
`period_type`	`"annual"` or `"quarterly"`.
`additive_layer`	Which layer `total_revenue` sums: `"country"`, `"country+other"`, `"region"`, `"region+other"`, or `"other"`.
`overlap_warning`	How the layers overlap, plus any rows excluded from the total (per-segment, parent-company, or duplicate extractions).
`total_revenue_reconciliation`	Cross-check against consolidated group revenue for the same period: `group_revenue` (same unit as the rows), `group_revenue_source` (where that figure came from, e.g. `"esef"` or `"avainluvut"` for Nordic filers, `"us_snapshot"` for US filers), `coverage_of_group_revenue` and an `explanation`. Omitted when no group revenue figure is available, or its currency differs from the rows.

Country, region, and other entries can include name_native (the name in the original filing language, e.g. "Yhdysvallat"). It is absent when the filing is in English.

Country vs. region vs. other

The response is split into three buckets -- and they are not strictly additive. The additive_layer field tells you which bucket can be safely summed to match total_revenue.

Bucket	Source	Notes
`countries`	Country-level disclosures with ISO codes	Safe to sum when `additive_layer` starts with `"country"`.
`regions`	Multi-country rollups ("EMEA", "Asia Pacific")	Do not sum with countries -- some filers report both.
`other`	"Other countries" catch-all	Can be large (40 %+) for filers that disclose only top markets.

total_revenue is always one layer, never the sum of all rows. Filers disclose geography at several granularities at once and those layers overlap by construction: a "Europe" row and a "Finland" row describe the same euros. The chosen layer is reconciled against consolidated group revenue for the same period -- a layer whose sum exceeds group revenue is provably overlapping and is rejected in favour of the largest layer that does not.

Use total_revenue_reconciliation.coverage_of_group_revenue to see how much of the company's revenue the breakdown actually accounts for. A value below 1.0 is normal and expected; most filers break out only their largest markets.

Coverage

Nordic: all filers tracked by Clarifo's PDF pipeline.
US: ~1,450 filers with country-level XBRL disclosures (2020–2026). Smaller and segment-only filers may be absent.

When the company cannot be resolved or has no geography data on file, the response is HTTP 200 with an error body:

json

{
  "error": "No revenue-by-geography data for this company",
  "failure_kind": "not_found",
  "company": "Acme Widgets",
  "hint": "Coverage is partial: Nordic filers tracked by Clarifo's PDF pipeline, plus ~1450 US filers …"
}