API Documentation

This document describes the HTTP API provided by the app.py Bottle service.

All endpoints return JSON and are designed for efficient database queries.

Base URL

http://localhost:8080/

Authentication

Currently, the API does not require authentication. (Planned: optional API keys or JWT tokens.)

Banks Endpoint

GET /banks

Return a list of all unique banks found in the transaction table.

URL

GET /banks

Response Example

{
    "banks": ["abn", "ing", "revolut"]
}

Monthly Transactions

GET /transactions/month

Return transactions from the previous month.

Supports filtering by a specific bank.

URL

GET /transactions/month?bank=<bank>

Query Parameters

bank (optional): bank name or “all”

Response Example

{
    "bank": "revolut",
    "start": "2024-12-01",
    "end": "2024-12-31",
    "data": [
        {
            "id": 28310,
            "bank": "revolut",
            "date": "2019-05-23",
            "description": "To EUR Coffee Beans",
            "amount": 0.5,
            "currency": "EUR"
        }
    ]
}

Yearly Transactions

GET /transactions/year

Returns transactions for the previous calendar year.

URL

GET /transactions/year?bank=<bank>

Query Parameters

bank (optional): specific bank or “all”

Response Example

{
    "bank": "all",
    "start": "2023-01-01",
    "end": "2023-12-31",
    "data": ["..."]
}

Daily Transactions

GET /transactions/day

Returns transactions for the last 24 hours.

Supports filtering by bank.

URL

GET /transactions/day?bank=<bank>

Custom Date Range

GET /transactions/range

Return transactions for any custom date period.

URL

GET /transactions/range?start=YYYY-MM-DD&end=YYYY-MM-DD&bank=<bank>

Query Parameters

start (required): start date
end (required): end date
bank (optional): specific bank or “all”

Error Example

{ "error": "Missing 'start' or 'end' query parameter" }

Totals Endpoint

GET /totals

Returns total spending aggregated by bank.

URL

GET /totals?bank=<bank>

Response Example

[
    {
        "bank": "abn",
        "total_amount": -14320.44
    }
]

Category Statistics (Enriched Data)

GET /stats/categories

Requires the enriched table to exist.

URL

GET /stats/categories

Response Example

[
    {
        "category": "groceries",
        "count": 45,
        "total_spent": -560.22
    }
]