Introducing

New Stock Financials API

Aug 3, 2021

We’ve just dropped our new Financials API featuring company financials sourced directly from SEC filings. We’ve standardized annual and quarterly company filings into fundamental accounting concepts that are easy to use and compare across companies and industries. We’ve normalized data across filings to be able to provide common concepts like revenues and operating expenses, and we’ve designed our new API to provide full traceability so that each reported number can be followed back to the field or formula that it originated from. And, we’ve made it all point-in-time, so you can view a company’s financials exactly as they were on a given date.

We’ve spent this past year overhauling our reference data with the fundamental idea that, just like all of our price data, our reference data should come directly from the source. For company financials, that means obtaining the data from the 10-K and 10-Q forms that each company files with the SEC. Those financials are reported in a language called XBRL, and inconsistencies between how different companies use XBRL to report their financials has always made standardization difficult. To solve this challenge, we took the idea of going directly to the source to a whole new level, and sought out one of the founders of XBRL, Charles Hoffman, who graciously assisted us in our efforts to build on top of his foundational methodology for mapping SEC reported financials to fundamental accounting principles. Building off of Mr. Hoffman’s work, we’ve created a standardized company financials API unlike any other available.

With our new Financials API, we’re providing 10+ years of financial history for listed companies. Like all of our new reference data APIs, financials are available as point-in-time data. By providing a date, you can query the financials API to see the financials for a company as they were known on that date. Responses include core financial data grouped into balance sheet, cash flow statement, income statement, and comprehensive income. By using the include_sources parameter, you can see the field or formula that each value came from, and, in combination with the returned information on the source filing, you can trace each value back to its origin in the SEC filing.

To see this in action, let’s make a call to get the most recent financials for Las Vegas Sands Corp. using the include_sources parameter.

https://api.polygon.io/vX/reference/financials?ticker=LVS&include_sources=true&apiKey=<your_api_key>

returns the result:

{
  "results":[{
    "financials":{
      "cash_flow_statement": {...},
      "comprehensive_income": {...},
      "income_statement":{
        "operating_expenses":{
          "label":"Operating Expenses",
          "value":96000000,
          "unit":"USD",
          "order":1000,
          "formula":"IS-Impute-22"
        },
        "net_income_loss":{
          "label":"Net Income/Loss",
          "value":-342000000,
          "unit":"USD",
          "order":3200,
          "xpath":"//*[local-name()='ProfitLoss' and @id='id3VybDovL2RvY3MudjEvZG9jOmNkZWYxMGE0NGJhOTRjNTM4MjNlMGU2YWM1NWQ4NWUzL3NlYzpjZGVmMTBhNDRiYTk0YzUzODIzZTBlNmFjNTVkODVlM18xOS9mcmFnOmJhNDQ1YmVlODE4MDQzOGZiOWEzZDVhYTliNzZjYzUwL3RhYmxlOmI3MzMwZmQ5YTQwYjQwZGZiNjgxZGYyY2ZiMDU4YzEyL3RhYmxlcmFuZ2U6YjczMzBmZDlhNDBiNDBkZmI2ODFkZjJjZmIwNThjMTJfMzYtMS0xLTEtODk3MA_41d2a042-a777-4a7d-9919-d0a48f392a7f']"
        },
        ...
      },
      "balance_sheet":{...}
     },
     "start_date":"2021-01-01",
     "end_date":"2021-03-31",
     "cik":"0001300514",
     "company_name":"LAS VEGAS SANDS CORP.",
     "fiscal_period":"Q1",
     "fiscal_year":"2021",
     "source_filing_url":"https://api.polygon.io/v1/reference/sec/filings/0001300514-21-000058",
     "source_filing_file_url":"https://api.polygon.io/v1/reference/sec/filings/0001300514-21-000058/files/lvs-20210331_htm.xml"                 
   }]
}

Looking at the Income Statement, you can see that the operating_expenses field is computed, and uses the formula IS-Impute-22. We can reference the formulas to find the exact rules used to compute this field.

The net_income_loss value has an associated xpath value, which means it came directly from the filing that is referenced in source_filing_file_url. We can run a quick command to download the source file and search for the given xpath to find the exact XBRL field that this value came from.

curl "<source_filing_file_url>"?apiKey=<your_api_key>" | xmllint --xpath "<xpath of field>" -

for example:

curl "https://api.polygon.io/v1/reference/sec/filings/0001300514-21-000058/files/lvs-20210331_htm.xml?apiKey=<your_api_key>" | xmllint --xpath "//*[local-name()='ProfitLoss' and @id='id3VybDovL2RvY3MudjEvZG9jOmNkZWYxMGE0NGJhOTRjNTM4MjNlMGU2YWM1NWQ4NWUzL3NlYzpjZGVmMTBhNDRiYTk0YzUzODIzZTBlNmFjNTVkODVlM18xOS9mcmFnOmJhNDQ1YmVlODE4MDQzOGZiOWEzZDVhYTliNzZjYzUwL3RhYmxlOmI3MzMwZmQ5YTQwYjQwZGZiNjgxZGYyY2ZiMDU4YzEyL3RhYmxlcmFuZ2U6YjczMzBmZDlhNDBiNDBkZmI2ODFkZjJjZmIwNThjMTJfMzYtMS0xLTEtODk3MA_41d2a042-a777-4a7d-9919-d0a48f392a7f']" -

returns the XBRL field from the filing that the net_income_loss value originated from:

<us-gaap:ProfitLoss contextRef="i7c1224b9750a41c3b1f4f4b63f82e52d_D20210101-20210331" decimals="-6" id="id3VybDovL2RvY3MudjEvZG9jOmNkZWYxMGE0NGJhOTRjNTM4MjNlMGU2YWM1NWQ4NWUzL3NlYzpjZGVmMTBhNDRiYTk0YzUzODIzZTBlNmFjNTVkODVlM18xOS9mcmFnOmJhNDQ1YmVlODE4MDQzOGZiOWEzZDVhYTliNzZjYzUwL3RhYmxlOmI3MzMwZmQ5YTQwYjQwZGZiNjgxZGYyY2ZiMDU4YzEyL3RhYmxlcmFuZ2U6YjczMzBmZDlhNDBiNDBkZmI2ODFkZjJjZmIwNThjMTJfMzYtMS0xLTEtODk3MA_41d2a042-a777-4a7d-9919-d0a48f392a7f" unitRef="usd">
-342000000
</us-gaap:ProfitLoss>

We’re releasing this API in experimental mode while we handle feedback. We want to hear from you, so check out the docs and leave your thoughts using the ‘Submit Feedback’ button.

• 

  Katie Adams

  katie

  Read More