{"id":44049595,"url":"https://github.com/gerritnowald/budget_book","last_synced_at":"2026-02-07T23:05:29.071Z","repository":{"id":133209162,"uuid":"605171769","full_name":"gerritnowald/budget_book","owner":"gerritnowald","description":"Download, ML categorization and analysis of banking transactions (comdirect Finanzmanager replacement)","archived":false,"fork":false,"pushed_at":"2026-02-07T21:10:57.000Z","size":309988,"stargazers_count":47,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-07T21:37:56.460Z","etag":null,"topics":["comdirect-api","finance","machine-learning","python"],"latest_commit_sha":null,"homepage":"https://gerritnowald.wordpress.com/2023/02/23/managing-spending-with-python-pandas/","language":"Jupyter Notebook","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/gerritnowald.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-22T15:45:17.000Z","updated_at":"2026-02-07T19:57:04.000Z","dependencies_parsed_at":"2024-02-15T01:24:57.900Z","dependency_job_id":"44e8d93a-9c86-4567-8778-11201826b631","html_url":"https://github.com/gerritnowald/budget_book","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/gerritnowald/budget_book","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerritnowald%2Fbudget_book","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerritnowald%2Fbudget_book/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerritnowald%2Fbudget_book/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerritnowald%2Fbudget_book/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gerritnowald","download_url":"https://codeload.github.com/gerritnowald/budget_book/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerritnowald%2Fbudget_book/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29211674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T22:58:45.823Z","status":"ssl_error","status_checked_at":"2026-02-07T22:58:45.272Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["comdirect-api","finance","machine-learning","python"],"created_at":"2026-02-07T23:05:28.464Z","updated_at":"2026-02-07T23:05:29.058Z","avatar_url":"https://github.com/gerritnowald.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# introduction\n\n![](https://raw.githubusercontent.com/gerritnowald/budget_book/main/sunburst.webp)\n\nBanking transactions are saved into a csv database and then analyzed for a given timeframe.\n\nTwo scripts are used to manage the banking transactions:\n- `transaction_importer` downloads new transactions using the *comdirect bank* API and appends them to the database. They are categorized based on their description text using Machine Learning.\n- `transaction_editor` is a console user interface to modify transactions, which is faster to use than Excel.  \n\nThe transactions are analyzed in a Jupyter notebook, see this example:  \nhttps://github.com/gerritnowald/budget_book/blob/main/src/analysis.ipynb\n\n# disclaimer\n\nThis is not a professional and easy to use budget planer and requires some programming knowledge and adaptation to cater to your individual needs.\n\n# contents\n\n- [initial setup](#initial-setup)\n  * [transactions database](#transactions-database)\n  * [account balance](#account-balance)\n  * [categorization](#categorization)\n  * [comdirect API](#comdirect-api)\n- [how to use](#how-to-use)\n  * [managing banking transactions](#managing-banking-transactions)\n    + [import \u0026 categorization](#import---categorization)\n    + [console user interface](#console-user-interface)\n  * [spendings report](#spendings-report)\n  * [backup](#backup)\n- [dependencies](#dependencies)\n- [contributions](#contributions)\n- [history](#history)\n- [acknowledgements](#acknowledgements)\n\n\u003csmall\u003e\u003ci\u003e\u003ca href='http://ecotrust-canada.github.io/markdown-toc/'\u003eTable of contents generated with markdown-toc\u003c/a\u003e\u003c/i\u003e\u003c/small\u003e\n\n# initial setup\n\nGeneral settings such as file names \u0026 column names have to be set in `config.ini`.\n\n## transactions database\n\nInitially, transactions (e.g. from the last year) are exported from online banking as a csv file.  \nThese form the database, stored locally on your hard drive.  \nThe minimal required columns are\n- date\n- amount\n- description\n\nAs an example for transactions, see  \nhttps://github.com/gerritnowald/budget_book/blob/main/src/transactions.csv  \n(only placeholder for description text)\n\n## account balance\n\nThe account balance over time has to calculated **once** using\n```\ncalculate_balance FINAL_BALANCE\n```\nFor Windows, the batch script `start_calculate_balance.bat` can be used (the final balance has to be set in the file).\n\n## categorization\n\nThe transactions have to be categorized for detailed analysis.  \nTwo layers of categories can be used, separated with / (e.g. *living expenses/groceries*).  \nThis has to be done manually in the beginning, e.g. using Excel.  \nLater, Machine Learning is used to automatically categorize new transactions.\n\nUse `categorizer_training.ipynb` to train a machine learning model on your transactions with your categories, see also this blog post:  \nhttps://gerritnowald.wordpress.com/2025/12/16/revisiting-categorization-of-banking-transactions/  \nA list of all currently used categories is automatically saved as `categories.csv`.  \nMy current model `categorizer.joblib` is also provided, but it will use my categories.\n\n## comdirect API\n\nFor the API import for the German *comdirect bank*, the user has to [register](https://www.comdirect.de/cms/kontakt-zugaenge-api.html) and insert the credentials into `config_comdirectAPI.json`.\n\n[back to contents](#contents)\n\n\n# how to use\n\n## managing banking transactions\n\nNew transactions are merged to the database \u0026 categorized using two standalone scripts running in batch mode.  \nThey can be used independently or in sequence, the latter by calling `start_transaction_importer.bat`.\n\n### import \u0026 categorization\n\nNew transactions are appended to the database using\n```\ntransaction_importer\n```\nwhich is using the *comdirect bank* API.  \nNew transactions are downloaded based on the last date in the database. Some overlap is considered and removed using a merge to make the import more robust.  \nAlso the balance over time is updated.  \n\nAlternatively, they can also be read from an exported csv file.  \nA code example is provided in `test_import_transactions.ipynb`, which can be adapted in the interactive Jupyter environment.  \nThe final code can then be inserted into the function `def transactions_CSV()` in `transaction_importer.py`.\n\nThe transactions are categorized based on their description text using Machine Learning, see also this blog post:  \nhttps://gerritnowald.wordpress.com/2023/04/05/categorize-banking-transactions-with-machine-learning/  \n\n### console user interface\n\nSince the accuracy of the categoriziation is not perfect, wrong categories should be corrected.  \nFor this, a console user interface is available, which can be run with\n```\ntransaction_editor\n```\nsee also this blog post:  \nhttps://gerritnowald.wordpress.com/2024/02/26/creating-a-command-line-interface-with-python/\n\nIt can also be used to split transactions, e.g. for cash withdrawal at the supermarket.\n\nThe console user interface is automatically run after `transaction_importer`.  \nThe pre-selected line highlights the last previously appended transaction.\n\n## spendings report\n\nThe spendings report can be updated by running `analysis.ipynb`.  \nReports for different time frames can be generated by filtering the database.  \nIt is recommended to export the notebook (e.g. as html or pdf) regularly (e.g. yearly) for later reference.  \nSee also this blog post: https://gerritnowald.wordpress.com/2023/02/23/managing-spending-with-python-pandas/\n\n\n## backup\n\nGit can be used as backup.  \nIf an online repo is used, it is **strongly** recommended to make it private and to exclude `config_comdirectAPI.json`.\n\n[back to contents](#contents)\n\n\n# dependencies\n\n- Pandas\n- plotly (for sunburst diagram)\n- sklearn (for ML categorization)\n- curses (for console user interface)\n\nOn Windows, use `install_dependencies.bat` to install the required packages.\n\n# contributions\n\nContributions are welcome, especially regarding APIs for additional banks.\n\n# history\n\nI started this personal project as the German *comdirect bank* abolished their online budget planer *Finanzmanager*. It aims to reproduce this functionality while being as simple and understandable as possible. In principle this project is applicable to every bank, which allows to export transactions as csv files. I decided to publish this project, since I thought that it might be useful to others.\n\n# acknowledgements\n\nthanks to Philipp Panhey for the comdirect API access:  \nhttps://github.com/phpanhey/comdirect_financialreport  \n\n[back to contents](#contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerritnowald%2Fbudget_book","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgerritnowald%2Fbudget_book","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerritnowald%2Fbudget_book/lists"}