Method

period.dates

The first and last days of the accounting period containing today or a given date.

Gives the first and last day of the accounting period containing a date, by default today (the local date of the session's clock, or of the server's with no book open). start, end and fiscalYearEnd override the configured bounds for this call only. startTime and endTime are the instants GnuCash uses: local 00:00:00 of the first day and 23:59:59 of the last. Use it to work out the dates to pass to a report or to transaction.list.

A fiscal year starts the day after the fiscal year end of the previous year, so with a year ending 31 March, 15 July 2024 falls in 2024-04-01 to 2025-03-31.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash, at 2024-07-15T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"period.dates","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "today": "2024-07-15",
    "start": "2024-01-01",
    "end": "2024-12-31",
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-12-31T23:59:59Z"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"period.dates","params":{"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "start": "2024-04-01",
    "end": "2025-03-31",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"period.dates","params":{"date":"2024-02-15","start":"previous-quarter","end":"previous-quarter"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "start": "2023-10-01",
    "end": "2023-12-31",
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
period.dates {}
period.dates {"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}
period.dates {"date":"2024-02-15","start":"previous-quarter","end":"previous-quarter"}
EOF

It prints:

[
  {
    "today": "2024-07-15",
    "start": "2024-01-01",
    "end": "2024-12-31",
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-12-31T23:59:59Z"
  },
  {
    "start": "2024-04-01",
    "end": "2025-03-31",
    "…": "…"
  },
  {
    "start": "2023-10-01",
    "end": "2023-12-31",
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"period.dates","arguments":{}}

Result:

{
  "structuredContent": {
    "today": "2024-07-15",
    "start": "2024-01-01",
    "end": "2024-12-31",
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-12-31T23:59:59Z"
  }
}

Tool call:

{"name":"period.dates","arguments":{"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}}

Result:

{
  "structuredContent": {
    "start": "2024-04-01",
    "end": "2025-03-31",
    "…": "…"
  }
}

Tool call:

{"name":"period.dates","arguments":{"date":"2024-02-15","start":"previous-quarter","end":"previous-quarter"}}

Result:

{
  "structuredContent": {
    "start": "2023-10-01",
    "end": "2023-12-31",
    "…": "…"
  }
}

It needs no book; today is then the server's:

Example: with no book, at 2024-11-20T09:30:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"period.dates","params":{"start":"quarter","end":"quarter"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "today": "2024-11-20",
    "start": "2024-10-01",
    "end": "2024-12-31",
    "startTime": "2024-10-01T00:00:00Z",
    "endTime": "2024-12-31T23:59:59Z"
  }
}

Command line

red-ale exec period.dates '{"start":"quarter","end":"quarter"}'

It prints:

{
  "today": "2024-11-20",
  "start": "2024-10-01",
  "end": "2024-12-31",
  "startTime": "2024-10-01T00:00:00Z",
  "endTime": "2024-12-31T23:59:59Z"
}

MCP tool call

Tool call:

{"name":"period.dates","arguments":{"start":"quarter","end":"quarter"}}

Result:

{
  "structuredContent": {
    "today": "2024-11-20",
    "start": "2024-10-01",
    "end": "2024-12-31",
    "startTime": "2024-10-01T00:00:00Z",
    "endTime": "2024-12-31T23:59:59Z"
  }
}

Effect: read.

Params

Params of period.dates. The optional fields override the configured setting for this call only.

  • date (Date or null): The day the period must contain; by default today in the local time zone.
  • start (string or null): Start, instead of the configured one.
  • end (string or null): End, instead of the configured one.
  • fiscalYearEnd (string or null): Fiscal year end, MM-DD, instead of the configured one.

Result

The result of period.dates.

  • today (Date, required): The day used as today.
  • start (Date, required): First day of the period (GnuCash starts it at 00:00:00 local time).
  • end (Date, required): Last day of the period (GnuCash ends it at 23:59:59 local time).
  • startTime (Timestamp, required): The period's first instant: local 00:00:00 on start.
  • endTime (Timestamp, required): The period's last instant: local 23:59:59 on end.