REST API reference

JSON over HTTPS, no authentication, no signup. Every calculator on this site is an endpoint, and every endpoint runs the same engine the pages do. Fair-use rate limits apply and an optional key raises them.

Making a request

POST a JSON body. That is the whole protocol.

Request

curl -s https://www.usmortgagecalc.com/api/v1/calculate-mortgage \
  -H 'content-type: application/json' \
  -d '{
    "homePrice": 400000,
    "downPaymentPercent": 20,
    "annualInterestRatePercent": 6.5,
    "loanTermYears": 30,
    "state": "Texas"
  }'

Response — 200 OK (trimmed)

{
  "data": {
    "monthlyMortgage": 2022.62,
    "monthlyPropertyTax": 603.33,
    "monthlyInsurance": 150,
    "monthlyPmi": 0,
    "monthlyHoa": 0,
    "totalMonthlyCost": 2775.95,

    "loanAmount": 320000,
    "loanType": "conventional",
    "propertyTaxRate": 1.81,
    "state": "Texas",

    "paymentsMade": 360,
    "totalInterestPaid": 408142.36,
    "totalAllPayments": 999342.36,

    "assumptions": {
      "propertyTaxRatePercent": 1.81,
      "propertyTaxSource": "U.S. Census Bureau and Zillow Research",
      "mortgageInsurance": "No conventional PMI estimated because down payment is 20% or more"
    }
  },
  "meta": {
    "operation": "calculate_mortgage",
    "computedAt": "2026-08-14T07:35:56.441Z",
    "disclaimer": "Estimate from published averages. Not a loan offer, rate quote, or financial advice."
  }
}

Calculation endpoints accept POST with a JSON body and return a JSON object. Reference endpoints accept GET. Every response includes the assumptions the engine applied, so a result carries the context needed to interpret it.

Calculation endpoints

11 operations. All are read-only: they compute from the body you send, store nothing, and are safe to retry and to cache.

POST/api/v1/calculate-mortgage

Full monthly housing cost for a US mortgage: principal and interest, property tax, homeowners insurance, mortgage insurance and HOA dues, plus lifetime totals and payoff timing. Pass a state name to use that state's average property tax rate. This is the right tool for 'what would my payment be on a $400,000 house'.

POST/api/v1/calculate-amortization

Payment-by-payment breakdown of how a loan is repaid, showing the split between principal and interest and the falling balance. Use granularity 'monthly' for the first years in detail, 'yearly' for a whole-term overview. Also reports how much sooner extra principal pays the loan off.

POST/api/v1/calculate-pmi

Mortgage insurance for any US loan programme, including the upfront charges most calculators omit. Conventional: monthly PMI and the month it cancels at 80% and 78% loan-to-value. FHA: the 1.75% upfront premium, monthly MIP, and whether it runs for the life of the loan or ends after 11 years. VA: the funding fee, tiered by down payment and prior use, and waivers. USDA: guarantee and annual fees.

POST/api/v1/calculate-property-tax

Annual and monthly property tax for a home, using a state's average effective rate. Also returns how that state ranks nationally and how its rate compares with the national average. For the mechanics behind the number — assessment basis, caps, exemptions, appeal deadlines — use get_state_mortgage_rules.

POST/api/v1/calculate-affordability

Maximum affordable home price from income, existing debt payments and available down payment, using the 28/36 qualifying ratios. Reports which of the two ratios is the binding constraint, which is the actionable part: a buyer limited by the back-end ratio can raise their budget by clearing debt, one limited by the front-end ratio cannot.

POST/api/v1/calculate-refinance

Whether refinancing is worth it: the new payment, monthly saving, and how many months it takes to recover closing costs. Also compares lifetime interest, which catches the common trap where a lower payment costs more overall because the term was reset.

POST/api/v1/estimate-closing-costs

Line-by-line buyer closing costs — lender fees, title, appraisal, transfer taxes, prepaid escrow — plus total cash needed at the table including the down payment. Marks which items are worth shopping for and which are fixed by the county, and adds the FHA upfront premium, VA funding fee or USDA guarantee fee where they apply.

POST/api/v1/calculate-rent-vs-buy

Compares renting and buying on net wealth rather than on monthly payment, accounting for equity, appreciation, maintenance, selling costs, and the return a renter earns on money not spent on a down payment. Returns the year buying overtakes renting. The result is highly sensitive to the appreciation and investment-return assumptions, which are returned alongside it.

POST/api/v1/compare-loans

Compares two to five loan scenarios and reports which is cheapest by monthly payment and which by lifetime cost, separately, because they frequently are not the same loan. Use for 15-year versus 30-year, FHA versus conventional, competing lender quotes, or with and without discount points.

POST/api/v1/get-state-mortgage-rules

How property tax actually works in one state: how assessed value is derived, any statutory growth cap, the billing cycle, named exemptions such as homestead, the filing deadline, who hears appeals and the window to file, notable county variation, and a link to the state's own tax authority. Use this when the question is about mechanics or deadlines rather than a dollar amount.

POST/api/v1/list-states

Every US state with its average effective property tax rate, median home value and estimated annual tax. Sortable, so it answers 'which states have the highest property taxes' directly. Call this to discover valid state names for the other tools.

Reference endpoints

Data rather than calculation. All GET.

GET/api/v1/states

Every state with its average effective property tax rate, median home value and estimated annual tax.

GET/api/v1/states/{state}

One state's assessment rules, exemptions, appeal procedure and county-level notes.

GET/api/v1/assumptions

Every rate, fee and threshold the engine applies, each with a source, source URL and the year it applies to.

GET/api/v1/company

Publisher details, in machine-readable form.

GET/api/health

Liveness check. Returns the engine version.

Errors

One shape, with the offending field named.

400 Bad Request

{
  "error": {
    "code": "invalid_input",
    "message": "Invalid arguments for calculate_mortgage: homePrice — Too small: expected number to be >0",
    "issues": [
      {
        "field": "homePrice",
        "message": "Too small: expected number to be >0"
      }
    ],
    "documentation": "https://www.usmortgagecalc.com/openapi.json"
  }
}

Input is validated against a schema before it reaches the engine, so an invalid request fails with a message naming the field rather than returning a plausible-looking number computed from a coerced value. A missing rate is not a 0% rate, and the API will not pretend otherwise.

Status	Code	When
400	invalid_input	A field failed schema validation. issues[] names each offending field.
400	invalid_json	The body was not parseable JSON.
401	unauthorized	An admin or developer route was called without valid credentials.
404	not_found	No endpoint matches that path.
404	unknown_state	The state name is not one of the fifty. Call /api/v1/states for valid names.
405	method_not_allowed	Calculation endpoints are POST; reference endpoints are GET.
429	rate_limited	Rate limit exceeded. retryAfterSeconds says how long to wait.
500	calculation_failed	The engine threw. This is a bug — please report it.

Every response carries an x-trace-id header, including errors. Quote it in a bug report and the exact request can be found.

Rate limits

120 requests a minute, without a key. A key raises that; it never gates access.

Tier	Per minute	Per month
Anonymous	120	Unmetered
Free key	120	100,000
Pro key	1,200	Unmetered

Every response carries the current state

x-ratelimit-limit: 120
x-ratelimit-remaining: 119
x-ratelimit-reset: 1786692648
x-trace-id: 1342adb143339f417cfbfad52ee3930a

Anonymous callers are bucketed by IP address, so a shared corporate network shares a budget. A key gets its own bucket, which is the other half of what a key buys. Exceeding the limit returns 429 rate_limited with a Retry-After header and retryAfterSeconds in the body — wait that long rather than retrying immediately.

These are ceilings, not guarantees. Counting happens in each serverless instance's memory, and requests spread across instances, so a burst can exceed the stated number before any single instance notices. Treat the figures above as the level below which you will certainly not be limited, rather than the exact point at which you will be. Build against the headers and the 429, not against the number — a global counter is the planned upgrade and the ceiling will start biting exactly where it says.

Authentication

There is none, and that is deliberate. Keys are for headroom, not entry.

Every calculation and reference endpoint works with no credentials at all. If you only need the numbers, you can stop reading here — nothing below is required.

Using a key

curl -s https://www.usmortgagecalc.com/api/v1/calculate-mortgage \
  -H 'authorization: Bearer usmc_live_…' \
  -H 'content-type: application/json' \
  -d '{"homePrice":400000,"downPaymentPercent":20,
       "annualInterestRatePercent":6.5,"loanTermYears":30,"state":"Texas"}'

Send the key as a bearer token. An invalid or revoked key is not an error: the request succeeds at the anonymous limit rather than failing, so a key that expires degrades your throughput instead of your service.

Create and revoke keys on the developer dashboard. A key is shown once at creation and stored only as a salted hash, so it cannot be retrieved afterwards — if you lose it, revoke it and make another.

CORS

Open to every origin. Call it from the browser.

Access-Control-Allow-Origin: * on every response, with GET, POST and OPTIONS allowed and x-trace-id exposed to scripts. There is no credentialed mode, because there is nothing to authenticate.

Calculation responses are cacheable for five minutes at the edge and are safe to retry: they compute from the body you send and store nothing.

Versioning and stability

What will and will not change under you.

The path carries the version. Breaking changes to a response shape arrive at /api/v2, not by editing v1 underneath you.
Additive changes happen in place. New fields may appear in a response. Parse defensively and ignore what you do not recognise.
The data moves, the shape does not. Property tax rates, loan limits and programme fees are updated as agencies publish them. Every value carries the year it applies to — check /api/v1/assumptions if you need to know what changed.

The OpenAPI specification describes every endpoint in machine-readable form and can generate a client. Integration examples cover calling this from an application or wiring it into an AI assistant, and the MCP server exposes the same operations as tools.

Open source on GitHub

The specifications, SDKs and documentation are public. Read them, fork them, or open an issue when something here is wrong — corrections to the docs are the most useful thing you can send.

View DocumentationQuickstart, REST, MCP, errors, rate limits and architecture

GitHub SDKsJavaScript, TypeScript, Python, Go, PHP and C#

API ExamplesMCP clients, agent tools, embedding and CI workflows

MCP SpecificationServer card: 11 tools, 7 resources, 7 prompts

Postman CollectionAll 16 endpoints, verified against production

chetanmane/usmortgagecalc-api — SDKs and examples under MIT, documentation and specifications under CC BY 4.0.