Realtor房源搜索 API

POST

接口健康状态

24h 健康值: 正常
24h 平均耗时: —

健康 / 正常
可用
少量可用
基本不可用

正常

24 小时趋势

30 天趋势

房源搜索：返回列表，默认 20 条、单次最多 200 条；主要字段 id、url、title、status、price、sold_price。

单价 $1.39 / 千次（每次 $0.001389），失败与空结果不扣费。同步返回；慢任务可在请求体加 "mode": "async"，先拿 job_id 再轮询。

AI 提示词

复制下面这段给你常用的 AI 助手：里面写好了这个接口的参数、返回字段和示例请求，它会先问清你的需求，再帮你写采集脚本。

请帮我用 EveryInfra 的「Realtor 房源搜索」接口（realtor/property_search）写一个数据采集脚本。

接口约定：
- 请求：POST https://api.everyinfra.com/api/v1/social，请求头 Authorization: Bearer <API Key>；Key 从环境变量 EVERYINFRA_API_KEY 读取，不要写进代码。
- 请求体里 platform 填 realtor，action 填 property_search，参数放在 params 里。
- 必填参数：
  - keyword：房源位置，填写美国五位邮编或 城市,州缩写，例如 78701 或 Austin, TX；不接受任意房源描述。
- 可选参数：
  - baths_min：最少卫浴数量，按整数处理，不能保留 1.5 这类半卫值。
  - beds_min：最少卧室数量，整数；不是整套房屋的总房间数。
  - city：城市名覆盖值；邮编搜索时不要再传不匹配城市，避免组合成相互冲突的定位条件。
  - max_price：最高挂牌价，整数，与 min_price 配合；出售与出租请分别解读价格。
  - min_price：最低挂牌价，整数；价格随出售或出租状态分别为售价或租金，不是 API 调用费用。
  - sort：降序排序：newest 最新上架、price_desc 挂牌价、sold_price_desc 成交价、recently_sold 最近成交、bedrooms_desc 卧室数、lot_size_desc 地块面积、ph…（可选值：bedrooms_desc / lot_size_desc / newest / photo_count_desc / price_desc / recently_sold / recently_updated / sold_price_desc）
  - status：单个房源状态字符串，默认 for_sale；已知值包括 sold、for_rent、ready_to_build、off_market、other 或 new_community。其他值不会被拒绝。
  - limit：这次调用最多返回的条数，整数，1–200；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。（默认 20）
- 返回一组记录，每条记录的主要字段：id、url、title、status（房源状态（在售/已售/待定等））、price、sold_price（成交价）、sold_at（成交时间）、listed_at（挂牌时间）、property_type（房屋类型）、beds（卧室数量）、baths（卫生间数量）、area_sqft（室内面积）；一共 28 个字段，完整列表见 https://api.everyinfra.com/api/v1/social/catalog?platform=realtor。
- 示例请求体：
{
  "platform": "realtor",
  "action": "property_search",
  "params": {
    "keyword": "10022"
  }
}
- 计费：$1.39 / 千次；失败和空结果不扣费。
- 一次要采几十上百个时，在请求体加 "mode": "async"：先拿到 job_id，再轮询 GET https://api.everyinfra.com/api/v1/jobs/{job_id} 取结果。
- 返回 422 时，按错误信息里的候选参数和允许值修正；返回 429 或 503 时，按 Retry-After 等待后重试。

写代码前，先问清楚我要采哪些对象、一共多少个、需要哪些字段、结果存成什么格式，再把方案和大概花费讲给我确认。

请求参数

参数名	位置	类型	必填	默认值	说明
`Authorization`	header	`string`	是	-	Bearer 加你的 API Key。在控制台创建；不要放进网址或代码仓库。
`platform`	body	`string`	是	`realtor`	平台标识，固定值。
`action`	body	`string`	是	`property_search`	能力标识，固定值。
`keyword`	body.params	未声明	是	-	房源位置，填写美国五位邮编或城市,州缩写，例如 78701 或 Austin, TX；不接受任意房源描述。
`baths_min`	body.params	未声明	否	-	最少卫浴数量，按整数处理，不能保留 1.5 这类半卫值。
`beds_min`	body.params	未声明	否	-	最少卧室数量，整数；不是整套房屋的总房间数。
`city`	body.params	未声明	否	-	城市名覆盖值；邮编搜索时不要再传不匹配城市，避免组合成相互冲突的定位条件。
`max_price`	body.params	未声明	否	-	最高挂牌价，整数，与 min_price 配合；出售与出租请分别解读价格。
`min_price`	body.params	未声明	否	-	最低挂牌价，整数；价格随出售或出租状态分别为售价或租金，不是 API 调用费用。
`sort`	body.params	`enum`	否	-	降序排序：newest 最新上架、price_desc 挂牌价、sold_price_desc 成交价、recently_sold 最近成交、bedrooms_desc 卧室数、lot_size_desc 地块面积、photo_count_desc 图片数、recently_updated 最近更新。默认 newest。允许值`bedrooms_desclot_size_descnewestphoto_count_descprice_descrecently_soldrecently_updatedsold_price_desc`
`status`	body.params	未声明	否	-	单个房源状态字符串，默认 for_sale；已知值包括 sold、for_rent、ready_to_build、off_market、other 或 new_community。其他值不会被拒绝。
`limit`	body.params	`integer (1–200)`	否	`20`	这次调用最多返回的条数，整数，1–200；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。

代码示例

bash

curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "realtor",
  "action": "property_search",
  "params": {
    "keyword": "10022"
  }
}'

[OpenAPI 定义 (JSON)]示例从环境变量 EVERYINFRA_API_KEY 读取 Key，复制出去的代码不含你的 Key。

响应示例

真实返回样例

2026年9月26日 16:56（北京时间）用上方代码示例的参数真实调用所得。results 与 count 是那次的真实返回，已隐去名字、账号、头像、主页链接、联系方式等个人信息，列表只保留前 2 条；id、billing、quota 每次调用都不同，只给结构。

json

{
  "id": "req_…",
  "platform": "realtor",
  "action": "property_search",
  "results": [
    {
      "id": "（已隐去）",
      "url": "https://www.realtor.com/realestateandhomes-detail/200-E-58th-St-Apt-6D_New-York_NY_10022_M34658-52869",
      "title": "200 E 58th St Apt 6D",
      "status": "for_sale",
      "price": 850000,
      "sold_price": 182000,
      "sold_at": "1992-01-31T00:00:00+00:00",
      "listed_at": "2026-09-26T09:23:16+00:00",
      "property_type": "condos",
      "beds": 1,
      "area_sqft": 0,
      "year_built": 1963,
      "address": "200 E 58th St Apt 6D",
      "city": "New York",
      "state": "NY",
      "postal_code": "10022",
      "county": "New York",
      "lat": 40.760578,
      "lng": -73.966903,
      "image_url": "https://ap.rdcpix.com/c66ce90814bb5fd99a1e190f0148454dl-m1477315349s.jpg",
      "photo_count": 15,
      "is_new_listing": true,
      "platform": "realtor"
    },
    {
      "id": "（已隐去）",
      "url": "https://www.realtor.com/realestateandhomes-detail/303-Park-Ave-3304_New-York_NY_10022_M91518-56430",
      "title": "303 Park Ave Unit 3304",
      "status": "for_sale",
      "price": 5350000,
      "listed_at": "2026-09-25T20:01:34+00:00",
      "property_type": "condos",
      "beds": 2,
      "area_sqft": 1461,
      "year_built": 1931,
      "address": "303 Park Ave Unit 3304",
      "city": "New York",
      "state": "NY",
      "postal_code": "10022",
      "county": "New York",
      "lat": 40.756886,
      "lng": -73.973892,
      "image_url": "https://ap.rdcpix.com/f53f80b6ec7b0511ff9a94352cfa0222l-m3708302104s.jpg",
      "photo_count": 30,
      "is_new_listing": true,
      "platform": "realtor"
    }
  ],
  "count": 20,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}

返回字段

业务数据在 results 里；下表是每条记录可能包含的字段，平台没有提供的值不会被补造。

字段	含义
`id`	该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。
`url`	该记录在原平台上的可访问链接。
`title`	标题。平台无标题概念时（如纯文本帖）为 null。
`status`	房源状态（在售/已售/待定等）。
`price`	价格数值，不含货币符号；币种见 currency。
`sold_price`	成交价。
`sold_at`	成交时间。
`listed_at`	挂牌时间。
`property_type`	房屋类型。
`beds`	卧室数量。
`baths`	卫生间数量，可能是小数（1.5 = 一全卫加一半卫）。
`area_sqft`	室内面积，平方英尺。
`lot_sqft`	地块面积，平方英尺。
`year_built`	建成年份。
`address`	详细地址，原文透传。
`city`	城市名，用原平台的语言书写，未做中英归一。
`state`	州。
`postal_code`	邮编。
`county`	所属县。
`lat`	纬度。
`lng`	经度。
`image_url`	图片链接。多图能力可能返回 image_urls 数组。
`photo_count`	房源照片数量。
`is_new_listing`	是否为新上架房源。
`is_price_reduced`	是否已降价。降价是买方议价的重要信号。
`is_foreclosure`	是否为法拍房。
`advertiser_emails`	房源挂牌方（经纪人、经纪公司）的联系邮箱列表（property_search）。
`advertiser_phones`	房源挂牌方的联系电话列表（property_search）。
`platform`	数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。

错误与计费

401: 缺少 Key 或 Key 无效。先鉴权再校验参数，未鉴权的请求拿不到参数结构。
422: 参数名或取值不对。错误信息会列出这项能力支持的参数、允许值和最接近的候选，按它改即可；发生在扣费之前。
402: 余额不足，请先充值。
429: 超过账户的每分钟请求上限（名下所有 Key 合计；Key 自设了更低上限时先按它算），按 Retry-After 等待后再试。需要更高上限可在控制台买提速包。
503: 暂时无法完成。已预扣的费用按原账本退回；响应里的 billing 与 refund 写明实际结果，结果未知时会明确标出，不要直接重发。
200 空结果: 请求完成但没有数据，不扣费（billing.reason = empty_result_refunded）。