Reaching Budget Calendar through its synced .bgt file

Everything Budget Calendar tracks for a user — every planned payment, every recurring rule, the running balance the app reconciles to a real one — lives in a single file the app writes and keeps in sync through that user's own Google Drive. No bank login sits behind it. That one fact decides the whole integration: the records are reachable the moment a user agrees to share their own file, and the engineering work is reading the container cleanly rather than negotiating a connection.

The route is plain. Pull the synced file from the user's Drive under their consent, decode it into typed records, and hand back a normalized API plus the source that produces it. The Windows and Mac desktop editions, sold separately, share the format, so one parser covers every place a user's data can sit.

On a real engagement we build the Drive-retrieval path and treat a file the user hands over directly as the same parser without the network hop. The Excel export is kept as a low-effort option for teams that only want the monthly roll-up.

What a .bgt file actually holds

The file is small but well structured. These are the domains worth pulling, named the way the app itself presents them in its documentation.

Pulling the file and reading a record

Retrieval is one Drive call against the user's own account, scoped to the file the app created. The parse step carries the real work; the container layout is confirmed against a consenting account during the build, never guessed. A sketch of both halves:

# Illustrative. Drive retrieval + container parse.
# OAuth scope, field offsets and layout are confirmed
# against a consenting account during the build.

from googleapiclient.discovery import build  # user-consented OAuth

def fetch_budget_file(creds):
    drive = build("drive", "v3", credentials=creds)
    # The app writes the data file into the user's own Drive,
    # so query the app-created file, newest first.
    q = "name contains '.bgt' and trashed = false"
    res = drive.files().list(
        q=q, orderBy="modifiedTime desc",
        fields="files(id,name,modifiedTime)").execute()
    files = res.get("files", [])
    if not files:
        # Expected before the user has synced once from the app.
        raise NoSyncedFileYet("ask the user to sync from the app")
    blob = drive.files().get_media(fileId=files[0]["id"]).execute()
    return parse_bgt(blob)

def parse_bgt(blob):
    # Container = balance header + transaction records
    # + recurrence rules. Field map fixed per build.
    book = decode_container(blob)
    return {
      "balance": book.header.adjusted_balance,
      "transactions": [
        {"date": t.date, "amount": t.signed_amount,
         "category": t.category, "icon": t.icon, "note": t.note}
        for t in book.transactions],
      "recurring": [
        {"every": r.interval, "nth_weekday": r.nth_weekday,
         "start": r.start, "end": r.end or None}
        for r in book.rules],
    }

The "no synced file yet" path matters in practice — the data file is created by the app itself, so a fresh user account simply has nothing in Drive until they sync once. We treat that as a normal state, not an error to the caller.

A neutral shape for ledgers and planners

The records normalize to a small, source-agnostic shape, so a downstream personal-finance tool or accounting integration does not care that the origin was a calendar app.

// transaction (normalized) — illustrative values
{ "id": "txn_2026_05_18_01",
  "date": "2026-05-18",
  "amount": -84.20,
  "currency": "CAD",
  "category": "Utilities",
  "label": "Hydro",
  "source": "budget-calendar:bgt" }

// recurring_rule (normalized) — illustrative values
{ "rule_id": "rr_009",
  "interval": "monthly",
  "nth_weekday": "2nd Friday",
  "amount": -1450.00,
  "starts": "2025-09-12",
  "ends": null }

Three authorized ways to reach the data

1 — User-consented Google Drive retrieval

The user grants read consent to the Drive account holding their synced file; we pull it and parse it. The whole dataset is reachable because the file is the whole dataset. Effort sits in the parser; durability is high while the format holds, and we guard that with a layout fingerprint. The Drive consent app and onboarding are arranged with the client while we build, against a consenting account.

2 — Direct file hand-off

Same parser, no Drive hop. The user exports or shares a copy of the file once and we read it. Reachable data and durability are identical to route one; setup is lighter, which suits one-shot imports or a closed environment.

3 — Desktop Excel export

The Windows and Mac editions generate Excel reports of the monthly statistics. For teams that only need aggregated figures, reading those workbooks is the cheapest path. It gives the report view rather than raw records, and it tracks the report layout instead of the container.

For most builds we ship route one and fold route two into it, so a customer can feed the integration either a live sync or a handed-over copy from the same code. The Excel path is offered only where raw fidelity is not needed.

What ships at the end

• An OpenAPI specification for the normalized endpoints — transactions, recurring rules, balance, categories.
• A runnable .bgt reader in Python or Node.js, including the Drive retrieval and the recurrence expander.
• A protocol and auth-flow report: the Drive OAuth scope chain and the container layout as mapped during the build.
• Automated tests covering recurrence boundaries (month-end, Nth-weekday, indefinite series) and the no-synced-file path.
• Interface documentation plus consent and data-retention guidance for handling a user's financial file.

What we plan around on this build

A few specifics shape how we scope the work, and we handle each of them on our side.

• The data file is created and owned by the app, then mirrored into the user's Drive. We key retrieval to the user's Drive consent and the app-created file, and design the caller so a not-yet-synced account is a defined state rather than a failure.
• Mobile and desktop share one format, but the desktop edition adds image embedding and Excel report generation. We map a single canonical schema that holds for both, so a customer on either edition gets the same API surface.
• "Nth weekday of a month" and indefinite recurrence need a deterministic expander. We build and test it against month-end, leap years and long horizons so a downstream ledger does not drift over time.
• The on-disk layout can change between app versions — the listing shows a mid-2025 update. We attach a schema fingerprint and a re-validation pass so a format change is caught and patched, not silently absorbed into bad output.

Consent and the Canadian privacy frame

This is one person's own financial planning file, reached with that person's consent — not institution-held data pulled over a banking rail. In Canada the governing regime is PIPEDA. Bill C-15 added a personal-information mobility right to PIPEDA, but it operates through sector-specific frameworks that do not yet designate a budgeting app, and Canada's consumer-driven banking framework is aimed at data held by banks, not a manual planner. The practical, available route today is user-consented access to the user's own file. We work that way by default: only the records the customer needs are extracted, access is logged, consent is recorded, and an NDA is in place where the engagement calls for one.

Screens from the app

Store screenshots, for interface reference. Select one to enlarge.

How this brief was built

Put together in May 2026 from the developer's own documentation and store listing, plus current Canadian privacy commentary. I read the MiShell Budget Calendar product page and its Google Drive sharing notes for how the data file is created and synced, the Google Play listing for category, platforms and the mid-2025 update, and recent legal analysis of the PIPEDA mobility amendment to confirm which regime actually governs a manual planner's data. The .bgt extension is described in the developer's sync notes and third-party listings rather than asserted here as a fixed internal layout; field offsets are confirmed against a consenting account during the build.

Sources opened: Google Play listing, MiShell product documentation, Google Drive sharing notes, McCarthy Tétrault on the PIPEDA mobility amendment.

Mapped by the OpenBanking Studio integration desk — May 2026

Other calendar and planner apps in scope

Same category, sketched so you can see where a unified integration would sit. Named for context, not ranked.

• CalendarBudget — a calendar-first planner that connects bank accounts and projects cash flow forward, so its records are server-held rather than file-based.
• PocketSmith — calendar budgeting with long-range forecasting and connected accounts; holds projected balances and categorized history per user.
• Dollarbird — a shared calendar ledger of planned and logged transactions, stored against an account.
• Cash Flow Calendar — aimed at variable income, plotting income and recurring bills on a calendar timeline.
• YNAB — zero-based budgeting with assigned dollars, account links and a categorized transaction history.
• Goodbudget — envelope budgeting with per-envelope allocations and a retained spending history.
• PocketGuard — connected-account tracking that isolates spendable cash after bills and goals.
• Monarch Money — aggregated accounts, budgets and net-worth tracking held server-side.
• Rocket Money — a bills-and-subscriptions calendar over connected accounts, with recurring-charge detection.

Questions integrators ask about Budget Calendar

Where does Budget Calendar keep the data you would integrate?

In one file the app writes and keeps in sync through the user's own Google Drive. The Windows and Mac desktop editions, sold separately, read the same format, so a single parser covers every copy of a user's data.

Can you handle recurring rules like 'every 2nd Friday of the month'?

Yes. The recurrence model, including Nth-weekday-of-month, fixed end dates and indefinite series, is expanded deterministically into a dated ledger and tested against month-end and year boundary cases.

Does Canada's consumer-driven banking framework apply to this integration?

No. That framework covers data held by banks and similar institutions. Budget Calendar is a manual planner with no bank connection, so the data is reached as the user's own file under their consent, governed by PIPEDA rather than an open-banking scheme.

What happens to the integration if the file layout changes in an update?

We fingerprint the container layout and ship a re-validation step, so a format change between app versions is detected and patched instead of silently corrupting output. Maintenance to track that drift is part of how we scope the build.

Working with us

A runnable .bgt reader and its OpenAPI spec is the usual handoff here, inside a one-to-two-week cycle. You can take that as delivered source code, from $300, billed only after delivery once the integration does what you asked — or skip the code and call our hosted endpoints instead, paying per call with nothing upfront. Either way you bring the app name and what you need from the data; the Drive consent app, access and the compliance details are arranged with you while we build. Start the conversation at /contact.html.