列出出售或出租的住宅房源,支持 50 多种筛选条件
查看 Idealista 房源数据接口:西班牙、葡萄牙与意大利房产搜索 的全部接口 →返回单个地区的一页 Idealista 住宅房源(购买/租赁 > 住宅)。必填参数:locationId(Idealista 地区 ID,例如 0-EU-ES-28-07-001-079,可通过联想和子地区接口获得)、location(国家站点:es、pt 或 it)、locale(广告语言:es、it、pt、en、ca、de、fr、nl 或 nb)、operation(sale 或 rent)、order(从 relevance 到 lowestfloors 的十二种排序之一)、maxItems(每页条数,默认 30,文档中的最大值为 40,取 0 时只返回数量)以及 numPage(页码,示例为 1)。可选参数包括 minPrice 与 maxPrice 价格区间、以平方米计的 minSize 与 maxSize 面积区间、通过 sinceDate 设置的发布时间窗口(T 为最近 24 小时,仅限租赁;Y 为最近 48 小时,仅限出售;W 为最近一周;M 为最近一个月)、通过 micrositeShortName 限定的中介筛选、面向租赁的 furnished 选项,以及覆盖房源类型、卧室、卫生间、楼宇设施、出售条件和租赁条款的 49 个布尔标志。布尔标志只会以 true 发送;省略某个标志即表示不按它筛选。实际探测中观察到的情况(出售搜索,locale es,location es,maxItems 5,numPage 1,order relevance,无筛选):HTTP 200,JSON 对象包含 elementList(房源卡片)、total、totalPages、actualPage、itemsPerPage、numPaginations、summary、filter、alertName、totalAppliedFilters、searchTitle、geoReach、lowerRangePosition、upperRangePosition 和 paginable。探测到的每张房源卡片都带有 propertyCode、url、price、priceInfo、priceByArea、propertyType、operation、size、rooms、bathrooms、floor、exterior、address、province、municipality、district、neighborhood、locationId、latitude、longitude、numPhotos、thumbnail、multimedia(images、videos、virtual3DTours)、contactInfo(中介名称、用户类型、联系方式、micrositeShortName)、features 对象,以及 priceDropValue 和 priceDropPercentage 等降价字段。该探测没有覆盖租赁搜索、带筛选的搜索、maxItems=0 的计数模式和标志组合,因此它们的行为取自参数说明,在此尚未验证;也没有附带响应结构,映射字段之前请先在实际响应中确认字段是否存在。
API 功能
在线 API 演示
未找到可用的 API Key,请前往控制台创建后刷新本页。 控制台 →
/api/project/idealista/list-home-properties API 响应 (JSON)
{} curl -X GET 'https://api.opendata-api.com/api/project/idealista/list-home-properties?key=<API_KEY>&locale=es&location=es&locationId=<locationId>&maxItems=30&numPage=<numPage>&operation=sale&order=relevance'
查询结果
使用场景
- 片区租金追踪:每周对同一个区运行同样的租赁筛选搜索,保存 total 与挂牌价格,绘制走势图。
- 宠物友好或无家具租房的搬迁推送:把 petsAllowed 或 furnished 与卧室标志及价格上限组合,并用 maxItems=0 的数量与未筛选的总数对比。
- 不良资产投资者筛选:扫描带有 isTenanted、isIllegallyOccupied、isBareOwnership 或 bankOffer 标志的出售房源,并按 priceByArea 排序。
- 短租与长租对比:对同一个 locationId 分别运行 shortTerm 和 longTermResidential 搜索,比较两者各返回多少套住宅。
- 新上架提醒机器人:把 sinceDate 设为 W 或 T、order 设为 mostrecent 轮询,并按 propertyCode 去重,只推送尚未见过的住宅。
- 降价监控:把出售结果按 highestpricereduction 排序,读取 priceDropValue 和 priceDropPercentage,找出急于出手的卖家。
- 豪宅细分市场报告:组合 luxury、villaType、penthouse、swimmingPool 和 garden,估算某个市镇高端市场的规模。
- 海外买家候选清单:设置 virtualTour,保留提供 virtual3DTours 的住宅,让海外买家无需出行即可预先筛选。
常见问题
住宅房源搜索有哪些必填参数?
必填的查询参数共七个:locationId、location、locale、operation、order、maxItems 和 numPage。其余 56 个参数都是可选的筛选条件,其中 49 个是布尔值。
怎样获得 locationId?
用联想接口把地名解析出来,再用子地区接口从城市下钻到各区县。文档示例是 0-EU-ES-28-07-001-079,探测使用的正是这个值,并返回了马德里的结果集。
布尔筛选条件怎么用?
传 true 表示启用该标志,省略则表示忽略;文档说明 false 要通过省略该参数来表达。多个标志如何组合(例如两种房源类型是“或”还是“且”)文档没有说明,请自行测试你所依赖的组合。
哪些筛选条件只适用于租赁或只适用于出售?
furnished、petsAllowed、shortTerm 和 longTermResidential 在文档中为仅限租赁。对于 sinceDate,T(最近 24 小时)仅限租赁,Y(最近 48 小时)仅限出售,W(最近一周)和 M(最近一个月)没有注明限制。
flat 和 chalet 标志分别包含哪些类型?
flat 会同时返回公寓、顶层复式和复式住宅,chalet 会同时返回独立住宅、双拼住宅、联排住宅和乡间住宅。更窄的标志(penthouse、duplex、independantHouse、semidetachedHouse、terracedHouse、countryHouse)只选择单一类型。
每页最多能请求多少条?怎样翻页?
maxItems 默认为 30,文档中的最大值为 40,更大的值会被忽略。递增 numPage 即可翻页,并参考响应中的 totalPages 和 actualPage。探测使用的是 maxItems 5 和 numPage 1。
maxItems=0 有什么作用?
文档说明 0 会快速返回房源数量。探测没有覆盖这一点,所以在依赖它之前,请先在实际响应中确认具体的数据形态。
实际观察到了哪些响应字段?
探测的出售搜索返回了 elementList、total、totalPages、actualPage、itemsPerPage、numPaginations、summary、filter、alertName、totalAppliedFilters、searchTitle、geoReach、lowerRangePosition、upperRangePosition 和 paginable。卡片包含 propertyCode、price、size、rooms、bathrooms、坐标、url、multimedia 和 contactInfo。没有附带响应结构,所以租赁结果和带筛选的结果尚未得到确认。
可以只列出某一家中介的住宅吗?
可以,把 micrositeShortName 设为该中介的微站点短名称,即其专业主页路径的最后一段,例如 cajal-gestion-inmobiliaria。探测中的卡片也带有 contactInfo.micrositeShortName;筛选条件是否期望同一个值文档没有说明,请在实际调用中验证。
有哪些排序方式?
order 接受 relevance、lowestprice、highestprice、mostrecent、leastrecent、highestpricereduction、lowestpricem2、highestpricem2、biggest、smallest、highestfloors 和 lowestfloors,每次只传一个。