列出出售或出租的住宅房源,支持 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 功能

按地区 ID 搜索买卖与租赁住宅 通过 locationId(例如 0-EU-ES-28-07-001-079)搜索任何 Idealista 区域,并用 operation 在出售与出租之间切换。ID 来自联想和子地区接口,因此可以把一个城市缩小到某个区县。
房源类型标志与组合快捷方式 flat、penthouse、duplex、chalet、villaType、countryHouse、loftType、atticStudioType 和 cortijoType 等标志用来选择住宅类型。设置 flat 会同时返回公寓、顶层复式和复式住宅,设置 chalet 会同时返回独立、双拼、联排和乡间住宅。
楼宇与舒适设施筛选 可以把结果缩小到带有 airConditioning、swimmingPool、garden、terrance、garage、elevator、exterior、builtinWardrobes、storeRoom 或 accessible 的住宅,还能通过 topFloor 和 intermediateFloor 限定楼层位置。
卧室与卫生间数量标志 bedrooms0 到 bedrooms4 标志以及 bathrooms1、bathrooms2 和 bathroom3 标志按房间数量筛选,无需数值范围参数。
仅限租赁的条款 当 operation=rent 时,furnished 接受 furnished 或 furnishedKitchen,petsAllowed 只保留允许宠物的住宅,而 shortTerm 或 longTermResidential 区分短期与长期租赁。
特殊情形的出售标志 isTenanted、isIllegallyOccupied、isBareOwnership、bankOffer 和 isFree 用来筛出或排除带租约、被占用、虚有产权或银行房源等条件下出售的房产。
含价格、位置与媒体的房源卡片 在探测的响应中,每张 elementList 卡片都提供 propertyCode、price 和 priceByArea、size、rooms、bathrooms、address、latitude 和 longitude、url、照片、视频与虚拟看房数据,以及发布方的 contactInfo。
十二种排序与分页、计数控制 order 可按相关度、价格、每平方米价格、面积、楼层、发布时间或降价幅度排序。numPage 与 maxItems 用于翻页,文档说明 maxItems=0 只返回数量,响应中带有 total 和 totalPages。

在线 API 演示

GET /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'
📢
需要帮助?
如遇接口异常,或需要其他接口需求,可联系我们
联系我们

使用场景

常见问题

住宅房源搜索有哪些必填参数?

必填的查询参数共七个: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,每次只传一个。

相关接口

相关指南

查看订阅方案 →