ROI Calculator API Documentation

1. Overview

The ROI Calculator API provides a simple way to calculate key investment metrics based on a series of cash flows. It accepts an initial investment and subsequent yearly returns, along with a discount rate, to compute the Net Present Value (NPV), Internal Rate of Return (IRR), and Return on Investment (ROI). Additionally, it provides a qualitative rating of the investment.

2. API Endpoint

The base URL for all API requests is:

www.promptbox.cn/api/roi.php

3. Authentication

No authentication is required to use this API.

4. Request

The API accepts POST requests with a JSON body.

4.1 Endpoint Details

POST /api/roi.php

4.2 Headers

Header	Value	Required
`Content-Type`	`application/json`	Yes

4.3 Request Body Parameters

The JSON body must contain the following parameters:

Parameter	Type	Required	Description
`rate`	Number	Yes	The discount, interest, or inflation rate as a percentage. For example, for 5%, use `5`.
`cashFlows`	Array of Numbers	Yes	An array of cash flows. The first element must be the initial investment (as a positive number). Subsequent elements represent the cash inflow (return) for each consecutive year.

4.4 Example Request

This example represents an initial investment of $500,000, followed by 8 years of $20,000 returns, and a final year return of $600,000 (representing the sale of the asset). The discount rate is 5%.


{
  "rate": 5,
  "cashFlows": [500000, 20000, 20000, 20000, 20000, 20000, 20000, 20000, 20000, 600000]
}

5. Response

The API returns a JSON object. The HTTP status code indicates success or failure.

5.1 Successful Response (200 OK)

If the request is valid and the calculation is successful, the API will return an object containing the calculated metrics.

Field	Type	Description
`NPV`	Number	The Net Present Value, rounded to two decimal places. This represents the total value of all future cash flows in today's dollars.
`IRR_percent`	Number	The Internal Rate of Return as a percentage, rounded to two decimal places. This is the discount rate at which the NPV becomes zero.
`ROI_percent`	Number	The real Return on Investment, calculated as `(NPV / Initial Investment) * 100`.
`Rating`	Object	A qualitative assessment of the investment. Contains `rating` and `reason` fields.
↳ `rating`	String	A categorical rating (e.g., "Good Investment", "Terrible Investment").
↳ `reason`	String	An explanation for the given rating, providing context on the metrics.

Example Successful Response


{
    "NPV": 16203.49,
    "IRR_percent": 5.36,
    "ROI_percent": 3.24,
    "Rating": {
        "rating": "Poor Investment",
        "reason": "A barely positive real return of about 0.36% over inflation. However, NPV is just 3.2% of your investment, which is relatively small."
    }
}

5.2 Error Response (4xx)

If the request fails due to invalid input or the wrong HTTP method, the API will return an appropriate HTTP status code and a JSON object containing an error message.

Common Errors:

400 Bad Request: Invalid or malformed JSON, missing required parameters, or non-numeric values in the input.
405 Method Not Allowed: Using an HTTP method other than POST (e.g., GET).

Example Error Response (400 Bad Request)

Request is missing the cashFlows parameter.


{
    "error": "Missing, invalid, or empty array parameter: 'cashFlows'."
}

Example Error Response (405 Method Not Allowed)

A GET request was sent to the endpoint.


{
    "error": "Only POST method is allowed."
}

6. Example cURL Request

Here is an example of how to call the API from the command line using cURL.


curl -X POST 'https://www.promptbox.cn/api/roi.php' \
-H 'Content-Type: application/json' \
-d '{
  "rate": 5,
  "cashFlows": [500000, 20000, 20000, 20000, 20000, 20000, 20000, 20000, 20000, 600000]
}'