# EODHDC
Python client for the EOD Historical Data service REST / WebSockets API and provides various financial data
including stock market, splits and dividends, fundamental and economic, exchanges and alternative data feeds.
Provides synchronous and asynchronous interfaces for HTTP API, asynchronous interface for WebSockets.
[Documentation](https://eodhdc.readthedocs.io/)
## Installation
For normal usage you will need API key which you can get from [here](https://eodhistoricaldata.com/).
Supported Python version >= 3.7
Package can be installed using pip or poetry:
```
pip install eodhdc
```
```
poetry add eodhdc
```
To support additional HTTP clients install with extras:
```
pip install eodhdc[httpx,aiohttp]
```
## Quickstart
Asynchronous usage
```python
import asyncio
from eodhdc import EODHDClient
eodhdc = EODHDClient("httpxa", key="demo")
async with eodhdc.session:
results = await asyncio.gather(
eodhdc.market.historical("MCD.US", start="2023-01-01", finish="2023-01-10", fmt="csv"),
eodhdc.market.historical("MCD.US", start="2023-01-01", finish="2023-01-10", fmt="json")
)
for result in results:
print(result)
```
Synchronous usage
```python
from eodhdc import EODHDClient
eodhdc = EODHDClient("requests", key="demo")
result = eodhdc.market.historical(
"AAPL.US", start="2023-01-01", finish="2023-01-10",
fmt="json", output="pandas:./response.csv", writer={"header": False}
)
print(result, "\n")
```
WebSockets usage
```python
from eodhdc import EODHDWebSockets
eodhdws = EODHDWebSockets(buffer=100)
async with eodhdws.connect("us") as websocket:
await eodhdws.subscribe(websocket, ["TSLA", "EURUSD"])
async for message in eodhdws.receive(websocket):
print(message)
if len(eodhdws.buffer) > 5:
await eodhdws.unsubscribe(websocket, ["EURUSD"])
if len(eodhdws.buffer) > 10:
eodhdws.deactivate()
print(eodhdws.buffer)
```
Also check `playground.py` for quickstart examples.
## Description
### Main client modules
- EODHDClient: HTTP API client, parameters are:
- client: http client module to use.
- key: api token.
- args: http client `get` args to use across requests.
- EODHDWebSockets: WebSockets API client, parameters are:
- key: api token.
- buffer: enable and set buffer size.
- args: websocket client args.
EODHDClient will automatically determine sync or async http client and provide corresponding interface
with same signature, so for example usage can easily be changed:
```python
eodhdc = EODHDClient("httpxs")
result = eodhdc.market.historical(...)
```
```python
eodhdc = EODHDClient("httpsxa")
result = await eodhdc.market.historical(...)
```
Asynchronous version of EODHDClient can be used without context manager, do not forget to call `destroy`
method to close session in that case.
EODHDWebSockets client provides following methods:
- connect: connect to web-socket endpoint, returns context manager.
- authorize: check authorization status, do not use directly as it will consume messages.
- subscribe: subscribe to the tickers.
- unsubscribe: unsubscribe from the tickers.
- receive: receive messages, async generator.
- activate: activate message loop.
- deactivate: deactivate message loop.
### HTTP client modules
- requests: default, well known, synchronous module.
- httpxs: httpx library, synchronous mode, 'httpx' extra.
- httpxa: httpx library, asynchronous mode, 'httpx' extra.
- aiohttp: aiohttp library, asynchronous mode, 'aiohttp' extra.
### HTTP API groups
Main HTTP API module contains groups that corresponds to EODHD API groups, and can be accessed like:
```eodhdc.market.<method>``` or ```eodhdc.exchange.<method>```
See below mapping for client groups and methods.
Visit official API [documentation](https://eodhistoricaldata.com/financial-apis/) for detailed description.
### HTTP API group methods
In addition to original API parameters each method have:
- args: override or add http client `get` args.
- output: output format and optionally file location, format is `<type>[:path]`
- types: response type
- "response": raw binary response body
- "content": decoded as response content type
- "pandas": pandas dataframe
- path: additionally save response to file
- for "response" and "content" will save as is
- for "pandas" will save in format specified by extension:
parquet, pickle, csv, hdf, xlsx, json, html, feather, tex, dta, md
- writer: pandas writer parameters, see [original](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_csv.html) `to_<format>` methods for more details.
note that some formats may require 3rd-party libraries.
additionally writer can be provided with:
- change:columns - dict to rename DataFrame columns.
- change:reorder - bool to use columns dict for DataFrame columns order.
- change:reindex - str or list to set DataFrame columns as index.
### API support status
API support status and mapping for client groups and methods.
- [x] HTTP
- [x] Stock Market Prices, Splits and Dividends Data API
- [x] End-Of-Day Historical Stock Market Data API
- market.historical
- [x] Live (Delayed) Stock Prices API
- market.delayed
- [x] Historical Splits and Dividends API
- market.dividends
- market.splits
- [x] Technical Indicator API
- market.indicators
- [x] Intraday Historical Data API
- market.intraday
- [x] Options Data API
- market.options
- [x] Fundamental and Economic Financial Data API
- [x] Fundamental Data for Cryptocurrencies
- fundamental.crypto
- [x] Historical Market Capitalization API
- fundamental.capitalization
- [x] Insider Transactions API
- fundamental.insider
- [x] Fundamental Data: Stocks, ETFs, Mutual Funds, Indices
- fundamental.fundamentals
- fundamental.bulk
- [x] Calendar. Upcoming Earnings, Trends, IPOs and Splits
- fundamental.calendar
- [x] Bonds Fundamentals and Historical API
- fundamental.bonds
- [x] Exchanges (Stock Market) Financial APIs
- [x] Bulk API for EOD, Splits and Dividends
- exchange.bulk
- [x] Exchanges API. Get List of Tickers
- exchange.exchanges
- exchange.tickers
- [x] Exchanges API. Trading Hours, Stock Market Holidays, Symbols Change History
- exchange.details
- exchange.history
- [x] Stock Market Screener API
- exchange.screener
- [x] Search API for Stocks, ETFs, Mutual Funds and Indices
- exchange.search
- [x] Alternative Data Financial API
- [x] Sentiment Data Financial API for News and Tweets
- alternative.sentiment
- [x] Economic Events Data API
- alternative.events
- [x] Stock Market and Financial News API
- alternative.news
- [x] Macro Indicators API
- alternative.macroindicators
- [x] Macroeconomic Data API
- alternative.macroeconomic
- [x] WebSockets
- [x] Stock Market Prices, Splits and Dividends Data API
- [x] Real-Time Data API
### Exceptions
Exceptions hierarchy:
- **ClientException**: Base HTTP client exception.
- **ClientConnectionTimeout**: Client connection timeout exception.
- **ClientConnectionError**: Client connection error exception.
- **ClientHTTPError**: Client HTTP error exception.
- **ModuleException**: Base module exception.
- **FileIOError**: File IO exception.
- **UnsupportedContentType**: Unsupported response content exception.
- **UnsupportedExtension**: Unsupported pandas extension exception.
- **JSONDecodeError**: JSON decoding exception.
- **BytesDecodeError**: Bytes decoding exception.
- **PandasRuntimeError**: Pandas runtime exception.
- **UnknownClient**: Unknown client exception.
- **ImproperClient**: Improper client exception.
- **WebsocketException**: Base websocket exception.
- **WebsocketUnknownEndpoint**: Websocket unknown endpoint exception.
- **WebsocketAuthError**: Websocket authentication exception.
- **WebsocketResponseError**: Websocket response error exception.
## Custom HTTP clients
Additionally, you can provide your own HTTP client by passing its module instead of name string.
Module should implement `get` method and `create` and `destroy` can be provided for asynchronous session management.
Check modules under `eodhd.clients` for details about required parameters, return data type and exceptions handling.
## Disclaimer
The information in this document is for informational and educational purposes only. Nothing in this document
can be construed as financial, legal, or tax advice. The content of this document is solely the opinion of the
author, who is not a licensed financial advisor or registered investment advisor. The author is not affiliated
as a promoter of EOD Historical Data services.
This document is not an offer to buy or sell financial instruments. Never invest more than you can afford to
lose. You should consult a registered professional advisor before making any investment.
Raw data
{
"_id": null,
"home_page": "https://github.com/wargx/eodhdc",
"name": "eodhdc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.16,<4.0.0",
"maintainer_email": "",
"keywords": "eod,eodhd,financial,historical,economic,data,api,fundamental,alternative,insider,real-time,exchanges,capitalization,bulk,intraday,options",
"author": "Warg",
"author_email": "warg.silencer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/93/c5/203fadac670b3d331bc878b913080496e3a10a6657e858841f90c088f992/eodhdc-0.9.1.tar.gz",
"platform": null,
"description": "# EODHDC\n\n\n\n\n\n\n \n\n\n\n\n\n\nPython client for the EOD Historical Data service REST / WebSockets API and provides various financial data \nincluding stock market, splits and dividends, fundamental and economic, exchanges and alternative data feeds.\nProvides synchronous and asynchronous interfaces for HTTP API, asynchronous interface for WebSockets. \n\n[Documentation](https://eodhdc.readthedocs.io/)\n\n## Installation\n\nFor normal usage you will need API key which you can get from [here](https://eodhistoricaldata.com/). \nSupported Python version >= 3.7\n\nPackage can be installed using pip or poetry:\n```\npip install eodhdc\n```\n```\npoetry add eodhdc\n```\nTo support additional HTTP clients install with extras:\n```\npip install eodhdc[httpx,aiohttp]\n```\n\n## Quickstart\n\nAsynchronous usage\n```python\nimport asyncio\nfrom eodhdc import EODHDClient\n\neodhdc = EODHDClient(\"httpxa\", key=\"demo\")\nasync with eodhdc.session:\n results = await asyncio.gather(\n eodhdc.market.historical(\"MCD.US\", start=\"2023-01-01\", finish=\"2023-01-10\", fmt=\"csv\"),\n eodhdc.market.historical(\"MCD.US\", start=\"2023-01-01\", finish=\"2023-01-10\", fmt=\"json\")\n )\nfor result in results:\n print(result)\n```\n\nSynchronous usage\n```python\nfrom eodhdc import EODHDClient\n\neodhdc = EODHDClient(\"requests\", key=\"demo\")\nresult = eodhdc.market.historical(\n \"AAPL.US\", start=\"2023-01-01\", finish=\"2023-01-10\",\n fmt=\"json\", output=\"pandas:./response.csv\", writer={\"header\": False}\n)\nprint(result, \"\\n\")\n```\n\nWebSockets usage\n```python\nfrom eodhdc import EODHDWebSockets\n\neodhdws = EODHDWebSockets(buffer=100)\nasync with eodhdws.connect(\"us\") as websocket:\n await eodhdws.subscribe(websocket, [\"TSLA\", \"EURUSD\"])\n async for message in eodhdws.receive(websocket):\n print(message)\n if len(eodhdws.buffer) > 5:\n await eodhdws.unsubscribe(websocket, [\"EURUSD\"])\n if len(eodhdws.buffer) > 10:\n eodhdws.deactivate()\n\nprint(eodhdws.buffer)\n```\n\nAlso check `playground.py` for quickstart examples. \n\n## Description\n\n### Main client modules\n\n- EODHDClient: HTTP API client, parameters are:\n - client: http client module to use.\n - key: api token.\n - args: http client `get` args to use across requests.\n\n- EODHDWebSockets: WebSockets API client, parameters are:\n - key: api token.\n - buffer: enable and set buffer size.\n - args: websocket client args.\n\nEODHDClient will automatically determine sync or async http client and provide corresponding interface \nwith same signature, so for example usage can easily be changed:\n\n```python\neodhdc = EODHDClient(\"httpxs\")\nresult = eodhdc.market.historical(...)\n```\n\n```python\neodhdc = EODHDClient(\"httpsxa\")\nresult = await eodhdc.market.historical(...)\n```\n\nAsynchronous version of EODHDClient can be used without context manager, do not forget to call `destroy` \nmethod to close session in that case. \n\nEODHDWebSockets client provides following methods:\n- connect: connect to web-socket endpoint, returns context manager.\n- authorize: check authorization status, do not use directly as it will consume messages. \n- subscribe: subscribe to the tickers.\n- unsubscribe: unsubscribe from the tickers.\n- receive: receive messages, async generator.\n- activate: activate message loop.\n- deactivate: deactivate message loop.\n\n### HTTP client modules\n\n- requests: default, well known, synchronous module.\n- httpxs: httpx library, synchronous mode, 'httpx' extra.\n- httpxa: httpx library, asynchronous mode, 'httpx' extra.\n- aiohttp: aiohttp library, asynchronous mode, 'aiohttp' extra.\n\n### HTTP API groups\n\nMain HTTP API module contains groups that corresponds to EODHD API groups, and can be accessed like: \n```eodhdc.market.<method>``` or ```eodhdc.exchange.<method>``` \nSee below mapping for client groups and methods. \nVisit official API [documentation](https://eodhistoricaldata.com/financial-apis/) for detailed description. \n\n### HTTP API group methods\n\nIn addition to original API parameters each method have:\n- args: override or add http client `get` args.\n- output: output format and optionally file location, format is `<type>[:path]`\n - types: response type\n - \"response\": raw binary response body\n - \"content\": decoded as response content type\n - \"pandas\": pandas dataframe\n - path: additionally save response to file\n - for \"response\" and \"content\" will save as is\n - for \"pandas\" will save in format specified by extension: \n parquet, pickle, csv, hdf, xlsx, json, html, feather, tex, dta, md \n- writer: pandas writer parameters, see [original](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_csv.html) `to_<format>` methods for more details. \n note that some formats may require 3rd-party libraries. \n additionally writer can be provided with:\n - change:columns - dict to rename DataFrame columns. \n - change:reorder - bool to use columns dict for DataFrame columns order.\n - change:reindex - str or list to set DataFrame columns as index.\n\n### API support status\n\nAPI support status and mapping for client groups and methods. \n\n- [x] HTTP\n - [x] Stock Market Prices, Splits and Dividends Data API\n - [x] End-Of-Day Historical Stock Market Data API\n - market.historical \n - [x] Live (Delayed) Stock Prices API\n - market.delayed\n - [x] Historical Splits and Dividends API\n - market.dividends\n - market.splits\n - [x] Technical Indicator API\n - market.indicators\n - [x] Intraday Historical Data API\n - market.intraday\n - [x] Options Data API\n - market.options\n - [x] Fundamental and Economic Financial Data API\n - [x] Fundamental Data for Cryptocurrencies\n - fundamental.crypto\n - [x] Historical Market Capitalization API\n - fundamental.capitalization\n - [x] Insider Transactions API\n - fundamental.insider\n - [x] Fundamental Data: Stocks, ETFs, Mutual Funds, Indices\n - fundamental.fundamentals\n - fundamental.bulk\n - [x] Calendar. Upcoming Earnings, Trends, IPOs and Splits\n - fundamental.calendar\n - [x] Bonds Fundamentals and Historical API\n - fundamental.bonds\n - [x] Exchanges (Stock Market) Financial APIs\n - [x] Bulk API for EOD, Splits and Dividends\n - exchange.bulk\n - [x] Exchanges API. Get List of Tickers\n - exchange.exchanges\n - exchange.tickers\n - [x] Exchanges API. Trading Hours, Stock Market Holidays, Symbols Change History\n - exchange.details\n - exchange.history\n - [x] Stock Market Screener API\n - exchange.screener\n - [x] Search API for Stocks, ETFs, Mutual Funds and Indices\n - exchange.search\n - [x] Alternative Data Financial API\n - [x] Sentiment Data Financial API for News and Tweets\n - alternative.sentiment\n - [x] Economic Events Data API\n - alternative.events\n - [x] Stock Market and Financial News API\n - alternative.news\n - [x] Macro Indicators API\n - alternative.macroindicators\n - [x] Macroeconomic Data API\n - alternative.macroeconomic\n- [x] WebSockets\n - [x] Stock Market Prices, Splits and Dividends Data API\n - [x] Real-Time Data API\n\n### Exceptions\n\nExceptions hierarchy:\n\n- **ClientException**: Base HTTP client exception.\n - **ClientConnectionTimeout**: Client connection timeout exception. \n - **ClientConnectionError**: Client connection error exception. \n - **ClientHTTPError**: Client HTTP error exception.\n- **ModuleException**: Base module exception. \n - **FileIOError**: File IO exception. \n - **UnsupportedContentType**: Unsupported response content exception. \n - **UnsupportedExtension**: Unsupported pandas extension exception. \n - **JSONDecodeError**: JSON decoding exception. \n - **BytesDecodeError**: Bytes decoding exception. \n - **PandasRuntimeError**: Pandas runtime exception. \n - **UnknownClient**: Unknown client exception. \n - **ImproperClient**: Improper client exception.\n- **WebsocketException**: Base websocket exception. \n - **WebsocketUnknownEndpoint**: Websocket unknown endpoint exception. \n - **WebsocketAuthError**: Websocket authentication exception. \n - **WebsocketResponseError**: Websocket response error exception.\n\n## Custom HTTP clients\n\nAdditionally, you can provide your own HTTP client by passing its module instead of name string. \nModule should implement `get` method and `create` and `destroy` can be provided for asynchronous session management. \nCheck modules under `eodhd.clients` for details about required parameters, return data type and exceptions handling.\n\n## Disclaimer\n\nThe information in this document is for informational and educational purposes only. Nothing in this document \ncan be construed as financial, legal, or tax advice. The content of this document is solely the opinion of the \nauthor, who is not a licensed financial advisor or registered investment advisor. The author is not affiliated \nas a promoter of EOD Historical Data services. \n\nThis document is not an offer to buy or sell financial instruments. Never invest more than you can afford to \nlose. You should consult a registered professional advisor before making any investment.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "EOD Historical Data API Python Client",
"version": "0.9.1",
"split_keywords": [
"eod",
"eodhd",
"financial",
"historical",
"economic",
"data",
"api",
"fundamental",
"alternative",
"insider",
"real-time",
"exchanges",
"capitalization",
"bulk",
"intraday",
"options"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3aa9a00f24994b6cfe2bb5733e317a9fa0371b916e5222f586cd02a41da0473c",
"md5": "8fc82aeed749a9ffa320a8f83870a736",
"sha256": "9149ce2180e3a47a238176d3f34806a8dbfb8cfe4df3a1e9f61282c4b95de6d4"
},
"downloads": -1,
"filename": "eodhdc-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fc82aeed749a9ffa320a8f83870a736",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.16,<4.0.0",
"size": 26668,
"upload_time": "2023-02-02T18:16:57",
"upload_time_iso_8601": "2023-02-02T18:16:57.096428Z",
"url": "https://files.pythonhosted.org/packages/3a/a9/a00f24994b6cfe2bb5733e317a9fa0371b916e5222f586cd02a41da0473c/eodhdc-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "93c5203fadac670b3d331bc878b913080496e3a10a6657e858841f90c088f992",
"md5": "689a63172c6d0ec25b91055976aa90c6",
"sha256": "cf65f8eb06739491b29d2efcf5c81f23c5ae9833cd8eb085c82ed03d226fdeca"
},
"downloads": -1,
"filename": "eodhdc-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "689a63172c6d0ec25b91055976aa90c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.16,<4.0.0",
"size": 19622,
"upload_time": "2023-02-02T18:16:59",
"upload_time_iso_8601": "2023-02-02T18:16:59.392793Z",
"url": "https://files.pythonhosted.org/packages/93/c5/203fadac670b3d331bc878b913080496e3a10a6657e858841f90c088f992/eodhdc-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-02 18:16:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "wargx",
"github_project": "eodhdc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "eodhdc"
}
JSON
