{"id":22111305,"url":"https://github.com/simfin/simfin","last_synced_at":"2025-04-13T11:48:25.603Z","repository":{"id":41243264,"uuid":"210851653","full_name":"SimFin/simfin","owner":"SimFin","description":"Simple financial data for Python","archived":false,"fork":false,"pushed_at":"2024-04-03T11:30:13.000Z","size":418,"stargazers_count":306,"open_issues_count":9,"forks_count":41,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-04T05:51:13.692Z","etag":null,"topics":["finance","financial-data","python","simfin"],"latest_commit_sha":null,"homepage":"https://simfin.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SimFin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2019-09-25T13:25:42.000Z","updated_at":"2024-12-31T04:45:00.000Z","dependencies_parsed_at":"2024-06-18T22:48:26.156Z","dependency_job_id":"8e0d2699-f21b-4ddd-a7cd-68c04335eb0e","html_url":"https://github.com/SimFin/simfin","commit_stats":{"total_commits":203,"total_committers":6,"mean_commits":"33.833333333333336","dds":"0.19704433497536944","last_synced_commit":"b17dd571c27282ef7e19c590d2b938ffe12f7124"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimFin%2Fsimfin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimFin%2Fsimfin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimFin%2Fsimfin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimFin%2Fsimfin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SimFin","download_url":"https://codeload.github.com/SimFin/simfin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248710412,"owners_count":21149186,"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","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":["finance","financial-data","python","simfin"],"created_at":"2024-12-01T10:38:24.857Z","updated_at":"2025-04-13T11:48:25.579Z","avatar_url":"https://github.com/SimFin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![docs](https://readthedocs.org/projects/simfin/badge/?version=latest)](https://simfin.readthedocs.io/)\n[![downloads](https://img.shields.io/pypi/dm/simfin.svg)](https://pypistats.org/packages/simfin)\n\n\n# SimFin - Simple financial data for Python\n\nSimFin makes it easy to obtain and use financial and stock-market data in\nPython. It automatically downloads share-prices and fundamental data from\nthe [SimFin](https://www.simfin.com/) server, saves the data to disk for\nfuture use, and loads the data into Pandas DataFrames.\n\n## Installation\n\n    pip install simfin\n    \nMore detailed installation instructions can be found [below](https://github.com/SimFin/simfin#installation-detailed-instructions).\n\n## API-Key\n\nTo download data from SimFin you need an API-key, you can get one for free by registering on [simfin.com](https://simfin.com/login). Once you registered, you can find your API-key [here](https://simfin.com/data/api).\nThe free datasets contain less data than the paid [SimFin+](https://simfin.com/simfin-plus) datasets and some datasets are only available to [SimFin+](https://simfin.com/simfin-plus) users.\nVisit [SimFin](https://simfin.com/data/bulk) for a comparison of the free and paid data versions.\n\n## Example\n\nOnce the simfin package has been installed and you got your API-key, the following Python\nprogram will automatically download all Income Statements for US companies,\nand print the Revenue and Net Income for Microsoft.\n\n    import simfin as sf\n    from simfin.names import *\n\n    # Set your API-key for downloading data.\n    # Replace YOUR_API_KEY with your actual API-key.\n    sf.set_api_key('YOUR_API_KEY')\n\n    # Set the local directory where data-files are stored.\n    # The dir will be created if it does not already exist.\n    sf.set_data_dir('~/simfin_data/')\n\n    # Load the annual Income Statements for all companies in the US.\n    # The data is automatically downloaded if you don't have it already.\n    df = sf.load_income(variant='annual', market='us')\n\n    # Print all Revenue and Net Income for Microsoft (ticker MSFT).\n    print(df.loc['MSFT', [REVENUE, NET_INCOME]])\n\nThis produces the following output:\n\n                      Revenue   Net Income\n    Report Date\n    2008-06-30   6.042000e+10  17681000000\n    2009-06-30   5.843700e+10  14569000000\n    2010-06-30   6.248400e+10  18760000000\n    2011-06-30   6.994300e+10  23150000000\n    2012-06-30   7.372300e+10  16978000000\n    2013-06-30   7.784900e+10  21863000000\n    2014-06-30   8.683300e+10  22074000000\n    2015-06-30   9.358000e+10  12193000000\n    2016-06-30   9.115400e+10  20539000000\n    2017-06-30   9.657100e+10  25489000000\n    2018-06-30   1.103600e+11  16571000000\n    2019-06-30   1.258430e+11  39240000000\n\nWe can also load the daily share-prices and plot the closing share-price for\nMicrosoft (ticker MSFT):\n\n    # Load daily share-prices for all companies in USA.\n    # The data is automatically downloaded if you don't have it already.\n    df_prices = sf.load_shareprices(market='us', variant='daily')\n    \n    # Plot the closing share-prices for ticker MSFT.\n    df_prices.loc['MSFT', CLOSE].plot(grid=True, figsize=(20,10), title='MSFT Close')\n\nThis produces the following image:\n\n![Share-price for MSFT](images/shareprice_MSFT.png)\n\n\n## Documentation\n\n-   [Tutorials](https://www.github.com/simfin/simfin-tutorials/) with\n    detailed examples.\n-   [Datasets](https://simfin.com/data/bulk) that are available.\n-   [Docs](https://simfin.readthedocs.io/en/latest/) for the\n    Python API.\n\n\n## Installation (Detailed Instructions)\n\nThe best way to install simfin and use it in your own project, is to\nuse a virtual environment. You write the following in a Linux terminal:\n\n    virtualenv simfin-env\n\nYou can also use Anaconda instead of a virtualenv:\n\n    conda create --name simfin-env python=3\n\nThen you can install the simfin package inside that virtual environment:\n\n    source activate simfin-env\n    pip install simfin\n\nIf the last command fails, or if you want to install the latest development\nversion from this GitHub repository, then you can run the following instead:\n\n    pip install git+https://github.com/simfin/simfin.git\n\nNow try and put the above example in a file called `test.py` and run:\n\n    python test.py\n\nWhen you are done working on the project you can deactivate the virtualenv:\n\n    source deactivate\n\n\n## Development\n\nIf you want to modify your own version of the simfin package, then you\nshould clone the GitHub repository to your local disk, using this command\nin a terminal:\n\n    git clone https://github.com/simfin/simfin.git\n\nThis will create a directory named simfin on your disk. Then you need to\ncreate a new virtual environment, where you install your local copy of\nthe simfin package using these commands:\n\n    conda create --name simfin-dev python=3\n    source activate simfin-dev\n    cd simfin\n    pip install --editable .\n\nYou should now be able to edit the files inside the simfin directory and\nuse them whenever you have a Python module that imports the simfin package,\nwhile you have the virtual environment `simfin-dev` active.\n\n\n## Testing\n\nTwo kinds of tests are provided with the simfin package:\n\n\n### Unit Tests\n\nUnit-tests ensure the various functions of the simfin package can\nrun without raising exceptions. The unit-tests generally do not test\nwhether the data is valid. These tests are mainly used by developers\nwhen they make changes to the simfin package.\n\nThe unit-tests are run with the following commands from the root directory\nof the simfin package:\n\n    source activate simfin-env\n    pytest\n\n\n### Data Tests\n\nData-tests ensure the bulk-data downloaded from the SimFin servers\nis valid. These tests are mainly used by SimFin's database admin to\nensure the data is always valid, but the end-user may also run these\ntests to ensure the downloaded data is valid.\n\nFirst you need to install [nbval](https://pypi.org/project/nbval/),\nwhich enables support for Jupyter Notebooks in the pytest framework.\nThis is not automatically installed with the simfin package, so as\nto keep the number of dependencies minimal for normal users of simfin.\nTo install nbval run the following commands:\n\n    source activate simfin-env\n    pip install nbval\n\nThen you can run the following commands from the root directory of the\nsimfin package to execute both the unit-tests and data-tests:\n\n    pytest --nbval-lax\n\nThe following command only runs the data-tests:\n\n    pytest --nbval-lax -v tests/test_bulk_data.ipynb\n\n\n### More Tests\n\nThe [tutorials](https://www.github.com/simfin/simfin-tutorials/)\nprovide more realistic use-cases of the simfin package, and they can\nalso be run and tested automatically using `pytest`. See the tutorials'\nREADME for details.\n\n\n## Credits\n\nThe database is created by [SimFin](https://www.simfin.com/).\nThe Python API and download system was originally designed and\nimplemented by [Hvass Labs](https://www.github.com/Hvass-Labs/).\nFurther development of the Python API by SimFin and the community.\n\n\n## License (MIT)\n\nThis is published under the\n[MIT License](https://github.com/simfin/simfin/blob/master/LICENSE.txt)\nwhich allows very broad use for both academic and commercial purposes.\n\nYou are very welcome to modify and use this source-code in your own project.\nPlease keep a link to the [original repository](https://github.com/simfin/simfin).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimfin%2Fsimfin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimfin%2Fsimfin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimfin%2Fsimfin/lists"}