Extracting Fundamental Stock Data from EDGAR using our favorite language: Common Lisp (Part 2)

In Part 1, we went on a bit of a quest and successfully obtained those CIK numbers using ticker symbols. You can catch up on that journey right here: Part 1 adventure.

Before we dive deeper, let’s take a moment to get familiar with XBRL (Extensible Business Reporting Language) and how it is used in the EDGAR API.

XBRL is a standard based on XML that’s all about exchanging business information in a clear, universal format. Since 2009, the SEC has integrated XBRL directly into financial reports, simplifying the process of extracting financial information.

To witness XBRL’s integration in action, let’s dive into Apple’s 2023 Annual Report, also known as the 10-K report.

Inline XBRL Viewer

Here’s Apple’s 10-K form from the SEC’s EDGAR service. The sections marked in red are formatted in XBRL, making them programmatically accessible.

Let’s explore a bit on the financial statements, we’ll scroll down a few pages until we stumble upon the Consolidated Statements of Operations, this table details revenues, expenses, and net income or loss, giving us a snapshot of the company’s operational efficiency.

We’re aiming to extract the Earnings Per Share (EPS) from this report programmatically. To identify the specific variable we need to query in the EDGAR API, simply click on the Earnings Per Share box highlighted in red. A popup will appear — make sure to note the Tag value, as that’s our key to retrieving the information.

The Tag, labeled as “uss-gaap:EarningsPerShareBasic” in this case, holds two crucial bits of information needed to pull our data. The first part, “uss-gaap,” tells us the taxonomy schema being used, and the second part, “EarningsPerShareBasic,” specifies the variable name we’re interested in.

It’s important to note that XBRL utilizes various taxonomies, such as us-gaap, ifrs-full, dei, and others. The most effective way to identify the correct taxonomy for your needs is to follow the process we’ve outlined above.

With this insight, we can consult the EDGAR API documentation. There, we discover that extracting this data requires us to make a GET request to a specific URL, in this case:

https://data.sec.gov/api/xbrl/companyconcept/CIK##########/us-gaap/EarningsPerShareBasic.json

So let’s write a function to query this data:

(defun get-company-concept (ticker taxonomy concept)
  "Get company concept using a taxonomy and a concept"
  (cl-json:decode-json-from-string (dex:get (format nil "https://data.sec.gov/api/xbrl/companyconcept/CIK~a/~a/~a.json"
          (get-stock-cik ticker)
          taxonomy
          concept)
         :headers *sec-headers*)))

Now, let’s test our function:

(get-company-concept "AAPL" "us-gaap" "EarningsPerShareBasic")

Voila, it works! Stay tuned for our next posts, where we’ll dive into processing this data and creating some insightful plots.

Hasta la vista!

Extracting Fundamental Stock Data from EDGAR using our favorite language: Common Lisp (Part 3)