Data & Analytics

Rent vs buy analysis

Compares the projected cost of renting versus buying a home over a holding period, anchored to live market mortgage rates. Returns year-by-year cumulative cost of each path (rent vs PITI), equity built, net cost of owning after sale, the breakeven year, and a buy/rent recommendation. When no rate is supplied, the current best market rate for the state is resolved via the decision engine. This route is the single source of truth for the rent-vs-buy math; the MCP analyze_rent_vs_buy tool and the consumer app call it.

Authentication required: Pass your API key in the X-API-Key header.

post/v1/rent-vs-buy

Request

  • Base URL: https://api.rateapi.dev
  • URL: https://api.rateapi.dev/v1/rent-vs-buy
  • Auth: API key in header X-API-Key

Request body

home_pricenumber required

Purchase price in dollars. Required.

monthly_rentnumber required

Current monthly rent in dollars. Required.

down_paymentnumber

Cash down payment in dollars. Default 20% of home_price.

ratenumber

Annual interest rate (percent). If omitted, best market rate for the state is used (fallback 7.0).

term_monthsinteger

Loan term in months. Default 360.

statestring

2-letter US state code. Default CA.

holding_period_yearsinteger

Years you expect to stay before selling. Default 7.

property_tax_ratenumber

Annual property tax as % of home value. Default 1.1.

annual_insurancenumber

Homeowners insurance dollars/year. Default max(800, 0.35% of home price).

monthly_hoanumber

Monthly HOA dues. Default 0.

pmi_ratenumber

Annual PMI as % of loan while LTV > 80%. Default 0.5.

credit_scorenumber

Optional credit score passed to the rate engine.

home_appreciation_ratenumber

Annual home appreciation %. Default 3.0.

rent_growth_ratenumber

Annual rent growth %. Default 3.0.

investment_return_ratenumber

Opportunity-cost return % on invested savings if renting. Default 5.0.

maintenance_ratenumber

Annual maintenance as % of home value. Default 1.0.

closing_cost_pctnumber

Buyer closing costs as % of home price. Default 3.0.

selling_cost_pctnumber

Seller transaction costs as % of sale price. Default 6.0.

marginal_tax_ratenumber

Marginal tax rate % for mortgage-interest/property-tax deduction. Default 0 (no deduction modeled).

Example request

{
  "home_price": 500000,
  "monthly_rent": 2500,
  "down_payment": 100000,
  "rate": 6.875,
  "term_months": 360,
  "state": "CA",
  "holding_period_years": 7
}

Response

Rent vs buy comparison

rate_usednumber

The rate the calculation was run at, as an annual percentage.

rate_source'provided' | 'market' | 'fallback'

Where the rate used in this calculation came from: provided if the caller supplied it, market if it was taken from live offers, fallback if neither was available and a default was used.

recommendation'buy' | 'rent' | 'too_close_to_call'

Which option comes out ahead over the holding period.

confidencestring

How decisive the gap between the two options is: high when one clearly wins, medium when the margin is narrower, low when they are close enough to call a tie.

summary_notestring

Plain-language summary of the comparison.

assumed_defaultsobject[]

Values filled in where the caller supplied none, so the result is reproducible.

next_actionsobject[]

Other endpoints or tools that are the natural next step from this result.

disclosuresstring[]

Statements that must be shown to a consumer alongside this result.

Changes

No recorded changes to this operation across all 1 revision of this API.