Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dannyben/eod
EOD Historical Data API Library and Command Line
https://github.com/dannyben/eod
api api-client command-line economic-data eod-data-downloader financial-data gem ruby stock-data
Last synced: 3 months ago
JSON representation
EOD Historical Data API Library and Command Line
- Host: GitHub
- URL: https://github.com/dannyben/eod
- Owner: DannyBen
- License: mit
- Created: 2022-03-31T16:25:14.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-03-29T07:58:59.000Z (almost 2 years ago)
- Last Synced: 2024-05-01T14:12:06.622Z (8 months ago)
- Topics: api, api-client, command-line, economic-data, eod-data-downloader, financial-data, gem, ruby, stock-data
- Language: Ruby
- Homepage:
- Size: 37.1 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# EOD Historical Data API Library and Command Line
[![Gem Version](https://badge.fury.io/rb/eod.svg)](https://badge.fury.io/rb/eod)
[![Build Status](https://github.com/DannyBen/eod/workflows/Test/badge.svg)](https://github.com/DannyBen/eod/actions?query=workflow%3ATest)
[![Maintainability](https://api.codeclimate.com/v1/badges/52438abcc1532b93b525/maintainability)](https://codeclimate.com/github/DannyBen/eod/maintainability)---
This gem provides both a Ruby library and a command line interface for the
[EOD Historical Data][docs] data service.This gem is not affiliated with EOD Historical Data.
---
## Install
```
$ gem install eod
```## Features
* Easy to use interface.
* Use as a library or through the command line.
* Access any EOD Historical Data endpoint and option directly, no need to learn
anything other than the original API documentation.
* Display output as JSON, YAML or CSV.
* Save output to a file as JSON, YAML or CSV.
* Includes a built in file cache, so you can avoid wasting API calls.
* Lightweight.
* Future proof. In case new endpoints are added to the API, they will
immediately become available in the Ruby library (but not in the CLI).## Usage
First, require and initialize with your EOD API token:
```ruby
require 'eod'
api_token = 'OeAFFmMliFG5orCUuwAKQ8l4WWFQ67YX' # demo token
api = EOD::API.new api_token
```Now, you can access any of the API endpoints with any optional parameter, like
this:```ruby
result = api.get "eod", 'AAPL.US', period: 'm'
```In addition, for convenience, you can use the first part of the endpoint as
a method name, like this:```ruby
result = api.eod 'AAPL.US', period: 'm', from: '2022-01-01'
```In other words, these calls are the same:
```ruby
api.get 'endpoint', param: value
api.endpoint, param: value
```as well as these two:
```ruby
api.get 'endpoint/sub', param: value
api.endpoint 'sub', param: value
```By default, you will get a ruby hash in return. If you wish to have more
control over the response, use the `get!` method instead:```ruby
payload = api.get! 'eod', 'AAPL.US'# Request Object
p payload.request.class
# => HTTParty::Request# Response Object
p payload.response.class
# => Net::HTTPOKp payload.response.body
# => JSON stringp payload.response.code
# => 200p payload.response.msg
# => OK# Headers Object
p payload.headers
# => Hash with headers# Parsed Response Object
p payload.parsed_response
# => Hash with HTTParty parsed response
# (this is the content returned with #get)
```You can get the response as CSV by calling `get_csv`:
```ruby
result = api.get_csv "eod", 'AAPL.US'
# => CSV string
```or, if you prefer, you can request a CSV from the API directly, by using the
`fmt` argument:```ruby
result = api.eod 'AAPL.US', fmt: 'csv'
# => CSV string
```To save the output directly to a file, use the `save` method:
```ruby
api.save 'filename.json', 'eod/AAPL.US', period: 'm'
```Or, to save CSV, use the `save_csv` method:
```ruby
api.save_csv "filename.csv", "eod/AAPL.US", period: 'm'
```## Command Line Interface
The command line utility `eod` that is installed when installing the gem acts
in a similar way. The main difference is that you provide any API query string
argument using the `key:value` format.First, set your API token in the environment variable `EOD_API_TOKEN`:
```bash
$ export EOD_API_TOKEN=OeAFFmMliFG5orCUuwAKQ8l4WWFQ67YX
````Now, you can run one of the many API commands, for example:
```shell
# Show monthly AAPL data in a pretty colorful output
$ eod data AAPL.US period:m# Show monthly AAPL data in CSV format
$ eod data AAPL.US --format csv from:2022-01-01 period:m# Saves a file
$ eod data AAPL.US --format csv --save aapl.csv from:2022-01-01 period:m# Show live (delayed) data
# eod live AAPL.US
```Run [`eod --help`](#full-command-line-usage-patterns) for the full list of usage
patterns.## Supported endpoints
- The Ruby library supports all current and future endpoints.
- The CLI supports most (if not all) current endpoints. If you know of an
endpoint that is not supported, please create an [issue][issues].## Caching
We are using the [Lightly][lightly] gem for automatic HTTP caching.
You can disable or customize it by either passing options on
initialization, or by accessing the `WebCache` object directly at
a later stage.```ruby
# Disable cache completely
api = EOD::API.new api_token, use_cache: false# Set different cache directory or lifetime
api = EOD::API.new api_token, cache_dir: 'data', cache_ilfe: '2h'# Or configure cache after initializaation:
api = EOD::API.new api_token
api.cache.disable
api.cache.enable
api.cache.dir = 'tmp/cache' # Change cache folder
api.cache.life = '30m' # Change cache life to 30 minutes
```To enable caching for the command line, simply set one or both of
these environment variables:```shell
$ export EOD_CACHE_DIR=cache # default: 'cache'
$ export EOD_CACHE_LIFE=2h # default: 3600 (1 hour)
```To disable cache for the CLI, set `EOD_CACHE_LIFE=off`.
The cache life argument supports these formats:
- `20s` - 20 seconds
- `10m` - 10 minutes
- `10h` - 10 hours
- `10d` - 10 days## Full command line usage patterns
```
$ eod --helpEOD Historical Data API
API Documentation:
https://eodhistoricaldata.com/financial-apis/Usage:
eod bond SYMBOL [options] [PARAMS...]
eod bulk EXCHANGE [options] [PARAMS...]
eod calendar CALENDAR [options] [PARAMS...]
eod data SYMBOL [options] [PARAMS...]
eod dividends SYMBOL [options] [PARAMS...]
eod events [options] [PARAMS...]
eod exchange EXCHANGE [options] [PARAMS...]
eod exchanges [options] [PARAMS...]
eod fundamental SYMBOL [options] [PARAMS...]
eod fundamental_bulk SYMBOL [options] [PARAMS...]
eod insider [options] [PARAMS...]
eod intraday SYMBOL [options] [PARAMS...]
eod live SYMBOL [options] [PARAMS...]
eod macro COUNTRY [options] [PARAMS...]
eod news [options] [PARAMS...]
eod opts SYMBOL [options] [PARAMS...]
eod screener [options] [PARAMS...]
eod search QUERY [options] [PARAMS...]
eod splits SYMBOL [options] [PARAMS...]
eod symbols EXCHANGE [options] [PARAMS...]
eod technical SYMBOL [options] [PARAMS...]
eod (-h|--help|--version)Commands:
bond
Bond fundamental data (/bond-fundamentals)bulk
Historical EOD bulk data (/eod-bulk-last-day)calendar
Calendar data (earnings, trends, IPOs and splits) (/calendar)data
Historical EOD data (/eod)dividends
Dividends data (/div)events
Economic events data (/economic-events)exchange
Details about an exchange (/exchanges-details)exchanges
List of exchanges (/exchanges-list)fundamental
Fundamental data (/fundamentals)fundamental_bulk
Bulk fundamental data (/bulk-fundamentals)insider
Insider transactions data (/insider-transactions)intraday
Intraday data (/intraday)live
Live data (/real-time)macro
Macroeconomics data (/macro-indicator)news
Financial news (/news)opts
Options data (/options)screener
Stock market screener (/screener)search
Search for stocks, ETFs, funds or indices (/search)splits
Splits data (/splits)symbols
List of symbols for an exchange (/exchange-symbol-list)technical
Technical data (/technical)Options:
-f --format FORMAT
Output format: csv, json, yaml, pretty or url [default: pretty]-s --save PATH
Save output to file-h --help
Show this help--version
Show version numberParameters:
SYMBOL
Ticker symbolCALENDAR
Calendar type: earnings, trends, ipos or splitsCOUNTRY
Country code in the Alpha-3 ISO formatEXCHANGE
Exchange codePARAMS
An optional list of query string parameters, separated by a space, to send
with the request. Each parameter should be in the format of key:value.
example: period:w from:2022-01-01
See https://eodhistoricaldata.com/financial-apis/ for all supported params.Environment Variables:
EOD_API_TOKEN
Your EOD Historical Data API token [required]EOD_CACHE_DIR
API cache diredctory [default: cache]EOD_CACHE_LIFE
API cache life. These formats are supported:
off - No cache
20s - 20 seconds
10m - 10 minutes
10h - 10 hours
10d - 10 daysEOD_API_URI
Override the API URI [default: https://eodhistoricaldata.com/api]Examples:
eod symbols NASDAQ
eod data AAPL.US
eod data AAPL.US --format csv period:m from:2022-01-01
eod live AAPL.US -fyaml
eod fundamental 'AAPL.US' filter:General
eod technical AAPL.US function:sma
eod macro USA indicator:inflation_consumer_prices_annual```
## Contributing / Support
If you experience any issue, have a question or a suggestion, or if you wish
to contribute, feel free to [open an issue][issues].[docs]: https://eodhistoricaldata.com/financial-apis
[issues]: https://github.com/DannyBen/eod/issues
[lightly]: https://github.com/DannyBen/lightly