{
  "openapi": "3.1.1",
  "info": {
    "title": "Percentage & Ratio Calculator API",
    "version": "1.0.0",
    "summary": "X% of Y, % change, reverse %, percentage points, ratios and aspect ratios, with formulas.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://percentageratiocalculator.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "X% of Y, % change, reverse %, percentage points, ratios and aspect ratios, with formulas.",
        "description": "Answers every everyday percentage question (X% of Y, X is what percent of Y, percentage change, increase or decrease by a percentage, reverse percentage, percentage points versus percent) and every ratio task (simplify, scale, split an amount, aspect ratios). Each answer shows the formula and the steps.\n\nMethodology:\n- X% of Y = X ÷ 100 × Y. X as a percent of Y = X ÷ Y × 100.\n- Percentage change from X to Y = (Y − X) ÷ |X| × 100; positive is an increase.\n- Increase Y by X% = Y × (1 + X/100); decrease Y by X% = Y × (1 − X/100).\n- Reverse percentage: if Y is the value after a change of X%, the original is Y ÷ (1 + X/100) (use a negative X for a decrease, e.g. −20 for 20% off).\n- Percentage points measure the plain difference between two percentages (3% − 2% = 1 percentage point); percent measures the relative change ((3 − 2) ÷ 2 = 50%).\n- Ratios are simplified exactly: decimal terms are first multiplied by a power of 10 to make whole numbers, then divided by their greatest common divisor.\n- Splitting an amount by a ratio uses the largest-remainder method at the chosen decimal places, so the parts always add up to exactly the amount.\n- Aspect ratios: width:height simplified by the GCD, the decimal width ÷ height, and the nearest well-known ratio within 1%. Resizing keeps the ratio: new height = new width × height ÷ width.",
        "tags": [
          "calculators"
        ],
        "x-mcp-tool": "percentage_ratio_calculator",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PercentageRatioCalculatorInput"
              },
              "examples": {
                "example1": {
                  "summary": "What is 15% of 80?",
                  "value": {
                    "mode": "percent-of",
                    "x": 15,
                    "y": 80
                  }
                },
                "example2": {
                  "summary": "Price rose from 40 to 50: percentage change",
                  "value": {
                    "mode": "change",
                    "x": 40,
                    "y": 50
                  }
                },
                "example3": {
                  "summary": "Price after 19% VAT is 119: price before tax",
                  "value": {
                    "mode": "reverse",
                    "x": 19,
                    "y": 119
                  }
                },
                "example4": {
                  "summary": "Interest rate from 2% to 3%: points vs percent",
                  "value": {
                    "mode": "points",
                    "x": 2,
                    "y": 3
                  }
                },
                "example5": {
                  "summary": "Split 1,000 by 2:3:5",
                  "value": {
                    "mode": "ratio-split",
                    "ratio": "2:3:5",
                    "amount": 1000
                  }
                },
                "example6": {
                  "summary": "1920 × 1080 aspect ratio, resize to 1280 wide",
                  "value": {
                    "mode": "aspect",
                    "x": 1920,
                    "y": 1080,
                    "newWidth": 1280
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PercentageRatioCalculatorResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "PercentageRatioCalculatorInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "mode": {
            "title": "Question",
            "type": "string",
            "enum": [
              "percent-of",
              "what-percent",
              "change",
              "increase",
              "decrease",
              "reverse",
              "points",
              "ratio-simplify",
              "ratio-scale",
              "ratio-split",
              "aspect"
            ],
            "default": "percent-of"
          },
          "x": {
            "title": "Value X",
            "description": "Percentage modes: the percentage or the start value (see the question). Aspect ratio: width.",
            "type": "number"
          },
          "y": {
            "title": "Value Y",
            "description": "Percentage modes: the base, end or final value. Aspect ratio: height.",
            "type": "number"
          },
          "ratio": {
            "title": "Ratio",
            "description": "For the ratio modes: 2 to 10 positive terms separated by \":\" (e.g. 16:9, 2:3:5, 1.5:2).",
            "type": "string",
            "maxLength": 120
          },
          "amount": {
            "title": "Amount",
            "description": "Split: the total to share out. Scale: the value the chosen term should become.",
            "type": "number"
          },
          "scaleTerm": {
            "title": "Term to scale",
            "description": "Scale mode: which ratio term (1 = first) should equal the amount.",
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1
          },
          "newWidth": {
            "title": "New width",
            "description": "Aspect ratio: optional; the matching height is calculated.",
            "type": "number",
            "minimum": 0
          },
          "newHeight": {
            "title": "New height",
            "description": "Aspect ratio: optional; the matching width is calculated.",
            "type": "number",
            "minimum": 0
          },
          "decimals": {
            "title": "Decimal places",
            "description": "Rounding of the displayed answer and of split amounts (2 = cents).",
            "type": "integer",
            "minimum": 0,
            "maximum": 10,
            "default": 2
          }
        },
        "required": []
      },
      "PercentageRatioCalculatorResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "mode",
              "question",
              "answer",
              "answerText",
              "formula",
              "steps",
              "ratio"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "percent-of",
                  "what-percent",
                  "change",
                  "increase",
                  "decrease",
                  "reverse",
                  "points",
                  "ratio-simplify",
                  "ratio-scale",
                  "ratio-split",
                  "aspect"
                ]
              },
              "question": {
                "type": "string"
              },
              "answer": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Main numeric answer, rounded to the chosen decimals (null for ratio-only answers)."
              },
              "answerText": {
                "type": "string"
              },
              "formula": {
                "type": "string"
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "ratio": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": false,
                "properties": {
                  "terms": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "simplified": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "unitForm": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Ratio divided by its first term (1 : n)."
                  },
                  "parts": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Split amounts (sum exactly to the amount) or scaled terms."
                  },
                  "decimal": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Aspect ratio as a decimal (width ÷ height)."
                  },
                  "nearestNamed": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "newWidth": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "newHeight": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                }
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}