curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Rent or buy API

The net cost of renting against buying a home over a number of years, from assumptions you set, with the first year in which buying comes out ahead.

POST https://api.curatedapi.com/v1/calc/finance/rent-vs-buy

Adds up what each choice costs over the years you plan to stay. Buying costs the down payment, the buying costs, the mortgage payments and the yearly costs of owning, less what is left after selling the home and repaying the loan. Renting costs the rent, less what the down payment and buying costs would have earned if invested instead. Every growth rate is an input, because the answer depends on them and nobody knows them in advance; change them to see how sure the result is.

Formula

buying = down payment + buying costs + mortgage payments + ownership costs − (home value × (1 − selling costs) − loan balance); renting = rent paid − (down payment + buying costs) × ((1 + return)^years − 1)
  • This is a simple, open model. It leaves out income tax effects, and it does not invest the monthly difference between rent and ownership costs.
  • Ownership costs each year are a percentage of the home's value at the start of that year; rent rises once a year.
  • It is arithmetic on your assumptions, not advice.
  • Amounts are plain numbers in any single currency; no currency conversion is done.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
home_price required decimal (string) The price of the home. Allowed: > 0 and <= 1000000000000000. Unit: currency.
down_payment required decimal (string) Cash paid towards the price. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
annual_rate_percent required decimal (string) The mortgage's annual rate. Allowed: >= 0 and <= 100. Unit: percent.
term_years required integer The mortgage term in years. Allowed: >= 1 and <= 50.
years required integer How many years to compare. Allowed: >= 1 and <= 50.
monthly_rent required decimal (string) Rent per month in the first year. Allowed: >= 0 and <= 1000000000000000. Unit: currency.
rent_increase_percent required decimal (string) How much the rent rises each year. Allowed: >= 0 and <= 100. Unit: percent.
home_appreciation_percent required decimal (string) How much the home's value changes each year; negative for a fall. Allowed: >= -50 and <= 100. Unit: percent.
annual_ownership_cost_percent required decimal (string) Property tax, insurance and upkeep per year, as a percentage of the home's value. Allowed: >= 0 and <= 100. Unit: percent.
buying_costs_percent required decimal (string) Costs of buying, as a percentage of the price. Allowed: >= 0 and <= 100. Unit: percent.
selling_costs_percent required decimal (string) Costs of selling, as a percentage of the sale price. Allowed: >= 0 and <= 100. Unit: percent.
investment_return_percent required decimal (string) The yearly return the down payment and buying costs would earn if invested instead. Allowed: >= 0 and <= 100. Unit: percent.
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
cost_of_rentingdecimal (string)Net cost of renting over the years. Unit: currency.
cost_of_buyingdecimal (string)Net cost of buying over the years. Unit: currency.
differencedecimal (string)cost_of_renting − cost_of_buying: positive when buying is cheaper. Unit: currency.
cheaperstringbuy or rent.
break_even_yearintegerThe first year in which buying costs no more than renting. Absent when that does not happen within the years compared.
home_value_at_enddecimal (string)The home's value after the years. Unit: currency.
loan_balance_at_enddecimal (string)What is still owed then. Unit: currency.
years_tablelist of objectBoth net costs if you stopped after each year.

Examples

A 400,000 home with 20% down against renting at 2,000 a month, over 10 years

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/rent-vs-buy \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "home_price": "400000",
    "down_payment": "80000",
    "annual_rate_percent": "6.5",
    "term_years": 30,
    "years": 10,
    "monthly_rent": "2000",
    "rent_increase_percent": "3",
    "home_appreciation_percent": "3",
    "annual_ownership_cost_percent": "2",
    "buying_costs_percent": "3",
    "selling_costs_percent": "6",
    "investment_return_percent": "5"
  }'
200 OKResponse
{
  "calculator": "finance/rent-vs-buy@1",
  "result": {
    "cost_of_renting": "217274.80",
    "cost_of_buying": "192396.12",
    "difference": "24878.68",
    "cheaper": "buy",
    "break_even_year": 8,
    "home_value_at_end": "537566.55",
    "loan_balance_at_end": "271283.24",
    "years_table": [
      {
        "year": 1,
        "cost_of_renting": "19400.00",
        "cost_of_buying": "53414.68",
        "home_value": "412000.00",
        "loan_balance": "316423.24"
      },
      {
        "year": 2,
        "cost_of_renting": "39290.00",
        "cost_of_buying": "70491.44",
        "home_value": "424360.00",
        "loan_balance": "312606.96"
      },
      {
        "year": 3,
        "cost_of_renting": "59680.10",
        "cost_of_buying": "87211.25",
        "home_value": "437090.80",
        "loan_balance": "308535.08"
      },
      {
        "year": 4,
        "cost_of_renting": "80580.47",
        "cost_of_buying": "103553.97",
        "home_value": "450203.52",
        "loan_balance": "304190.51"
      },
      {
        "year": 5,
        "cost_of_renting": "102001.36",
        "cost_of_buying": "119498.20",
        "home_value": "463709.63",
        "loan_balance": "299554.97"
      },
      {
        "year": 6,
        "cost_of_renting": "123953.04",
        "cost_of_buying": "135021.23",
        "home_value": "477620.92",
        "loan_balance": "294608.97"
      },
      {
        "year": 7,
        "cost_of_renting": "146445.85",
        "cost_of_buying": "150098.95",
        "home_value": "491949.55",
        "loan_balance": "289331.75"
      },
      {
        "year": 8,
        "cost_of_renting": "169490.16",
        "cost_of_buying": "164705.76",
        "home_value": "506708.03",
        "loan_balance": "283701.10"
      },
      {
        "year": 9,
        "cost_of_renting": "193096.35",
        "cost_of_buying": "178814.44",
        "home_value": "521909.27",
        "loan_balance": "277693.35"
      },
      {
        "year": 10,
        "cost_of_renting": "217274.80",
        "cost_of_buying": "192396.12",
        "home_value": "537566.55",
        "loan_balance": "271283.24"
      }
    ]
  },
  "exactness": {
    "cost_of_renting": "rounded",
    "cost_of_buying": "rounded",
    "difference": "rounded",
    "home_value_at_end": "rounded",
    "loan_balance_at_end": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 2
  },
  "inputs": {
    "home_price": "400000",
    "down_payment": "80000",
    "annual_rate_percent": "6.5",
    "term_years": 30,
    "years": 10,
    "monthly_rent": "2000",
    "rent_increase_percent": "3",
    "home_appreciation_percent": "3",
    "annual_ownership_cost_percent": "2",
    "buying_costs_percent": "3",
    "selling_costs_percent": "6",
    "investment_return_percent": "5"
  },
  "formula": "buying = down payment + buying costs + mortgage payments + ownership costs − (home value × (1 − selling costs) − loan balance); renting = rent paid − (down payment + buying costs) × ((1 + return)^years − 1)",
  "references": [
    {
      "title": "Consumer Financial Protection Bureau: Buying a house, tools and resources",
      "url": "https://www.consumerfinance.gov/owning-a-home/"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.