BAC Statement Tools

Tools for processing BAC Costa Rica credit card statement PDFs.

Dependencies

• Python 3.10+
• pdfplumber (>=0.10.0)
• matplotlib (>=3.5.0) - optional, for graphs

Extraction

Extract transactions from statement PDFs to JSON.

python bac_extract.py <pdf_file> [options]

Options:

• -o, --output: Output JSON path (default: transactions.json)
• --pretty: Pretty-print JSON output
• -v, --verbose: Enable debug logging

Examples:

python bac_extract.py statement.pdf --pretty
python bac_extract.py statement.pdf -o output.json -v

Analysis

Analyze extracted transactions with category breakdowns and graphs.

python bac_analyze.py <json_files...> [options]

Options:

• --graph {bar,pie,timeline,all}: Generate graph(s)
• -o, --output: Output file for graph (default: spending_.png)
• --show: Display graph interactively
• --categories: Custom categories file (default: categories.json)

Examples:

# Text summary
python bac_analyze.py transactions.json

# Analyze multiple statements
python bac_analyze.py *.json

# Generate all graphs
python bac_analyze.py *.json --graph all

# Generate bar chart with custom output
python bac_analyze.py *.json --graph bar -o spending.png

# Use custom categories
python bac_analyze.py *.json --categories my_categories.json

Categories

Create a categories.json file to customize spending categories. Each category maps to a list of merchant name patterns (case-insensitive substring match).

{
  "Groceries": ["SUPERMARKET", "WALMART", "FRESH MARKET"],
  "Gas": ["SERVICENTRO", "DELTA", "SHELL"],
  "Restaurants": ["RESTAURANT", "CAFE", "PIZZA", "SUSHI"],
  "Transportation": ["UBER", "TAXI", "PARKING"],
  "Entertainment": ["CINEMA", "NETFLIX", "STEAM"],
  "Utilities": ["ELECTRIC", "WATER", "INTERNET"],
  "Subscriptions": ["SPOTIFY", "YOUTUBE", "CHATGPT"]
}

Transactions not matching any pattern are categorized as "Other".

Output Format

{
  "metadata": {
    "source_file": "statement.pdf",
    "extraction_date": "2025-01-15T12:00:00Z",
    "statement_date": "2025-01-10",
    "total_transactions": 5
  },
  "card_holders": [
    {
      "card_suffix": "1234",
      "name": "CARD HOLDER NAME"
    }
  ],
  "purchases": [
    {
      "reference": "123456789012",
      "date": "2025-01-09",
      "description": "EXAMPLE STORE",
      "location": null,
      "currency": "CRC",
      "amount_crc": 1234.56,
      "amount_usd": null
    }
  ],
  "other_charges": [],
  "voluntary_services": [],
  "summary": {
    "purchases": { "total_crc": 50000.00, "total_usd": 0.00, "count": 5 },
    "other_charges": { "total_crc": 0.00, "total_usd": 0.00, "count": 0 },
    "voluntary_services": { "total_crc": 0.00, "total_usd": 0.00, "count": 0 }
  }
}