Skip to content

Commit fd20137

Browse files
JSONboredJSONbored
committed
Exports Splitwise data and receipts to spreadsheet
Adds functionality to authenticate with the Splitwise API, fetch expenses, download receipts, and export the data to a spreadsheet (CSV or XLSX). Implements a CLI interface with options for output file, receipts directory, group filtering, and date range filtering. Includes comprehensive documentation in README.md and dependency management via requirements files.
1 parent f2cffa9 commit fd20137

5 files changed

Lines changed: 455 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
env/
12+
build/
13+
develop-eggs/
14+
dist/
15+
downloads/
16+
eggs/
17+
.eggs/
18+
lib/
19+
lib64/
20+
parts/
21+
sdist/
22+
var/
23+
*.egg-info/
24+
.installed.cfg
25+
*.egg
26+
27+
# Virtual environments
28+
.venv/
29+
venv/
30+
ENV/
31+
32+
# PyInstaller
33+
*.manifest
34+
*.spec
35+
36+
# Installer logs
37+
debug.log
38+
pip-log.txt
39+
pip-delete-this-directory.txt
40+
41+
# Unit test / coverage reports
42+
htmlcov/
43+
.tox/
44+
.nox/
45+
.coverage
46+
.coverage.*
47+
.cache
48+
nosetests.xml
49+
coverage.xml
50+
*.cover
51+
.hypothesis/
52+
.pytest_cache/
53+
54+
# Jupyter Notebook
55+
.ipynb_checkpoints
56+
57+
# pyenv
58+
.python-version
59+
60+
# pipenv
61+
Pipfile.lock
62+
63+
# mypy
64+
.mypy_cache/
65+
.dmypy.json
66+
67+
# VS Code
68+
.vscode/
69+
70+
# macOS
71+
.DS_Store
72+
.AppleDouble
73+
.LSOverride
74+
75+
# Thumbnails
76+
._*
77+
78+
# Files that might appear on external disks
79+
.Spotlight-V100
80+
.Trashes
81+
82+
# Editor directories and files
83+
.idea/
84+
*.sublime-workspace
85+
*.sublime-project
86+
87+
# Receipts and exports
88+
downloads/
89+
receipts/
90+
*.csv
91+
*.xlsx
92+
93+
# Taskmaster/AI/IDE
94+
.cursor/
95+
96+
# Auth and config
97+
splitwise_auth.json
98+
*.lock
99+
100+
# Logs
101+
*.log
102+
103+
# System files
104+
Thumbs.db
105+
Desktop.ini
106+
107+
# Ignore requirements-lock.txt if you want to keep it local only
108+
# requirements-lock.txt

‎README.md‎

Lines changed: 124 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,124 @@
1-
# splitwise-export-receipts
1+
# Splitwise Export Receipts
2+
3+
A user-friendly tool to export all your Splitwise transaction data—including any/all receipts—into a single spreadsheet (CSV/XLSX). Designed for both technical and non-technical users.
4+
5+
## Features
6+
- Export all expenses (optionally by group/date)
7+
- Download and link all available receipts
8+
- Output a single spreadsheet with all relevant data and clickable receipt links
9+
- Easy-to-use CLI
10+
- Cross-platform (Windows, Mac, Linux)
11+
12+
## 🚨 Splitwise API Setup (Required Before First Use)
13+
14+
> **Note**
15+
> You must create a Splitwise app to obtain your API keys before using this tool. This is a one-time setup required by Splitwise for all third-party tools.
16+
>
17+
> **Steps:**
18+
> 1. Go to [https://secure.splitwise.com/apps/new](https://secure.splitwise.com/apps/new) and create a new app.
19+
> 2. Set the callback URL to anything (e.g., `http://localhost:8080`).
20+
> 3. After creating the app, copy your **Consumer Key** and **Consumer Secret**.
21+
> 4. When you run this tool for the first time, you will be prompted to enter these keys and complete the authorization process in your browser.
22+
> 5. Your credentials will be saved securely in `~/.splitwise_auth.json` for future use.
23+
24+
## ⚡ How to Use (Step-by-Step Flow)
25+
26+
1. **Install dependencies** (in a virtual environment):
27+
```bash
28+
python3 -m venv .venv
29+
source .venv/bin/activate
30+
python -m pip install --upgrade pip
31+
python3 -m pip install -r requirements-lock.txt
32+
```
33+
> **Note:**
34+
> - For reproducible installs, use `requirements-lock.txt` (recommended for most users).
35+
> - `requirements.txt` contains version ranges and is intended for development or as a reference.
36+
2. **Run the tool:**
37+
```bash
38+
python src/splitwise_export_receipts.py
39+
```
40+
3. **Authenticate with Splitwise:**
41+
- Enter your Consumer Key and Secret when prompted.
42+
- Open the provided authorization URL in your browser.
43+
- **After authorizing, you will see a browser error (page not found).**
44+
45+
> **Important: Getting the OAuth Verifier**
46+
> - This is expected! Splitwise will redirect you to your callback URL (e.g., `http://localhost:8080`) and the page will not load.
47+
> - **Look at the URL in your browser's address bar.**
48+
> - Find the part that says `oauth_verifier=...` and copy the value after the `=`.
49+
> - Paste this value into the terminal when prompted for the verification code.
50+
51+
> _Example:_
52+
> ```
53+
> http://localhost:8080/?oauth_token=...&oauth_verifier=YOUR_CODE_HERE
54+
> ```
55+
> Copy `YOUR_CODE_HERE` and paste it into the script prompt.
56+
57+
4. **Choose output options:**
58+
- The script will prompt you for the output file path (default: `splitwise_export.csv`).
59+
- You can choose `.csv` (recommended) or `.xlsx`.
60+
- You can also specify the receipts directory (default: `receipts`).
61+
62+
5. **Open your exported spreadsheet:**
63+
- For CSV: Open in Excel or Google Sheets. The `Receipt` column contains a clickable link for each transaction with a receipt. Click "View Receipt" to open the local file (if it exists on your machine).
64+
- For XLSX: The `Receipt` column contains the local file path.
65+
66+
6. **Receipts are saved in the specified directory.**
67+
68+
## 📂 Specifying Output Locations
69+
70+
You can control where the spreadsheet and receipts are saved using command-line options:
71+
72+
- **Spreadsheet output file:**
73+
- Use `--output` (or `-o`) to set the spreadsheet file path:
74+
```bash
75+
python src/splitwise_export_receipts.py --output /path/to/your/spreadsheet.csv
76+
```
77+
- Example:
78+
```bash
79+
python src/splitwise_export_receipts.py --output ~/Desktop/splitwise_export.csv
80+
```
81+
82+
- **Receipts directory:**
83+
- Use `--receipts-dir` to set the receipts folder:
84+
```bash
85+
python src/splitwise_export_receipts.py --receipts-dir /path/to/receipts_folder
86+
```
87+
- Example:
88+
```bash
89+
python src/splitwise_export_receipts.py --receipts-dir ~/Desktop/splitwise_receipts
90+
```
91+
92+
- **Combine both:**
93+
```bash
94+
python src/splitwise_export_receipts.py --output ~/Desktop/splitwise_export.csv --receipts-dir ~/Desktop/splitwise_receipts
95+
```
96+
97+
- **If you don't specify these options:**
98+
- The script will prompt you for the output file path (default: `splitwise_export.csv` in the current directory).
99+
- Receipts will be saved in the `receipts` folder in your current directory by default.
100+
101+
- **See all options:**
102+
```bash
103+
python src/splitwise_export_receipts.py --help
104+
```
105+
106+
## Troubleshooting
107+
- If you see a browser error after authorizing Splitwise, this is normal. Just copy the `oauth_verifier` from the URL as described above.
108+
- If you get a `ModuleNotFoundError`, make sure you installed all dependencies in your virtual environment.
109+
- If the receipt links do not work, make sure the receipt files are present at the specified paths on your computer.
110+
111+
## Requirements
112+
- Python 3.10+
113+
- Splitwise account (you will need to create an API app for OAuth)
114+
115+
## Roadmap
116+
- [x] Splitwise API authentication
117+
- [x] Expense fetching
118+
- [x] Receipt downloading
119+
- [x] Data export to spreadsheet
120+
- [x] CLI improvements
121+
- [x] Documentation
122+
123+
## License
124+
MIT

‎requirements-lock.txt‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
certifi==2025.6.15
2+
charset-normalizer==3.4.2
3+
click==8.2.1
4+
et_xmlfile==2.0.0
5+
idna==3.10
6+
numpy==2.3.0
7+
oauthlib==3.2.2
8+
openpyxl==3.1.5
9+
pandas==2.3.0
10+
python-dateutil==2.9.0.post0
11+
pytz==2025.2
12+
requests==2.32.4
13+
requests-oauthlib==1.3.1
14+
six==1.17.0
15+
splitwise==3.0.0
16+
tzdata==2025.2
17+
urllib3==2.4.0

‎requirements.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Requires Python 3.10+
2+
splitwise>=3.0.0
3+
pandas>=1.0.0
4+
requests>=2.0.0
5+
openpyxl>=3.0.0
6+
click>=8.0.0

0 commit comments

Comments
 (0)