Realtor 美国房产数据 APIs

传入美国城市、邮编、地址，或 property-auto-complete 返回的地点 ID，发现挂牌出售的房源。New York, NY 搭配 sort=newest 已实测。成功结果包含 status=true、message、扁平 data 数组，以及 resultsPerPage、totalResultCount、totalPages、currentPage。已观察到 property_id、listing_id、status=for_sale、list_price、list_date、location.address、description 中的卧室/浴室/面积，以及 primary_photo.href 和 photos[].href；部分属性可能为 null。价格、房间数、面积、房产类型与设施条件属于已列出的可选参数，尚未逐项验证筛选效果。pageSize=8 实际返回 30 条，应按数组长度处理并检查翻页，不要假设请求条数和汇总页数完全可靠。不存在的城市曾返回 HTTP 200、status=false、data=null，并附含糊的分页错误；不能仅凭 HTTP 200 判定搜索成功。

通过 location 查询美国广告中的出租房源，邮编 10001 搭配 sort=newest 已实测。结果包含 status=true、message、扁平 data 数组，以及 resultsPerPage、totalResultCount、totalPages、currentPage。样本可见 property_id、listing_id、status=for_rent、含 postal_code 的 location.address、list_date、可为空的 list_price/list_price_min/list_price_max、description 中的卧室与浴室数量或区间、主图及图片列表。广告租金不等于实际签约租金。pageSize=8 仍返回 30 条，汇总总数和页数也可能与实际行数不一致；应明确展示价格不可用状态，逐页检查并按标识去重。宠物、入住日期和设施等可选输入已列入参数，但并未逐项验证筛选效果。

按 location 查询已售房产，文档列出价格、房间数、房产类型、面积与 minSoldDate 等可选输入。Austin, TX 搭配 sort=newest 已实测，返回 status=true、message、扁平 data 数组及分页汇总。样本可见 property_id、listing_id、status=sold、location.address、last_sold_date、可为空的 last_sold_price、list_price、list_date、description 和图片。挂牌价 list_price 与已记录成交价 last_sold_price 必须分开保存；成交价缺失不等于零。newest 是挂牌相关排序，不能保证最近成交日期排在最前。pageSize=8 实际返回 30 条，应核对实际页面与汇总。成交日期及其他可选筛选尚未验证，此接口不代表完整历史交易数据，也不是认证估价。

提交地点文本，获取用于房源搜索的地点候选。New York, NY 实测返回含 data 数组的对象；候选可见 id、full_address、area_type、city、state_code、country、centroid、counties 和可能为空的 propertyId。首个城市候选的 id 为 city:New York, NY，可作为房源搜索的地点输入，但不是 property_id 或 listing_id。成功数据本身没有 status/message 字段。不存在的地点实测返回 {"data":[]}，应视作正常的无匹配结果。limit=5 曾返回 10 条建议，需要限制展示数量时请在客户端截取，不要承诺请求条数会被严格执行。

将完整 Realtor.com 搜索页面 URL 传入 url，可选 page 与 pageSize。文档列出城市、州、邮编等支持的搜索页面类型；纽约城市链接只是文档示例，本接口尚未实测。适合评估把已保存的搜索条件链接转为 JSON 房源候选的流程。响应字段和分页行为均未确认，应先检查实际结果，再确定映射方式；不能假设所有 URL 都兼容。如果无需链接输入，优先使用已有实测示例的城市或邮编搜索接口。

提交 location，并可选择单个 status：for_sale、for_rent 或 sold，默认 for_sale。此接口中的 page 和 pageSize 按文档保留为字符串输入。它用于评估跨市场状态的统一搜索入口，但尚未实测，响应字段也未确认。将其作为生产环境统一入口前，应分别核对状态筛选、返回地区和分页。需要已验证示例时，请使用在售、出租、已售专用搜索，不要假设它们与本接口结构完全一致。

将已知 MLS 挂牌编号作为 mlsId，page 与 pageSize 是可选数字参数。示例是挂牌编号，不是城市名称。本接口尚未实测，返回房源字段、编号歧义和分页行为未确认。关联记录前应核对实际返回的房产身份与地区。按 MLS 编号查找公开房源不代表直接接入 MLS，不提供 IDX 授权、完整 MLS 覆盖或房源转载许可。

将搜索结果中的 property_id 作为 query，补充所选房源详情。文档还列出房源 URL、完整地址与地址式 ID 输入，但只有 property_id 形式已实测。测试中的详情与搜索记录的 property_id、listing_id、地址及 list_price 一致，返回 status=true、message 和 data 对象。已观察字段包括房源状态、地址与坐标、description.text 及房屋属性、photo_count、photos[].href、mortgage.estimate、mortgage.average_rates、hoa、details、tax_history、property_history、last_sold_date、last_sold_price、last_update_date。不同房产可能缺少部分字段，应保留空值并记录查询时间。金融信息只是估算，不是贷款要约。跟随示例时建议先取得最新搜索 ID，因为挂牌可能变化或失效。

将完整 Realtor.com 房源详情链接传入 url。此只读接口为已保存房源书签提供链接查询方式，但尚未实测，响应字段与支持的 URL 模式均未确认。请使用当前有效链接，核对返回的身份和字段，不要默认结果与 property-v2-detail 相同。若已从搜索取得 property_id，优先参考已实测的 property-v2-detail 进行详情补充。

query 可按文档填写已知房产 ID、支持的房源链接、完整地址或地址式 ID。可选 size 使用 w2048_h1536 形式；实际图片尺寸和缩放行为需验证。专用图片接口尚未实测，响应结构、图库字段和链接可用性均未确认。已实测的 property-v2-detail 曾返回 photos[].href，若同时需要完整房源详情可优先参考该接口。能读取图片链接不代表获得图片复用或再分发授权。

propertyId 与 listingId 必须来自同一条搜索结果，已实测搜索中对应 data[].property_id 和 data[].listing_id。此接口用于单独读取挂牌介绍，但尚未实测，文字字段名、响应结构及旧 ID 组合的行为未确认。不要把一套房的 propertyId 与另一条挂牌的 listingId 混在一起。需要已验证的介绍字段时，property-v2-detail 曾返回 data.description.text 及完整详情。展示房源文字前仍须确认内容使用权。

传入搜索结果中的 propertyId，可选 pageSize。文档用途是发现相似房源，但本接口尚未实测；返回字段、相似判定标准和请求条数的效果都未确认。向用户展示替代房产前，应独立核对候选身份、地区、状态与属性。不要把未知匹配方法宣传为个性化智能推荐、估值建议或可用于正式估价的已售可比样本。

提交 propertyId 与 destinationAddress，可选 transportationType、withTraffic。文档中的交通方式为 driving、transit、walking、bicycling，withTraffic 是布尔输入。本接口尚未实测，时长单位、路线字段和路况处理均未确认。展示通勤估算前，需分别验证出行方式和返回地区。即便有结果也只是时间估算，不能保证实际旅程时长；不要无必要地保留用户工作地点或住址。

传入已知 propertyId，评估文档中的周边区域信息查询。本接口尚未实测，返回类别、评分、边界和字段名均未确认。设计社区信息面板前应先检查实际数据。不要仅凭接口名称推断它提供学校质量、犯罪风险、步行友好度或完整设施覆盖；周边信息缺失应如实保留，不编造当地结论。

提交数字 latitude 与 longitude，评估文档中的经纬度在售搜索。可选输入包括 expandSearchArea、价格、房间数、房产类型、面积、设施、sort、page 和 pageSize。坐标只是文档数字示例，本接口未实测，响应字段与搜索半径行为均未确认。将结果称为“附近房源”前需核对返回地区并逐项验证筛选。不要假设支持多边形、地图边界框或保证距离内完整覆盖。

提供数字 latitude 和 longitude，评估经纬度出租搜索。价格、卧室、浴室、房产类型、features、pets、moveInDate、expandSearchArea、sort、page、pageSize 为可选输入。本接口尚未实测，租金字段、筛选效果和搜索范围未确认。广告租金与实际签约租金应分开，称为附近租房前需核对返回位置；承诺宠物适配或可入住之前，还需验证相应参数行为并核实真实租赁条件。

传入数字 latitude 与 longitude，评估指定坐标周边的已售房产发现。可选 minSoldDate、价格、房间数、建筑和地块面积、房产类型、expandSearchArea、sort、page、pageSize。本坐标接口尚未实测，成交字段可用性、距离范围、筛选与排序均未确认。应分开检查可用成交日期、成交价与挂牌字段，不能把周边候选等同于完整交易数据或专业估价级可比案例。

提交 query 文本，可选 limit，评估经纪人目录专用地点补全。候选用于选择 agents-list 的地点输入，应检查真实返回标识后再传入。本接口尚未实测，建议字段、空结果和 limit 是否限制条数均未确认。不要假定它的地点值与 property-auto-complete 的 ID 或金融工具地点格式可互换。

id 填写文档中的经纪人搜索地点值或邮编。可选姓名、language、agentType、agentFilterCriteria、价格范围、sort、limit、page。agentType 文档值为 BUYER、SELLER、BOTH；语言与排序可在参数中查看。本接口尚未实测，过滤是否生效、响应字段和分页均未确认。文档将 data[].id 作为可能的 profileId、data[].fulfillment_id 作为 fulfillmentId；使用资料、房源组合或反馈接口前必须核对真实路径。找到经纪人记录不代表允许联系，也不证明其专业适合度。

提交经核对的 agents-list 结果中的 profileId，可选 fulfillmentId 必须属于同一经纪人。文档将两者分别对应目录记录的 id 和 fulfillment_id，但这些路径未实测确认。本资料接口也未测试，因此简介、办公室、评分、联系方式等字段均不保证存在。请检查实际返回，仅展示已确认且允许使用的公开信息；不要混用两种标识。

传入经核对的经纪人搜索结果中的 fulfillmentId。可选 status 文档值包括 for_sale、for_rent、off_market、sold、ready_to_build、other，并列出逗号分隔组合；limit 与 page 可选。本接口未实测，房源字段、状态筛选、分页和组合完整性均未确认。展示前需核对返回身份和状态，不能把单次结果视为该经纪人的全部库存或交易历史。

提交所选经纪人的 fulfillmentId，评估公开评论查询。当前参数不提供 page 或 limit。本接口未实测，评论字段、评分刻度、条数与覆盖范围均未确认。应与 agents-recommendations 分开处理，核对真实格式并确认内容使用许可后再展示。公开反馈不等于对经纪人服务质量的客观保证。

提交 fulfillmentId，评估经纪人推荐或客户证言查询。本接口未实测，条目字段、日期、评分和响应结构均未确认。应检查实际内容，不默认沿用 agents-reviews 的结构。保存查询背景，且不要把推荐文字宣传为已认证背书或真实性证明。

提交 homePrice、downPayment 与 location，可选 rate、homeInsurance、hoaFees。文档地点示例为 11212, Brooklyn, NY。此 v1 计算接口未实测，输出字段、隐含假设、利率单位和保险周期均未确认。比较方案前需核对默认值与单位，不要假定它与其他房贷接口使用相同结构或算法。任何可用输出只作为预算估算，不是报价、批准或个性化金融建议。

提交 price、term、downPayment、rate、propertyTaxRate、homeInsurance，可选 applyVeteransBenefits，均按文档类型填写。v2 示例中的利率和税率看似小数比例，但实际比例单位及保险周期尚未实测。本接口响应字段和计算行为均未确认。比较预算前应核对每个单位与可选福利假设；输出只是估算，不代表贷款要约、资格判定或预审批。

提交 homePrice、downPaymentPercentage、mortgageLoanType、interestRate、propertyTaxRate、homeInsurance。此接口用比例表示首付，文档示例为 20，而利率示例看似小数比例。本接口未实测，响应字段、贷款期限解释、利率和税率比例单位、保险周期均未确认。使用首付比例滑块或比较方案前应先验证假设，不能把全部数值按同一种百分比规则转换。结果不是贷款报价或放贷决定。

提交 homePrice、downPaymentPrice，以及 mortgageLoanType、interestRate、propertyTaxRate、homeInsurance。downPaymentPrice 表示现金首付而非百分比，数值示例是预算场景输入。本接口未实测，付款字段、贷款期限解释、利率比例单位和保险周期均未确认。统一单位并验证结果后再比较方案；输出应描述为估算，不是放贷机构报价或个性化建议。

annualIncome 与 availableFunds 按文档是必填字符串，monthlyDebt 是可选数字，isPmiIncluded 是可选布尔值。isPmiIncluded 的说明与名称存在不一致，其真实含义与效果尚待确认，不应宣传为已验证的军人福利或保险功能。本接口未实测，负担能力字段、比率和计算假设均未观察。建议使用虚构场景，尽量少保存个人财务输入；任何可用结果只是预算估算，不是房贷预审批。

提交数字 homePrice、downPayment，以及字符串 interestRate、propertyTax、homeInsurance。可选 loanType 提供文档中的固定利率、FHA 与 ARM 选项，默认 TWENTY_YEAR_FIX。本接口未实测，输出字段、税费与保险解释、贷款类型效果和浮动利率行为均未确认。不要将其 loanType 编码与 tools-mortgage-rates 的 loanTerm 编码混用。展示前验证成本单位与每种融资方式，结果仅作估算而非约束性要约。

将美国 ZIP Code 作为 postalCode，文档示例为 10065。此简化利率查询未实测，返回利率字段、日期、贷款产品、金融机构归属和资格假设均未确认。展示参考利率前应检查实际返回的时间与条件。即使业务成功，也不代表取得当前约束性报价、可申请的贷款要约或用户符合条件的利率。

提交 location，可选 loanType、loanTerm、propertyUse、propertyType、creditScore、points、showUsda 与融资金额。文档以 loanType=52 表示购房、54 表示再融资；购房场景使用 purchasePrice、downPaymentPercent，再融资场景使用 propertyValue、loanBalance。本接口未实测，利率或要约字段、输入依赖和资格处理均未确认。showUsda 与贷款期限编码只是请求选项，不证明产品可用。应验证编码含义、场景条件并减少保存个人财务信息，任何可用利率均不构成约束性报价。

提交 location 文本，评估金融工具专用地点自动补全。本接口未实测，建议字段、返回地点格式和无匹配行为均未确认。文档指出后续金融请求可能使用 data.autocomplete[].location，但应先在真实响应中验证路径。金融地点不应与房源搜索 ID、经纪人目录 ID 混用；此查询本身不计算房贷，也不返回利率。

location 填写支持的地址或地点值；文档中的金融工具流程从 tools-auto-complete 取得地点。本邮编接口未实测，邮编字段、结果数量和匹配规则均未确认。为利率请求选用 ZIP 前应检查真实响应，尤其不能假定多邮编城市只有一个确定结果。它属于地理上下文查询，不是权威邮政投递验证。

提交 location，评估文档中的房贷分析查询。本接口未实测，分析指标、地理粒度、计算假设和响应字段均未确认。设计地点级融资信息面板前应检查实际内容，不能仅凭接口名称推断摊还计划、授信决定、借款人资格或详细贷款要约。

旧版详情接口要求同一搜索记录中的 propertyId 与 listingId，文档已标记弃用，且本接口未实测，响应字段和持续可用性未确认。保留它用于已有集成参考，不推荐新项目以此开始。新开发应优先使用 property-v2-detail，将当前搜索取得的 property_id 作为 query。迁移前比较真实字段可用性，并保持房产身份与挂牌身份的区别。