---
title: "finreportr – Querying Data from the U.S. Securities and Exchange Commission"
author: "Seward Lee"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{finreportr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

A financial analyst's time is valuable – it shouldn't be wasted on performing manual data entry. **finreportr** is a web scraper written in R that allows analysts to query data from the U.S. Securities and Exchange Commission directly from the R console.  It aims to eliminate time wasters from a financial analyst's workflow, such as navigating the SEC EDGAR database, flipping through financial reports, and parsing XBRL-encoded data.

**finreportr** allows you to fetch data from the SEC and load it into your workspace using the following commands:

* `CompanyInfo()`: returns basic information about a company
* `AnnualReports()`: returns a listing of annual reports filed by a company
* `GetIncome()`: returns the income statement for a given company
* `GetBalanceSheet()`: returns the balance sheet for a given company
* `GetCashFlow()`: returns the cash flow statement for a given company

## Querying Company Information

**finreportr** provides two functions that allow users to acquire background information relating to publicly-listed companies.

The function `CompanyInfo()` returns the following information about a company based on its stock ticker symbol:

* Name
* [Central Index Key ("CIK")](https://en.wikipedia.org/wiki/Central_Index_Key)
* [Standard  Industrial Classification ("SIC")](https://en.wikipedia.org/wiki/Standard_Industrial_Classification)
* State Location
* State of Incorporation
* Fiscal Year End
* Address

For example, suppose we want to do a quick search on Google/Alphabet (symbol: `GOOG`):

```
> CompanyInfo("GOOG")

      company        CIK  SIC state state.inc FY.end            street.address             city.state
1 GOOGLE INC. 0001288776 7370    CA        DE   1231 1600 AMPHITHEATRE PARKWAY MOUNTAIN VIEW CA 94043
```

The function `AnnualReports()` returns a data frame that summarizes a company's annual reports based on its stock ticker symbol. It will return data relating to a company's [Form 10-Ks](https://www.investopedia.com/terms/1/10-k.asp) if the company is domestic, and [Form 20-Fs](https://www.investopedia.com/terms/s/sec-form-20-f.asp) if the company is foreign. 

For example, suppose we want to display the annual reports filed by Facebook (symbol: `FB`):

```
> AnnualReports("FB")

  filing.name filing.date         accession.no
1        10-K  2016-01-28 0001326801-16-000043
2      10-K/A  2015-02-13 0001326801-15-000010
3        10-K  2015-01-29 0001326801-15-000006
4        10-K  2014-01-31 0001326801-14-000007
5        10-K  2013-02-01 0001326801-13-000003
```


## Querying Financial Data

The main benefit of **finreportr** comes from allowing users to download and display financial data without having to manually inspect filings from the SEC EDGAR database. This creates opportunities for users to introduce automation, scalability, and reproducibility to their analysis.

The function `GetIncome()` returns a company's income statement from a given filing year. Suppose we want the income statement of Tesla Motors (symbol: `TSLA`) from the annual report filed in 2015:

```
> head(GetIncome("TSLA", 2015))

                      Metric        Units     Amount  startDate    endDate
1    Sales Revenue Goods Net U_iso4217USD  385699000 2012-01-01 2012-12-31
2    Sales Revenue Goods Net U_iso4217USD 1997786000 2013-01-01 2013-12-31
3    Sales Revenue Goods Net U_iso4217USD 3192723000 2014-01-01 2014-12-31
4 Sales Revenue Services Net U_iso4217USD   27557000 2012-01-01 2012-12-31
5 Sales Revenue Services Net U_iso4217USD   15710000 2013-01-01 2013-12-31
6 Sales Revenue Services Net U_iso4217USD    5633000 2014-01-01 2014-12-31
```

The function `GetBalanceSheet()` returns a company's balance sheet from a given filing year. Suppose we want the balance sheet of Apple (symbol: `AAPL`) from the annual report filed in 2012:

```
> head(GetBalanceSheet("AAPL", 2012))

                                    Metric       Units      Amount startDate    endDate
1 Available For Sale Securities Noncurrent iso4217_USD 55618000000      <NA> 2011-09-24
2 Available For Sale Securities Noncurrent iso4217_USD 92122000000      <NA> 2012-09-29
3         Property Plant And Equipment Net iso4217_USD  7777000000      <NA> 2011-09-24
4         Property Plant And Equipment Net iso4217_USD 15452000000      <NA> 2012-09-29
5                                 Goodwill iso4217_USD   896000000      <NA> 2011-09-24
6                                 Goodwill iso4217_USD  1135000000      <NA> 2012-09-29
```

The function `GetCashFlow()` returns a company's cash flow statement from a given filing year. Suppose we want the cash flow statement of LinkedIn (symbol: `LNKD`) from the annual report filed in 2014:

```
> head(GetCashFlow("LNKD", 2014))

                                                   Metric Units    Amount  startDate    endDate
1                Net Income (Loss) Attributable to Parent   usd  11912000 2011-01-01 2011-12-31
2                Net Income (Loss) Attributable to Parent   usd  21610000 2012-01-01 2012-12-31
3                Net Income (Loss) Attributable to Parent   usd  26769000 2013-01-01 2013-12-31
4 Depreciation, Depletion and Amortization, Nonproduction   usd  43100000 2011-01-01 2011-12-31
5 Depreciation, Depletion and Amortization, Nonproduction   usd  79849000 2012-01-01 2012-12-31
6 Depreciation, Depletion and Amortization, Nonproduction   usd 134516000 2013-01-01 2013-12-31
```