From 397a388a72207ed917f0a845a7f02e8670942f2b Mon Sep 17 00:00:00 2001 From: jeroen Date: Wed, 8 Feb 2023 13:57:45 +0100 Subject: [PATCH] Update the documentation so the importance of API keys is more clear --- .../terminal/guides/advanced/api-keys.md | 12 +- .../content/terminal/guides/basics/index.md | 106 +++++++++++++++++- 2 files changed, 111 insertions(+), 7 deletions(-) diff --git a/website/content/terminal/guides/advanced/api-keys.md b/website/content/terminal/guides/advanced/api-keys.md index d3853d859de..0330891422e 100644 --- a/website/content/terminal/guides/advanced/api-keys.md +++ b/website/content/terminal/guides/advanced/api-keys.md @@ -7,15 +7,21 @@ keywords: [api, keys, api keys, data provider, data, free, alpha vantage, fred, ## Accessing the keys menu -Within the `keys` menu you can define your, often free, API key from various platforms like Alpha Vantage, FRED, IEX, Twitter, DeGiro, Binance and Coinglass. An API key is a set of random characters provided to you by a third party vendor that allows you to access data via their API endpoints. +Within the `keys` menu you can define your, often free, API key from various platforms like Alpha Vantage, FRED, IEX, Twitter, DeGiro, Binance and Coinglass. An API key is a set of random characters provided to you by a third party vendor that allows you to access data via their API endpoints. You will notice that you need an API key when you receive a message like the following: -You can access this menu from the homepage with `keys` which will open the menu as shown below: +``` +(🦋) /stocks/fa/ $ rot + +API_FINNHUB_KEY not defined. Set API Keys in ~/.openbb_terminal/.env or under keys menu. +``` + +You can access the `keys` menu as mentioned above from the homepage with `keys` (or directly from your current menu with `/keys`). This will open the menu as shown below: image Within this menu you are able to set your API keys to access the commands that require that key. You can do so by typing the command followed by the API key, for example: `fred a215egade08a8d47cfd49c849658a2be`. When you press `ENTER` (⏎) the terminal will test whether this API key works. If it does, you receive the message `defined, test passed` and if it does not, you receive the message `defined, test failed`. -To figure out where you can obtain the API key, you can enter the command (e.g. `av`) and press `ENTER` (⏎) or use the table below. **We recommend that you gradually obtain and set keys whenever you wish to use features that require an API key. For example, if you are interested in viewing recent news about a company, you should set the API key from the 'News API'.** +To figure out where you can obtain the API key, you can enter the command (e.g. `av`) and press `ENTER` (⏎) or use the table below. We also provide an elaborate explanation where to find the API key in the next section. **We recommend that you gradually obtain and set keys whenever you wish to use features that require an API key. For example, if you are interested in viewing recent news about a company, you should set the API key from the 'News API'.**
Summary of API Key Providers diff --git a/website/content/terminal/guides/basics/index.md b/website/content/terminal/guides/basics/index.md index ba98cea67ab..945cdcd947e 100644 --- a/website/content/terminal/guides/basics/index.md +++ b/website/content/terminal/guides/basics/index.md @@ -110,10 +110,108 @@ We can check that this period has changed by looking into the Explanation of Menus, some information also transfers over to other menus and this includes the loaded market data from load. So, if you would visit the `ta` menu (which stands for Technical Analysis) you will see that, by running any command, the selected period above is depicted again. Return to the Stocks menu again by using `q` and use it again to return to the home screen which can be shown with `?`. -### Defining your own source of data +### Expanding the Terminal with API keys +The OpenBB Terminal is built on a lot of different data sources. The example above collects data from Yahoo Finance. This could be undesirable and therefore we allow for a variety of different data sources. Think of Polygon, IEX Cloud, Alpha Vantage and Binance to name a few. Some of these sources require you to set an API Key to connect with their data. -The OpenBB Terminal is built on a lot of different data sources. The example above collects data from Yahoo Finance. This could be undesirable and therefore we allow for a variety of different data sources. Think of Polygon, IEX Cloud, Alpha Vantage and Binance to name a few. +:::note Setting API Keys +For an elaborate explanation of defining API keys to greatly extend the capabilities of the OpenBB Terminal, please have a look [**here**](/terminal/guides/advanced/api-keys). +::: -Some of these sources require you to set an API Key to connect with their data. You can find more information about setting these keys in the OpenBB Terminal [here](/terminal/guides/advanced/api-keys). +This becomes apparent when you receive a message like the following: -It is also possible to use your own datastreams. It could be that you have a dataset in Microsoft Excel or similar that you would like to import for usage within any of our functionalities. In that case, have a look [here](/terminal/guides/advanced/data). +``` +(🦋) /stocks/fa/ $ rot + +API_FINNHUB_KEY not defined. Set API Keys in ~/.openbb_terminal/.env or under keys menu. +``` + +We ensure that any source has a (usually extensive) free tier before we include the source. For example, you will be able to obtain 30+ years of fundamental data and query extensive economic databases by collecting just a few of the API keys. + +The [keys menu](/terminal/guides/advanced/api-keys) serves the purpose of providing you to set API keys so that this type of functionality becomes available. For example, in the case of `rot` you will see that the source is "FinnHub". + +``` +(🦋) /stocks/fa/ $ ? + +╭───────────────────────────────────────────────────────────────────────────────── Stocks - Fundamental Analysis ─────────────────────────────────────────────────────────────────────────────────╮ +│ │ +│ load load a specific stock ticker for analysis [YahooFinance, IEXCloud, AlphaVantage, Polygon, EODHD] │ +│ │ +│ Ticker: TSLA │ +│ │ +│ Company Overview: │ +│ enterprise company enterprise value [FinancialModelingPrep, YahooFinance] │ +│ overview financial overview of the company [Finviz, FinancialModelingPrep, AlphaVantage, YahooFinance] │ +│ divs show historical dividends for company [YahooFinance] │ +│ splits stock split and reverse split events since IPO [YahooFinance] │ +│ rating analyst prices and ratings over time of the company [Finviz, FinancialModelingPrep] │ +│ rot number of analyst ratings over time on a monthly basis [Finnhub] │ +│ score value investing scores for any time period [FinancialModelingPrep] │ +│ warnings company warnings according to Sean Seah book [MarketWatch] │ +│ sust sustainability values (environment, social and governance) [YahooFinance] +``` + +Therefore, you need to acquire an API key from FinnHub through the website and enter the key within the [keys menu](/terminal/guides/advanced/api-keys). + +### Importing and exporting data + +Any type of data that you see within the OpenBB Terminal, you will be able to export to a variety of files like xlsx, csv and json. + +:::note The OpenBBUserData Folder +All of the below examples are stored in the OpenBBUserData folder. This also applies to when you wish to import files, as is for example required within the [Portfolio menu](/terminal/guides/intros/portfolio). To find more information about this folder please have a look [**here**](/terminal/guides/advanced/data). +::: + +For example, if you wish to download market data you can do so from the stocks menu with the following: + +```console +/stocks/load AAPL -s 2010-01-01 --export xlsx +``` + +This results in the following: + +![Export Example](https://user-images.githubusercontent.com/46355364/214817681-fd5324c3-003c-45eb-adf4-96d5b41a3c02.png) + +We also allow you to define a file name, for example for the same stock tickers, we can also add in the filename. This time, we export to `csv`. + +```console +/stocks/load AAPL -s 2010-01-01 --export apple.csv +``` + +Which results in the following: + +![Filename Example](https://user-images.githubusercontent.com/46355364/214818131-597b3bd0-9c66-43f1-bf0e-2c0a703e2645.png) + +Lastly, when you select the `xlsx` option, you can also specify the sheet name with `--sheet-name` which allows multiple datasets to be send to the same Excel file. Using the same stock ticker, we can define the following. First, get market data from the `stocks` menu: + +```console +/stocks/load AAPL -s 2010-01-01 --export apple.xlsx --sheet-name Market Data +``` + +Then enter the `fa` (Fundamental Analysis) menu and type: + +**Income Statement:** + +```console +income --source FinancialModelingPrep -l 10 --export apple.xlsx --sheet-name Income Statement +``` + +**Balance Sheet:** +```console +balance --source FinancialModelingPrep -l 10 --export apple.xlsx --sheet-name Balance Sheet +``` + +**Cash Flow Statement:** + +```console +cash --source FinancialModelingPrep -l 10 --export apple.xlsx --sheet-name Cash Flow Statement +``` + +This generates a file for Apple with market data from 2010-01-01 until now and income, balance and cash flow statements over the last 10 years as seen in the image below. + +![Sheet Name Example](https://user-images.githubusercontent.com/46355364/214824561-6eaf3a88-746a-4abc-91e1-420c9036c00d.png) + +Next to that, we also allow exporting to images, this can be PNG, JPG, PDF and SVG. For example, using our `portfolio` menu we can export the charts to any type of format which again can be found within the `OpenBBUserData` folder. + +![image](https://user-images.githubusercontent.com/46355364/214819518-cec40468-9019-440c-8bfe-7bcabc207578.png) + + +It is also possible to use your own datastreams. It could be that you have a dataset in Microsoft Excel or similar that you would like to import for usage within any of our functionalities. Often functionalities will have a `--file` argument which refers to your own file. \ No newline at end of file