Percentages and formats
Updated 2026-11-13
How percentage inputs are sent (as decimals), how SpreadAPI recognises percentages, currencies and dates from the cell format, and how formats travel with outputs so results can be shown the way your workbook shows them.
The rule for percentages
A percentage is sent as a decimal: 0.05 for 5%, 0.19 for 19%, 1 for 100%.
This is how a spreadsheet stores a percentage. A cell that shows 5% holds the number 0.05, and formulas such as =B1*B2 calculate with 0.05. A service works with the stored value, in both directions:
- A caller sends
0.05for an interest rate of 5%. - An output cell that shows 7.25% returns
0.0725.
How SpreadAPI recognises a percentage input
When you add a cell as an input, SpreadAPI reads its number format.
- The cell is formatted as a percentage. The input is marked as a percentage. This also works when the format comes from the whole column or row.
- The cell is not formatted as a percentage, currency or date, but its label says so. If the label next to the cell contains
%, "percent", "Prozent", "Zinssatz" or "Zinsfuß", and the cell holds a decimal below 1, the input is marked as a percentage as well.
For a percentage input the dialog suggests:
| Field | Suggested value |
|---|---|
| Display Format (Optional) (Anzeigeformat) | The format of the cell, for example 0.00% |
| Min Value (Min-Wert) | 0 |
| Max Value (Max-Wert) | 1 |
| Example Values (Beispielwerte), under AI Info | 0.05 for 5%, 0.10 for 10%, 0.075 for 7.5% |
Change the limits if your model allows other values: a maximum of 0.25 allows up to 25%, a maximum above 1 allows more than 100%, a minimum below 0 allows negative rates.
The safest way to get this right is to format the cell as a percentage in the workbook before you add it; see Formatting and number formats. You can also mark an input yourself by entering a percent format such as 0.00% in Display Format (Optional).
If you later change the cell's number format with the toolbar, the input follows: it becomes a percentage input or stops being one, and you see Parameter format updated to match the cell: ….
What a caller may send for a percentage input
| Sent | Used in the workbook | Note |
|---|---|---|
0.05 | 0.05 (5%) | The recommended form. |
"5%" | 0.05 (5%) | Text with a percent sign is converted. |
5 | 0.05 (5%) | A number above 1 is read as percent points. |
1 | 1 (100%) | 1 is a decimal, not 1%. |
"150%" | 1.5 (150%) | Use the percent sign for values above 100%; the maximum then decides whether it is accepted. |
After the conversion the value is checked against the minimum and maximum of the input, which are decimals. With a maximum of 1, "150%" is refused with "Value 1.5 is above maximum 1".
Send decimals whenever you can. They mean the same for every input and every service.
AI assistants are told about this by SpreadAPI itself: the description of a percentage input, as an AI receives it, ends with "Send a decimal: 0.05 for 5%." You do not need to write that into your own description; see Write good descriptions.
Currency
A cell with a currency format (€, $, £, ¥, ₹ or CHF in the format) gives its parameter a format such as €#,##0.00.
- Inputs: the caller sends the plain number,
1250.5, without symbol and without thousands separators. The format only says how the value is shown in web apps. - Outputs: the answer carries the plain number and the format.
A service does not convert between currencies. The symbol is a display format; the number is what your formulas calculate.
Dates
A cell with a date format gives its parameter the format marker date. Parameters have no date type of their own; how to send and return dates is described in Data types.
Formats on outputs
When you add an output, its format is taken from the cell and shown in Format String (Optional) (Formatstring). You can edit it.
| Cell shows | value in the answer | formatString in the answer |
|---|---|---|
| 7.25% | 0.0725 | 0.00% |
| €1,211.96 | 1211.96 | €#,##0.00 |
| 1,234.5 | 1234.5 | #,##0.0 |
| 15.01.2026 (a date cell) | see Data types | date |
| 42 (format General) | 42 | not present |
The value is never rounded or turned into text by the format. Who uses the format:
- Your own code can apply it, or format the number in its own way.
- Web apps and web snippets show inputs and results with it; see Apps overview.
- AI assistants are told to show each output under its title and in its format, so 0.0725 with
0.00%is presented as 7.25%.
Format strings use Excel's format codes. Examples: 0%, 0.00%, €#,##0.00, $#,##0.00, #,##0, #,##0.0 "kg".
An output that is a cell range carries one format per column, as columnFormats. They are recorded from the cells when you publish; see Add outputs.
For developers and agents
- An input counts as a percentage when it was marked from its cell, or when its format string contains a bare
%. A%inside quotes, as in0" %", is only a displayed character. - Conversion for percentage inputs: text matching a number followed by
%is divided by 100; a bare number with an absolute value above 1 is divided by 100; values between -1 and 1 are used as sent. - Text with a percent sign is also accepted for a number input whose minimum is at least 0 and whose maximum is at most 1.
- Limits (
min,max) are compared after the conversion and are decimals. - Outputs:
{ "name", "title", "value", "formatString"? }.valueis the stored number. - An AI agent connected to the account additionally gets a
displaytext for formatted numbers when it tests or runs a service; see What an agent can do.
FAQ
How do I send 5 percent to the API?
Send the decimal 0.05. The text "5%" is accepted too, but decimals are the recommended form.
What happens if I send 5 instead of 0.05?
For an input marked as a percentage, a number above 1 is read as percent points, so 5 is used as 0.05. For any other number input, 5 stays 5 and is checked against the input's limits; see Input errors.
Is 1 read as 1% or as 100%?
As 100%. Values up to 1 are decimals and are used as sent, so send 0.01 for 1%.
How does SpreadAPI know that my input is a percentage?
From the cell's number format when you add the input. A cell formatted as a percentage becomes a percentage input, with a minimum of 0 and a maximum of 1 as a suggestion.
My input was not recognised as a percentage. How do I fix it?
Format the cell as a percentage with Number format in the toolbar; the input then follows. Alternatively open the input and enter a percent format such as 0.00% in Display Format (Optional).
How do I allow more than 100%?
Open the input and raise Max Value, for example to 2 for 200%. Callers then send 1.5, or "150%", for 150%.
Do I send currency amounts with the symbol?
No. Send the plain number, for example 1250.5, with a point as the decimal separator and no thousands separators.
Can I change how an output is formatted without changing the workbook?
Yes. Open the output with the pencil and edit Format String (Optional), for example to €#,##0. Save and publish again.
Does the format round my results?
No. The format only describes how to display the value. To return a rounded number, round it in the workbook with ROUND.
As an agent, how should I present a result to my user?
Show each output under its title and apply its formatString to value: 0.0725 with 0.00% is 7.25%, 265.5 with €#,##0.00 is €265.50. Do not send a formatted text back as an input; send plain numbers.