price.nearest

The price of a commodity in a currency nearest to a time, before it, or on its day.

Gives the price of a commodity in a currency nearest to a date or time, in both directions. mode is nearest (the default: the closer of the newest price at or before and the oldest after, a tie going to the older), before (the newest at or before) or sameDay. GnuCash has no "nearest after", and neither does red-ale. Conversions at a past date, such as a foreign-currency transfer, use this.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"price.nearest","params":{"commodity":"GBP","currency":"USD","date":"2000-01-20"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "price": {
      "guid": "e0000000000000000000000000000000",
      "date": "2000-01-15",
      "…": "…"
    },
    "reversed": true,
    "rate": {
      "num": "7",
      "denom": "5"
    }
  }
}

Command line

red-ale exec --book book.gnucash price.nearest '{"commodity":"GBP","currency":"USD","date":"2000-01-20"}'

It prints:

{
  "price": {
    "guid": "e0000000000000000000000000000000",
    "date": "2000-01-15",
    "…": "…"
  },
  "reversed": true,
  "rate": {
    "num": "7",
    "denom": "5"
  }
}

MCP tool call

Tool call:

{"name":"price.nearest","arguments":{"commodity":"GBP","currency":"USD","date":"2000-01-20"}}

Result:

{
  "structuredContent": {
    "price": {
      "guid": "e0000000000000000000000000000000",
      "date": "2000-01-15",
      "…": "…"
    },
    "reversed": true,
    "rate": {
      "num": "7",
      "denom": "5"
    }
  }
}

Effect: read.

Params

Params of price.nearest.

commodity (CommodityId, required): The commodity priced.
currency (CommodityId, required): The currency wanted.
date (Date or null): A day, meaning its neutral time (10:59 UTC from UTC−10 to UTC+13). Give this or time.
time (Timestamp or null): An exact time. Give this or date.
mode (NearestMode): nearest (default), before or sameDay.

Result

Type: FoundPrice or null.