edgar.api — com.github.clojure-finance/edgarjure 0.5.0

Unified power-user entry point for edgarjure. Require as: (require '[edgar.api :as e])

Design principles:

• Every function accepts ticker or CIK interchangeably
• Keyword args throughout; no positional form/type args — a single options map also works everywhere: (e/income "AAPL" {:form "10-Q"})
• nth-style lookups (e/filing :n ...) return nil out of range, never throw
• Sensible defaults for taxonomy (us-gaap), unit (USD), form (10-K)
• :concept accepts a string or a collection of strings
• Functions that return datasets always return tech.ml.dataset, never seq-of-maps

balance clj

(balance ticker-or-cik
         &
         {:keys [form shape as-of view concepts] :or {form "10-K" shape :long}})

Return balance sheet as a long-format tech.ml.dataset. Options: :form - "10-K" (default) or "10-Q" :shape - :long (default) or :wide :view - :normalized (default) | :as-reported | :standardized | :compustat (:standardized imputes e.g. Total Liabilities, Total Equity = SE + NCI, and a derived-only "Working Capital" item; :compustat adds reclassified items approximating Compustat constructions: "RE (Compustat)" incl. AOCI, "DLC (Compustat)"/"DLTT (Compustat)" incl. lease obligations, "MIB (Compustat)"/"MIBN (Compustat)" /"MIBT (Compustat)", "PSTK (Compustat)", "SEQ (Compustat)"/"CEQ (Compustat)" /"TEQ (Compustat)", "RECT (Compustat)", "CHE (Compustat)") :concepts - override balance-sheet-concepts with your own [[label concept ...] ...] vectors :as-of - ISO date string "YYYY-MM-DD" (default nil). When set, only filings where :filed <= as-of-date are used (point-in-time / look-ahead-safe mode).

balance-sheet clj

(balance-sheet ticker-or-cik & {:keys [form shape as-of view concepts]})

Long-name alias of e/balance.

cash-flow clj

(cash-flow ticker-or-cik & {:keys [form shape as-of view concepts]})

Long-name alias of e/cashflow.

cashflow clj

(cashflow ticker-or-cik
          &
          {:keys [form shape as-of view concepts]
           :or {form "10-K" shape :long}})

Return cash flow statement as a long-format tech.ml.dataset. Options: :form - "10-K" (default) or "10-Q" :shape - :long (default) or :wide :view - :normalized (default) | :as-reported | :standardized | :compustat (:standardized adds a derived "Free Cash Flow" line item and imputes "D&A" from separately tagged components; :compustat currently equals :standardized for the cash flow statement) :concepts - override cash-flow-concepts with your own [[label concept ...] ...] vectors :as-of - ISO date string "YYYY-MM-DD" (default nil). When set, only filings where :filed <= as-of-date are used (point-in-time / look-ahead-safe mode; also for :as-reported). Long format carries :duration-months; 10-K :shape :wide keeps only the annual windows. 10-Q queries add :val-q and :val-ltm (share counts and per-share amounts are never differenced or summed).

cik clj

(cik ticker-or-cik)

Resolve a ticker to a zero-padded 10-digit CIK string, or normalise a CIK. Accepts integer CIKs (320193) and share-class dots ("BRK.B"). (e/cik "AAPL") => "0000320193"

clear-disk-cache! clj

(clear-disk-cache! & {:as opts})

Delete all entries from the on-disk HTTP cache. Returns the number of entries removed. Options: :dir (defaults to the enabled/default dir).

clear-unmapped-concepts! clj

(clear-unmapped-concepts!)

Reset the unmapped-concept registry.

company clj

(company ticker-or-cik)

Return full SEC submissions metadata map for a company. Accepts ticker or CIK.

company-metadata clj

(company-metadata ticker-or-cik)

Return a shaped metadata map for a company. Richer than (e/company ...). Extracts SIC, exchanges, addresses, fiscal year end, EIN, phone, website, former names, and more from the SEC submissions endpoint. Accepts ticker or CIK.

Example: (e/company-metadata "AAPL") ;=> {:cik "0000320193" :name "Apple Inc." :tickers ["AAPL"] ; :exchanges ["Nasdaq"] :sic "3571" ; :sic-description "Electronic Computers" ; :entity-type "operating" :category "Large accelerated filer" ; :state-of-inc "CA" :fiscal-year-end "0926" ; :ein "942404110" :phone "[phone]" ; :addresses {:business {:street1 ... :city ... :state ... :zip ...} ; :mailing {:street1 ... :city ... :state ... :zip ...}} ; :former-names []}

company-name clj

(company-name ticker-or-cik)

Return the company name string for a ticker or CIK.

concepts clj

(concepts ticker-or-cik)

Return a dataset of all XBRL concepts available for a company. Columns: :taxonomy :concept :label :description Each row is one distinct concept — use this to discover what data is available. Example: (e/concepts "AAPL")

concepts-for clj

(concepts-for statement & {:keys [industry] :or {industry :standard}})

Return the active concept chains (and their EDN metadata) for a statement. statement: :income | :balance | :cash-flow Options: :industry - :standard (default) | :bank | :insurance | :reit (income only) Example: (e/concepts-for :income :industry :bank)

daily-filings clj

(daily-filings date & {:keys [form filter-fn]})

Return a lazy seq of all filings submitted on a given date.

date — a java.time.LocalDate or a "YYYY-MM-DD" string. Options: :form — filter by form type e.g. "10-K" "8-K" "4" :filter-fn — arbitrary predicate applied to each result map

Built from the EDGAR daily master index — complete, one map per filing. :form is an exact match ("8-K" excludes "8-K/A"). Returns an empty seq for weekends, holidays, future dates, and the current day until the SEC publishes its index (around 10 pm ET).

Each result map has: :accessionNumber — dashed accession number :form — form type string :filingDate — "YYYY-MM-DD" :cik — zero-padded 10-digit CIK of the first listed filer :companyName — that filer's name :filers — every filer as {:cik :name} (e.g. Form 4 issuer and owner) The maps work directly with e/html, e/text, e/items, e/obj; call e/filing-by-accession for :primaryDocument, :url and filer roles. For 8-K item filters use e/search-filings (its hits carry :items).

Examples: ;; All filings on a date (e/daily-filings "2026-03-10")

;; Only 8-Ks (e/daily-filings "2026-03-10" :form "8-K")

;; 10-Ks filed by large-cap tech (filter by known CIKs) (e/daily-filings "2026-03-10" :form "10-K" :filter-fn #(= (:cik %) "0000320193"))

;; Works with java.time.LocalDate too (e/daily-filings (java.time.LocalDate/of 2026 3 10))

disable-disk-cache! clj

(disable-disk-cache!)

Disable the on-disk HTTP cache (cached files are kept on disk).

disable-fsds! clj

(disable-fsds!)

Disable the FSDS quarter cache (cached files are kept on disk).

disk-cache-stats clj

(disk-cache-stats)

Return {:dir :entries :bytes} for the on-disk cache, or nil when disabled.

doc-url clj

(doc-url filing-map doc-name)

Build the SEC archives URL for a specific document within a filing. doc-name is the filename as it appears in the filing index.

Use (e/filing-index f) to see all available document names and types.

Examples: ;; URL for a named exhibit (let [ex (e/exhibit f "EX-21")] (e/doc-url f (:name ex)))

;; URL for a known attachment (e/doc-url f "R2.htm")

enable-disk-cache! clj

(enable-disk-cache! & {:as opts})

Enable the persistent on-disk HTTP cache (off by default). Responses are stored under :dir (default ~/.edgarjure/http-cache) and reused across sessions: JSON endpoints and the daily-changing full-index/daily-index files for 24 h, raw filing documents for 30 days (published filings are immutable). Options: :dir, :ttl-json-ms, :ttl-raw-ms. Example: (e/enable-disk-cache!)

enable-fsds! clj

(enable-fsds! & {:as opts})

Enable the local SEC Financial Statement Data Sets quarter cache (off by default). When enabled, the income statement's :view :compustat augments its reclassification with two things the companyfacts API cannot provide, per 10-K period: statement placement (does this filer present D&A as its own income statement line? then COGS is not stripped) and extension-tag operands (e.g. AMZN's Fulfillment / Technology & content lines, folded into XSGA/XRD). Quarter zips (50-130 MB each) download on first use into :dir (default ~/.edgarjure/fsds) and are shared across all companies. FSDS operands apply to 10-K periods only: 10-Q queries never trigger quarter downloads (the annual rows they build for Q4/LTM derivation are reclassified without FSDS, so a derived Q4 never mixes the two rule regimes). Options: :dir. Example: (e/enable-fsds!)

exhibit clj

(exhibit filing-map exhibit-type)

Return the first exhibit matching exhibit-type (e.g. "EX-21"). Returns nil if no matching exhibit is found.

Common exhibit types: "EX-21" — subsidiaries list "EX-23" — auditor consent "EX-31.1" — CEO Sarbanes-Oxley certification "EX-31.2" — CFO Sarbanes-Oxley certification "EX-32" — Section 906 certifications

To fetch the exhibit content, use (e/doc-url ...) to get the URL, or (e/filing-document ...) to fetch the raw content string directly:

(def f (e/filing "AAPL" :form "10-K")) (def ex (e/exhibit f "EX-21")) ;; Get the SEC URL: (e/doc-url f (:name ex)) ;; Or fetch the content directly: (e/filing-document f (:name ex))

exhibits clj

(exhibits filing-map)

Return all exhibit entries from a filing's index as a seq of maps. Each map has :name :type :description :sequence. Exhibits have :type values beginning with "EX-" (e.g. "EX-21", "EX-31.1").

Example: (def f (e/filing "AAPL" :form "10-K")) (e/exhibits f) ;=> ({:type "EX-21" :name "aapl-20230930_g2.htm" :description "Subsidiaries" ...} ...)

Fetch an exhibit's content: (let [ex (e/exhibit f "EX-21")] (e/doc-url f (:name ex)))

facts clj

(facts ticker-or-cik & {:keys [concept form]})

Fetch XBRL company facts as a tech.ml.dataset. Options: :concept - string or collection of strings to filter concepts :form - "10-K" | "10-Q" (default: no filter) Example: (e/facts "AAPL") (e/facts "AAPL" :concept "Assets") (e/facts "AAPL" :concept ["Assets" "NetIncomeLoss"] :form "10-K")

filing clj

(filing ticker-or-cik
        &
        {:keys [form n include-amends?]
         :or {form "10-K" n 0 include-amends? false}})

Return the latest filing of a given form type for a company. Options: :form - form type string (default "10-K") :n - return the nth latest (0-indexed, default 0) :include-amends? - include amended filings (default false); an amendment :form ("10-K/A") returns the amendments themselves regardless

filing-by-accession clj

(filing-by-accession accession-number)

Hydrate a filing map from an accession number string. Accepts dashed ("XXXXXXXXXX-YY-ZZZZZZ") or undashed format. Returns {:cik :accessionNumber :form :primaryDocument :filingDate :url :filers}, ready for e/html, e/text, e/items, e/obj, etc. :cik is the company the filing is about (Filer, else Subject, Issuer, Reporting, Filed by) — not the filing agent that submitted it; :filers lists every entity on the filing index as {:name :role :cik}. CIKs are zero-padded 10-digit strings. Example: (e/filing-by-accession "0000320193-23-000106")

filing-document clj

(filing-document filing-map doc-name)

Fetch a specific named document from a filing as a raw string. doc-name is the filename as it appears in the filing index.

Use (e/exhibits f) or (e/filing-index f) to discover available document names. Use (e/doc-url f doc-name) if you only need the URL.

Examples: ;; Fetch the subsidiaries exhibit content (def f (e/filing "AAPL" :form "10-K")) (def ex (e/exhibit f "EX-21")) (e/filing-document f (:name ex))

;; Fetch a known attachment by name (e/filing-document f "R2.htm")

filing-index clj

(filing-index filing-map)

Return a filing's index: {:files [{:sequence :name :type :description :size} ...] :formType :filingDate :filers [{:name :role :cik} ...]}. :files lists every document in the filing (primary document, exhibits, XBRL, graphics).

filings clj

(filings ticker-or-cik
         &
         {:keys [form start-date end-date limit include-amends?]
          :or {include-amends? false}})

Return a lazy seq of filing metadata maps for a company. Options: :form - form type string e.g. "10-K" "10-Q" "8-K" "4" :start-date - "YYYY-MM-DD" :end-date - "YYYY-MM-DD" :limit - max results :include-amends? - include amended filings e.g. 10-K/A (default false); an amendment :form ("10-K/A") returns the amendments themselves regardless

filings-dataset clj

(filings-dataset ticker-or-cik & opts)

Return a filing index for a company as a tech.ml.dataset. Same options as e/filings.

financials clj

(financials ticker-or-cik
            &
            {:keys [form shape as-of view industry]
             :or {form "10-K" shape :long}})

Return all three financial statements for a company. Returns {:income ds :balance ds :cashflow ds} Options: :form - "10-K" (default) or "10-Q" :shape - :long (default) or :wide :view - :normalized (default) | :as-reported | :standardized | :compustat (income + balance sheet reclassification) :industry - :standard | :bank | :insurance | :reit (income statement only) :as-of - ISO date string "YYYY-MM-DD" (default nil). All three statements use point-in-time deduplication (every :view, including :as-reported).

frame clj

(frame concept
       period
       &
       {:keys [taxonomy unit] :or {taxonomy "us-gaap" unit "USD"}})

Fetch cross-sectional data for a concept across all companies for a period. Returns a tech.ml.dataset sorted by :val descending, with columns :accn :cik :entityName :loc :end :val. :cik is a zero-padded 10-digit string (matching e/cik), so results join directly against other edgarjure output. Required: concept - GAAP concept string e.g. "Assets" "NetIncomeLoss" period - frame string e.g. "CY2023Q4I" "CY2023" Options: :taxonomy - default "us-gaap" :unit - default "USD" Example: (e/frame "Assets" "CY2023Q4I") (e/frame "SharesOutstanding" "CY2023Q4I" :unit "shares")

html clj

(html filing-map)

Fetch the primary HTML document of a filing as a string.

income clj

(income ticker-or-cik
        &
        {:keys [form shape as-of view industry concepts]
         :or {form "10-K" shape :long}})

Return income statement as a long-format tech.ml.dataset. Options: :form - "10-K" (default) or "10-Q" :shape - :long (default) or :wide :view - :normalized (default) | :as-reported | :standardized | :compustat :as-reported = raw rows, no dedup or label mapping (:as-of still applies); :standardized = normalized plus line items imputed from arithmetic identities (rows carry :method :derived); :compustat = standardized plus line items reclassified to approximate Compustat definitions ("COGS (Compustat)", "XSGA (Compustat)", "OIADP (Compustat)", ...; rows carry :method :reclassified) - see (e/reclass-rules :income) :industry - :standard | :bank | :insurance | :reit. Auto-detected from the company's SIC code when omitted (banks/insurers/REITs get industry-specific concept chains). The :compustat rules only apply on :standard chains; for other industries :view :compustat equals :standardized :concepts - override the fallback chains with your own [[label concept ...] ...] vectors (disables industry routing) :as-of - ISO date string "YYYY-MM-DD" (default nil). When set, only filings where :filed <= as-of-date are used (point-in-time / look-ahead-safe mode). Long format carries :duration-months. 10-K queries keep the quarterly-footnote windows filed with the 10-K (3/6/9 months); :shape :wide keeps only the annual windows. 10-Q queries add :val-q (single quarter) and :val-ltm (trailing twelve months); share counts and per-share amounts are never differenced or summed (:val-q is the reported 3-month value or nil, :val-ltm is nil).

income-statement clj

(income-statement ticker-or-cik
                  &
                  {:keys [form shape as-of view industry concepts]})

Long-name alias of e/income.

init! clj

(init! name-and-email)

Set the SEC User-Agent identity required for all HTTP requests. Must be called once before any other function. Example: (e/init! "Your Name [e-mail]")

item clj

(item filing-map item-id)

Extract a single item section from a filing. Returns {:title "..." :text "..." :method ...} or nil. (e/item f "7") => {:title "Management's Discussion..." :text "..." :method :html-heading-boundaries}

items clj

(items filing-map & {:keys [only remove-tables?] :or {remove-tables? false}})

Extract item sections from a filing. Returns a map of item-id → {:title "..." :text "..." :method ...}. Options: :only - set of item ids to extract e.g. #{"7" "1A"} (default all) :remove-tables? - strip numeric tables before extraction (default false) 10-Q ids carry their part: "I-1".."I-4", "II-1".."II-6" ("I-2" is MD&A); ids are normalized, so "i 2" also works.

latest-effective-filing clj

(latest-effective-filing ticker-or-cik & {:keys [form] :or {form "10-K"}})

Return the most recent effective filing for a company and form type. If an amendment (e.g. 10-K/A) is newer than the original, it is returned instead. Options: :form - form type string (default "10-K")

obj clj

(obj filing-map)

Parse a filing into a structured form-specific map via filing-obj multimethod. Dispatches on :form. Requires the form parsers to be loaded: (require '[edgar.forms]) ; Forms 3/4/5, 13F-HR, Schedule 13D/G

panel clj

(panel tickers & {:keys [concept form as-of] :or {form "10-K"}})

Fetch XBRL facts for multiple companies and combine into a long-format dataset. Adds a :ticker column. Options: :concept - string or collection of strings (default all concepts) :form - "10-K" (default) or "10-Q" :as-of - "YYYY-MM-DD" string; point-in-time filter — excludes filings submitted after this date and deduplicates per [ticker concept unit start end] keeping the most recently filed observation available at that date Example: (e/panel ["AAPL" "MSFT" "GOOG"] :concept ["Assets" "NetIncomeLoss"]) (e/panel ["AAPL" "MSFT"] :concept "Assets" :as-of "2022-01-01")

pivot clj

(pivot ds)

Pivot a long-format facts dataset to wide format. Rows = :end (per [:ticker :end] when the dataset has a :ticker column, e.g. e/panel output); columns = :concept; values = :val. One observation per [ticker end concept unit]: the longest duration window wins (fiscal year over quarterly-footnote rows), latest :filed among equal windows. Concepts reported in several units get one column per unit, "<concept> (<unit>)". Returns a tech.ml.dataset.

reclass-rules clj

(reclass-rules statement)

Return the reclassification ruleset used by :view :compustat for a statement, as its full EDN map ({:ruleset :compustat :rules [...] ...}), or nil when the statement has no rules (:income and :balance have rules; :cash-flow has none). Example: (e/reclass-rules :balance)

save! clj

(save! filing-map dir)

Download a filing's primary document to dir/<form>/<cik>/<accession>/ ("/" in the form becomes "_", e.g. 10-K_A). Returns the saved file path.

save-all! clj

(save-all! filing-map dir)

Download all documents in a filing to a directory. Returns a seq of saved file paths.

save-unmapped-concepts! clj

(save-unmapped-concepts! & {:keys [path]})

Write the unmapped-concept registry as EDN. Options: :path - output file (default ~/.edgarjure/unmapped-concepts.edn) Returns the path written.

search clj

(search query & {:keys [limit] :or {limit 10}})

Search EDGAR entities (companies, funds, individual filers) by current name, best match first; ticker and CIK queries match too. Returns a vector of {:cik "0000320193" :name "Apple Inc." :tickers ["AAPL"]}. Options: :limit - max results (default 10; the SEC endpoint returns at most 10)

search-companies clj

(search-companies query & {:keys [limit]})

Alias of e/search — searches companies by name, symmetric with e/search-filings for full-text filing search.

search-filings clj

(search-filings query
                &
                {:keys [forms start-date end-date limit] :or {limit 10}})

Full-text search across EDGAR filings. Options: :forms - vector of form types e.g. ["10-K" "10-Q"] :start-date - "YYYY-MM-DD" :end-date - "YYYY-MM-DD" :limit - max results (default 10) Returns a lazy seq of one map per FILING (EFTS indexes documents; a filing whose exhibits also match appears once, best-scoring document first). Each map is the raw EFTS source map (:adsh :ciks :display_names :root_forms :file_date :period_ending :items :sics ...) plus :accessionNumber - dashed accession number :cik - zero-padded 10-digit CIK of the first filer :form - form type :filingDate - "YYYY-MM-DD" :companyName - first display name :document - file name of the matching document :url - archive URL of the matching document so results work with e/html, e/text, e/filing-by-accession. EFTS caps result offsets at 10,000.

tables clj

(tables filing-map
        &
        {:keys [nth min-rows min-cols] :or {min-rows 2 min-cols 2}})

Extract HTML tables from a filing as a seq of tech.ml.dataset objects.

Options: :nth — return only the nth table (0-indexed); returns a single dataset or nil :min-rows — only include tables with at least this many data rows (default 2; :min-rows 1 also keeps single-row tables) :min-cols — only include tables with at least this many columns (default 2)

Layout and navigation tables (no data row with at least two non-blank cells) are filtered out. Column names come from the first substantive row; duplicates are suffixed _1, _2, etc. Numeric columns are auto-detected: commas stripped, parentheses → negative.

Examples: (def f (e/filing "AAPL" :form "10-K"))

;; All data tables (e/tables f)

;; Only substantial tables (e/tables f :min-rows 5)

;; Specific table by index (e/tables f :nth 0) (e/tables f :nth 2)

text clj

(text filing-map)

Fetch the primary document of a filing as plain text (HTML stripped).

unmapped-concepts clj

(unmapped-concepts & {:keys [top]})

Return the registry of us-gaap concepts seen in company facts that no active concept chain matched, accumulated across statement calls this session: {concept {:count n :first-seen date :example-ciks #{...}}} Options: :top - only the n most frequent, as [concept info] pairs Grow chain coverage by reviewing this and extending the EDN concept files.

xbrl-docs clj

(xbrl-docs filing-map)

Return all XBRL-related document entries from a filing's index as a seq of maps. Covers EX-101.* linkbases: instance (.xml), schema (.xsd), calculation, label, presentation, and definition linkbases.

Example: (def f (e/filing "AAPL" :form "10-K")) (e/xbrl-docs f) ;=> ({:type "EX-101.SCH" :name "aapl-20230930.xsd" ...} ; {:type "EX-101.CAL" :name "aapl-20230930_cal.xml" ...} ...)