{"id":31829913,"url":"https://github.com/legout/yfin","last_synced_at":"2025-10-11T20:58:42.718Z","repository":{"id":133490498,"uuid":"532581479","full_name":"legout/yfin","owner":"legout","description":"python wrapper for the yahoo finance api","archived":false,"fork":false,"pushed_at":"2024-05-01T07:09:29.000Z","size":80501,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-10T03:27:11.970Z","etag":null,"topics":["poetry-python","python","yahoo-finance","yahoo-finance-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/legout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-04T15:36:19.000Z","updated_at":"2025-01-26T02:16:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"42893091-0c05-4b8a-8abb-90dc214a6866","html_url":"https://github.com/legout/yfin","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/legout/yfin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/legout%2Fyfin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/legout%2Fyfin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/legout%2Fyfin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/legout%2Fyfin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/legout","download_url":"https://codeload.github.com/legout/yfin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/legout%2Fyfin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279008635,"owners_count":26084480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["poetry-python","python","yahoo-finance","yahoo-finance-api"],"created_at":"2025-10-11T20:58:40.670Z","updated_at":"2025-10-11T20:58:42.711Z","avatar_url":"https://github.com/legout.png","language":"Python","funding_links":["https://ko-fi.com/W7W0ACJPB"],"categories":[],"sub_categories":[],"readme":"# yFin - A blazing fast python wrapper for the Yahoo Fincance API\n\nYfin is yet another python wrapper for the Yahoo Finance API. \n\nBy using asyncronous coroutines the http requests are performed in parallel and downloading data is blazing fast. Additionally, to avoid yahoo finance rate limiting, you can use random proxies. \n \nFor every function an async version is available. e.g. for downloading hisorical data there is the function `history` and `history_async`. \n\nThis python library currently has functions to download\n - historical OHLCV data\n - fundamental data\n - quotes\n - symbol search\n\n## Installation\n```\npip install git+https://github.com/legout/yfin.git\n```\n\n## Usage\n\n[Example Notebook](examples/examples.ipynb)\n\n```python\nimport datetime as dt\nimport pandas as pd\n\n# Use nest_asyncio, when you are in a jupyter notebook/lab\nimport nest_asyncio\nnest_asyncio.apply()\n```\n#### 1. Hisorical OHLCV data\n\nHistorical data can be downloaded for in several symbols in parallel. The number of symbols is limited to around 1000 if you do not use random proxies.\n \nThe time range can be set by using the parameters `start` and `end`. Both are timestamps, which can be defined as a string (e.g. `'2022-01-01'` or `'20220101'`) or a `datetime` object (e.g. `datetime.datetime(2022,1,1)`). If `end=None`, today is used as the end timestamp. \n \nInstead of using `start` and  `end`, one can also provide the timerange with the parameter  `period`. Valid optionsare  `1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, 25y, ytd, max`.\n \nThe parameter `freq` defines the interval between two data points. Valid options are `1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo`.\n\n```python\nfrom yfin.history import history, history_async\n\n# list of symbols can be of any size. Any valid yahoo symbol is supported. Symbols are available for this types: \n# equity, etf, mutualfund, futures, currency, cryptocurrency, index\n\nsymbols = [\"AAPL\", \"SF.ST\", \"DAX\", \"EUR=X\", \"BTC-USD\", \"HOH25.NYM\", \"0P00000WCP\", \"^SPX\"] \n\n# sync function. wraps the async function called with asyncio.run\ndata = history(symbols=symbols, start=dt.datetime(2022,1,1), end=dt.datetime.now(), freq=\"1d\")\n\n# async function\ndata = await history_async(symbols=symbols, start='20220101', end=None, freq=\"1d\")\n```\n\n#### 2. Quote Summary\n#\nThe python class `QuoteSummary` is used to get all the data available on yahoo finance for a specific financial asset. Most of the following properties are only valid for symbols of type equity (stocks).\n\nFollowing properties are available:\n \n - assetProfile\n - balanceSheetHistory\n - balanceSheetHistoryQuarterly\n - calendarEvents\n - cashflowStatementHistory\n - cashflowStatementHistoryQuarterly\n - defaultKeyStatistics\n - earnings\n - earningsHistory\n - earningsTrend\n - esgScores\n - financialData\n - fundOwnership\n - fundPerformance\n - fundProfile\n - indexTrend\n - incomeStatementHistory\n - incomeStatementHistoryQuarterly\n - industryTrend\n - insiderHolders\n - insiderTransactions\n - institutionOwnership\n - majorHoldersBreakdown\n - pageViews\n - price\n - quoteType\n - recommendationTrend\n - secFilings\n - netSharePurchaseActivity\n - sectorTrend\n - summaryDetail\n - summaryProfile\n - topHoldings\n - upgradeDowngradeHistory\n\n```python\nfrom yfin.quote_summary import QuoteSummary\n\nqs = QuoteSummary(symbols=[\"AAPL\", \"NET\", \"VOW.DE\", \"SF.ST\"])\n\n# use `fetch` to get the data for the given modules.\nres = await qs.fetch(modules=[\"upgradeDowngradeHistory\", \"insider_holders\"]) # you can use camel or snake case for the property names\n\n# Use class properties \n# Summary Profile\npd.DataFrame(qs.summary_profile)\n\n# Default Key Stats\npd.concat(qs.default_key_statistics).unstack()\n\n# Income Statement\npd.concat(qs.income_statement_history)\n\n# async function for earnings_history \npd.concat(await qs.earnings_history_async())\n```\n\n#### 3. Symbol Search\n\n**Classic symbol search**\n\n Yahoo fincane offers two different symbol search endpoints which are available in yFin in the the function `search` (or its async equivalent `search_async`).\n \nBy using the parameter `search_assist` one can switch between the two endpoints, whereas `search_assist=1` uses the endpoint, which is used in the search bar on [finance.yahoo.com](finance.yahoo.com).\nThe search query can be an asset name, or its symbol. Results are limited to 6 and 10 for `search_assist=1` and `search_assist=2`, respectively.\n\n```python\nfrom yfin.symbols import search\n\nsearch(\"Volkswagen\", search_assist=1) # search_assist=1 is the default\nsearch(\"Volkswagen\", search_assist=2)\n```\n\n**Lookup symbol search**\n\nAdditionally, a lookup endpoint is included in yFin, which can also be used for searching symbols. This endpoints gives up to 10000 results for a search query, but is less accurate than the classic symbol search functions. It is also possible to search for (a) specific asset type(s) and most important, it seems that there isn´t any rate limiting for this endpoint. \n \nTherefore this function is especially useful to get (nearly) all available symbols for (a) specific asset type(s). :-)  This is exactly what I am doing in my other yahoo finance related python module [yahoo symbols](https://github.com/legout/yahoo-symbols).\n\n```python\nfrom yfin.symbols import lookup_search\n\nlookup_search(\"btc\", type_=\"cryptocurrency\")\n```\n\n\n#\n\n## Use of a random proxy server.\n\n**Note** The library should work fine without using random proxies, but the number of requests is limited to ~1000/h. Using random proxies might be illegal.\n\nYou can set `random-proxy=True` in any of the yFin functions. By default this uses free proxies*. In my experience, these proxies are not reliable, but maybe you are lucky.\n\nIt is also possible to provide a list or `proxies` as a parameter in every yFin function. \n\n```python\nfrom yfin import history\nfrom yfin.utils.proxy import get_free_proxy_list\n\ndata = history(\"AAPL\", random_proxy=True)\n\nproxies = [\"http://proxy.one.com\", \"https://proxy.town.com\"]\n# or get free proxies. Note: These proxies are not very reliable\n# proxies = get_free_proxy_list()\n\ndata = history(\"AAPL\", proxies=proxies)\n```\n\n### Webshare.io proxies\n\nI am using proxies from [webshare.io](https://www.webshare.io/). I am very happy with their service and the pricing. If you wanna use their service too, sign up (use the [this link](https://www.webshare.io/?referral_code=upb7xtsy39kl) if you wanna support my work) and choose a plan that fits your needs. In the next step, go to Dashboard -\u003e Proxy -\u003e List -\u003e Download and copy the download link. Set this download link as an environment variable `WEBSHARE_PROXIES_URL`  before importing any yFin function. \n\n*Export WEBSHARE_PROXIES_URL in your linux shell*\n```\n$ export WEBSHARE_PROXIES_URL=\"https://proxy.webshare.io/api/v2/proxy/list/download/abcdefg1234567/-/any/username/direct/-/\"\n```\n\nYou can also set this environment variable permanently in an `.env` file (see the `.env-exmaple`) in your home folder or current folder or in your command line config file (e.g. `~/.bashrc`).\n\n*Write WEBSHARE_PROXIES_URL into .env*\n```\nWEBSHARE_PROXIES_URL=\"https://proxy.webshare.io/api/v2/proxy/list/download/abcdefg1234567/-/any/username/direct/-/\"\n```\n\n*or write WEBSHARE_PROXIES_URL into your shell config file (e.g. ~/.bashrc)*\n```\n$ echo 'export WEBSHARE_PROXIES_URL=\"https://proxy.webshare.io/api/v2/proxy/list/download/abcdefg1234567/-/any/username/direct/-/\"' \u003e\u003e ~/.bashrc\n```\n\nThe last option is to set your `WEBSHARE_PROXIES_URL` within your python code. **Note** It is neccessary to do before importing any other yFin function.\n\n```python\nfrom yfin.utils.proxy import set_webshare_proxies_url\n\nset_webshare_proxies_url(url=\"https://proxy.webshare.io/api/v2/proxy/list/download/abcdefg1234567/-/any/username/direct/-/\")\n```\n\n\n\n*Free Proxies are scraped from here:\n- \"http://www.free-proxy-list.net\"\n- \"https://free-proxy-list.net/anonymous-proxy.html\"\n- \"https://www.us-proxy.org/\"\n- \"https://free-proxy-list.net/uk-proxy.html\"\n- \"https://www.sslproxies.org/\"\n\n\n\u003chr\u003e\n\n#### Support my work :-)\n\nIf you find this useful, you can buy me a coffee. Thanks!\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/W7W0ACJPB)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flegout%2Fyfin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flegout%2Fyfin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flegout%2Fyfin/lists"}