edgar-geo-revenue

Extract geographic revenue breakdowns from SEC EDGAR 10-K filings — the revenue-by-country split a company actually disclosed, resolved to ISO country codes.

import edgar_geo_revenue as egr
egr.set_user_agent("Your Name your@email.com")
egr.fetch_geo_revenue("AAPL")
# {'fiscal_year': 2025, 'total_revenue_usd': 416161000000,
#  'segments': [['US', 36.47], ['CN', 15.47]],
#  'region_segments': [['INTL', 48.06]], 'pct_coverage': 100.0}

Source on GitHub · MIT licensed

Why geographic revenue is hard to extract

The filing is easy to fetch. The difficulty is that revenue-by-geography has no standard location, table shape, or label vocabulary in EDGAR:

• XBRL geographic tags are incomplete. Many filers disclose a geographic split in the rendered statements while tagging little or nothing usable, so an XBRL-only approach reports “no data” for companies that plainly disclosed one.
• The note lives in an unpredictable R-file, anywhere from R1.htm to R200.htm.
• Label vocabulary is unbounded — “U.S.”, “US and Canada”, “Europe, the Middle East and Africa (EMEA)”, “Non-US”, “Greater China”, “Rest of world”, with arbitrary footnote markers and punctuation.
• Adjacent tables are near-identical — long-lived assets, deposits and pension assets by geography sit beside the revenue note and share its row labels.

Rules here survived a production audit of 463 SEC filers, of which 262 had a usable geographic disclosure. Much of the remainder genuinely do not disclose one.

What it deliberately refuses to do

Each of these is a plausible heuristic that was tried in production, produced wrong numbers, and was removed:

• Never splits a region-level disclosure into per-country estimates. “Europe: 30%” stays a region row. Apportioning it by GDP or fixed weights fabricates figures the filer never reported.
• Never guesses the “Total” row. No positional or label-based heuristic proved safe; the denominator comes from the filing’s own revenue figure.
• Never rescales a partition that does not add up. Country percentages summing to 109% are overlapping subtotals, not a partition — the result is rejected with a logged reason rather than normalised to 100%.
• Never stops the R-file scan at the first failed fetch, which truncates the search before reaching the note in longer filings.

Combined place labels are resolved on the set of places, not the label text, so {EUROPE, MEA} is recognised as EMEA and {US, CA} as North America across every punctuation variant.

Returned fields

Field	Meaning
fiscal_year	Fiscal year from the filing’s own period metadata
total_revenue_usd	Total revenue for that year, USD
segments	[[ISO2, percent], …] country-level rows
region_segments	[[REGION, percent], …] genuinely region-level rows
pct_coverage	Share of total revenue the rows account for

None means no geographic disclosure was found — a normal result, not an error.

SEC EDGAR fair-access compliance

This library fetches only public filings from SEC EDGAR, and it is built to stay inside the SEC’s fair-access policy for automated tools:

• A real contact address is required, with no default. SEC asks that automated requests identify the requester. There is no fallback User-Agent, and calling without one raises UserAgentNotSet rather than issuing an anonymous request:

  egr.set_user_agent("Your Name your@email.com")
  # or: export EDGAR_GEO_USER_AGENT="Your Name your@email.com"
  

• Requests are throttled below SEC’s limit. SEC permits about 10 requests per second. Pacing is enforced centrally in the HTTP layer at ~9 req/s, so every request the library makes is covered rather than only the ones inside the filing scan.
• Only public endpoints are used — company_tickers.json, the submissions API, and filing archive R-files. No authenticated, bulk, or paywalled endpoint is touched.
• Nothing is redistributed. The library returns what the filer disclosed; it ships no cached copy of EDGAR content.
• A 403 is reported, never swallowed. If SEC rejects or throttles a request it is logged at warning level, so a blocked request is never mistaken for a company that discloses no geographic breakdown.

Filing content is public domain as a US government work. This library is MIT licensed and is not affiliated with or endorsed by the SEC.

---

Built from the extraction layer behind MetricsHour, which publishes geographic revenue exposure for listed companies alongside macro and trade data. For the parsed dataset with country pages and screening, see metricshour.com/screener.

This site is open source. Improve this page.