美国房贷计算器 API:区分含税保险月供、本息与还款总额
同一次美国房贷计算里,下面五个数字都是真的,却不能放进同一个「月供」标签:
| 返回字段 | 美元金额 |
|---|---|
monthly_payment | 3,128 |
principal_and_interest | 2,528 |
property_tax | 500 |
home_insurance | 100 |
total_payment | 910,178 |
房产网站若拿第二行做「每月住房支出」,会少展示 600 美元;若拿第一行乘还款期数,又会与第五行对不上。这里需要先对账,再接卡片,而不是先选一个看起来像月供的字段。
月供 3,128 美元不等于本息 2,528 美元
这次计算采用房价 500,000 美元、首付 100,000 美元、贷款 400,000 美元,期限 30 年,年利率 6.5%。返回的本息、月度房产税和房屋保险满足 2,528 + 500 + 100 = 3,128。因此,这一场景的 monthly_payment 包含税和保险,不只是向贷款账户偿还的本息。
PITI 指本金、利息、房产税与保险。本例可按这些已知分项展示 PITI 估算,但「每月住房支出」范围更大,还可能涉及 HOA、贷款保险、维修与水电。把含税保险月供标成「全部持有成本」,仍然会误导跨境购房用户。
展示房贷月供前,先核对税费和保险分项
当前已观测的业务载荷在 data.loan_mortgage,分项位于其 monthly_payment_details。先确认本息、房产税、房屋保险均为有效金额,再与同一对象的月供核对。另一份示例使用顶层 mortgage 和 monthly_property_taxes 等名称,不能据此在当前结构缺项时悄悄补零。
本例传入 hoa_fees=0,只证明了零费用场景;非零 HOA 的计入方式尚未验证。当前已观测分项也没有确立 PMI(私人贷款保险)的金额。缺失不是免费,应在界面写明「HOA/PMI 未确认」,不要把缺项、空值或未验证的旧字段统一转成零。
HTTP 200 也不是对账通过。服务端还要检查平台业务 code(如存在,应为成功码 200)、载荷内错误以及 loan_mortgage 是否存在,失败时停止渲染正常月供。授权平台密钥从控制台取得,仅放在服务端;查询参数中的密钥必须从访问日志和报错链接中脱敏。
响应中的 0.065 不能证明利率参数怎么传
单看返回值,无法倒推请求究竟接受百分数还是小数。这里可以确定小数输入,是因为当前计算接口的参数约定与已验证请求一致:rate=0.065 表示 6.5%,property_tax_rate=0.012 表示 1.2%。传入 6.5 和 1.2 的另一次检查虽得到 HTTP 200,金额却明显不合理。
下面沿用已验证的完整场景,down_payment 是首付金额而非比例,保险输入 100 对应本例每月保险 100 美元。示例中的密钥是占位符,打开文章或复制代码都不会发出数据请求;手动执行才会调用接口,结果不保证与历史检查相同。
curl --get 'https://api.opendata-api.com/api/project/realty-in-us/mortgage-v2-calculate?key=YOUR_API_KEY' \
--data-urlencode 'price=500000' --data-urlencode 'down_payment=100000' \
--data-urlencode 'rate=0.065' --data-urlencode 'term=30' \
--data-urlencode 'property_tax_rate=0.012' --data-urlencode 'home_insurance=100' \
--data-urlencode 'hoa_fees=0' --data-urlencode 'apply_veterans_benefits=false'
apply_veterans_benefits=true 的效果和资格条件未验证。若先从邮编利率查询或地区利率参考取得数据,也必须另核单位、时间与适用条件,不能直接把返回利率塞进计算器。
如需同类应用的 API,可通过联系页面提出需求,平台也提供源码私有化部署。
还款总额 910,178 美元不能当作含税保险月供的累计值
30 年按月还款对应 360 期;3,128 × 360 = 1,126,080,并不是返回的 910,178。反过来,显示本息 2,528 × 360 = 910,080,与返回总额还差 98 美元。这种接近不足以证明总额的完整定义,也不能据此承诺逐期偿还计划或精确的总利息。
应把 total_payment 单独标成「接口报告的贷款还款总额,费用口径待核实」。不要将其改名为「30 年全部住房支出」,也不要用舍入后的月供反算它。房产税、保险可能变化,非零 HOA 和 PMI 的处理尚不明确;单个响应无法证明这些项目在整个期限内如何累计。
用代码拦截缺失费用、舍入差异和假设变更
以下只摘取已观测数值,离线运行即可。实际接入时,把已检查业务状态的 loan_mortgage 传给同一校验函数。缓存要同时保存完整计算参数(不含密钥);用户改了首付、利率、税费或期限,就不能继续展示旧结果。
from decimal import Decimal
def amount(row, key):
value = Decimal(str(row[key]))
if not value.is_finite() or value < 0:
raise ValueError(f"Invalid amount: {key}")
return value
def reconcile(loan, saved_inputs, current_inputs, tolerance=Decimal("0")):
if saved_inputs != current_inputs:
raise ValueError("Assumptions changed; recalculate")
parts = loan["monthly_payment_details"]
subtotal = sum((amount(parts, name) for name in (
"principal_and_interest", "property_tax", "home_insurance"
)), Decimal("0"))
monthly = amount(loan, "monthly_payment")
if abs(subtotal - monthly) > tolerance:
raise ValueError("Monthly components do not reconcile")
return monthly, amount(loan, "total_payment")
inputs = {
"price": 500000, "down_payment": 100000, "rate": 0.065,
"term": 30, "property_tax_rate": 0.012, "home_insurance": 100,
"hoa_fees": 0, "apply_veterans_benefits": False,
}
loan = {
"monthly_payment": 3128, "total_payment": 910178,
"monthly_payment_details": {
"principal_and_interest": 2528, "property_tax": 500,
"home_insurance": 100,
},
}
print(reconcile(loan, inputs.copy(), inputs))
这里缺键会报错,null、非数字和负数也不会变成零。默认严格对账;若展示层确有逐项舍入,先记录原值与精度,再设明确的小额容差,不能拿容差掩盖漏项。为回归测试删除保险字段、改掉月供、修改当前首付,三种情况都应阻止旧卡片通过。此函数只校验已知三项,不会替你确认 HOA、PMI 或总额口径;费用模型变更时也要更新校验规则。
月供估算不是利率报价,也不是贷款审批
这个计算适合比较明确假设下的月度负担,不代表银行愿意按该利率放款,更不证明收入、信用、退伍军人福利资格或可贷额度。税费和保险输入也不是正式税单或保险报价。
嵌入房产产品时,外围数据同样有边界:
- 房源的
property_id与listing_id分列保存;详情必需前者,后者保留挂牌上下文,不能互相替代。返回三条房源只是当页结果,不代表该地区只有三套,匹配总数与页面条数要分开。 - 地址自动补全 HTTP 成功但
autocomplete=[]、命中数为零,可以是正常无候选。经纪人筛选则用agents-v2-list,必填邮编字符串,语言传单个languages值,如mandarin;语言过滤效果未单独验证,不承诺服务匹配。 - 新接入应选当前接口,带
deprecated的房源与房贷路由留作旧系统迁移核对,不能拿旧版字段约定替换新版参数。数据接口不等于获得 MLS/IDX 展示授权,返回照片链接也不授予商用转载权。
这些边界不会因分项加总正确而消失。卡片能证明的是「在所列假设下,这次估算如何组成」,不是一份覆盖未来三十年的费用保证。