列出 Idealista 出售或出租的新建住宅
查看 Idealista 房源数据接口:西班牙、葡萄牙与意大利房产搜索 的全部接口 →列出 Idealista 上某一地区的新建住宅(购买/租赁 > 新房),并支持可选筛选。必填参数包括国家站点(location:es、it 或 pt)、响应语言(locale)、取自联想或子地区接口的 locationId、交易类型(operation:sale 或 rent)、排序方式、页码(numPage)和每页条数(maxItems,最大 40;取 0 只返回房源数量)。可选筛选涵盖已竣工新房、先租后买、政府补贴住房、银行房源、公寓、独栋住宅或别墅、卧室数量(bedrooms0 到 bedrooms4,其中 bedrooms4 表示四间或更多)以及 minPrice 和 maxPrice。在一次观察到的样例调用中(locale=es、location=es、locationId=0-EU-ES-28-07-001-079、operation=sale、order=relevance、maxItems=5),响应是一个 JSON 对象,包含 elementList(房源数组)、total、totalPages、actualPage、itemsPerPage、numPaginations、summary、filter、alertName、totalAppliedFilters、searchTitle、lowerRangePosition、upperRangePosition 和 paginable。每条被观察到的房源都带有 propertyCode、price、priceInfo、propertyType、operation、address、municipality、district、locationId、latitude、longitude、url、description、numPhotos、multimedia、contactInfo、newDevelopmentFinished、isRentToOwn 和 promoName 等字段。
API 功能
在线 API 演示
未找到可用的 API Key,请前往控制台创建后刷新本页。 控制台 →
/api/project/idealista/list-new-homes API 响应 (JSON)
{} curl -X GET 'https://api.opendata-api.com/api/project/idealista/list-new-homes?key=<API_KEY>&locale=es&location=es&locationId=<locationId>&maxItems=30%2C40&numPage=<numPage>&operation=sale&order=relevance'
查询结果
使用场景
- 按城市跟踪新房供应管线:用 finished 标志和 newDevelopmentFinished 区分现房与在建项目。
- 首次购房者查找工具:在选定市镇内列出价格不超过 maxPrice 的政府补贴楼盘。
- 先租后买聚合平台:搜索 operation=rent 且 rentToOwn=true 的房源,并比较各子地区的月租信息。
- 开发商竞品价格监控:比较公寓与独栋住宅或别墅,并长期跟踪 promoName 和 priceInfo 的变化。
- 按揭获客页面:在贷款计算器旁边展示带有银行房源标志的新房。
- 市场规模看板:对大量地区 ID 调用 maxItems=0,以很低的成本绘制新房供应图表。
- 交互式楼盘地图:根据每一行的 latitude 和 longitude 标点,并链接回门户的房源页面。
常见问题
响应包含哪些内容?
在一次观察到的调用中,响应是一个 JSON 对象,带有 elementList 房源数组,以及 total、totalPages、actualPage、itemsPerPage、numPaginations、summary、filter、alertName、totalAppliedFilters、searchTitle、lowerRangePosition、upperRangePosition 和 paginable。房源包含 propertyCode、price、priceInfo、address、latitude、longitude、url、contactInfo、多媒体标志、newDevelopmentFinished、isRentToOwn 和 promoName 等字段。
怎样只统计新房数量而不下载房源?
把 maxItems 设为 0,参数文档说明这会作为快速响应返回房源数量。观察到的样例使用的是 maxItems=5,所以仅计数模式来自文档而不是实际捕获的调用。
怎样只获取已竣工的新房?
把 finished 设为 true。留空则包含各个阶段的新建楼盘;每一行还会返回 newDevelopmentFinished,你也可以自行对库存分类。
可以搜索租赁、先租后买或补贴住房吗?
把 operation 设为 rent 即可搜索租赁,并可与 rentToOwn=true 组合以获得附带购买选项的租赁。设置 stateSubsidized=true 可筛选补贴住房。在观察到的响应中,每行都带有 isRentToOwn 标志。
locationId 从哪里获取?应该选哪个国家?
用本 API 的联想接口解析地名,再用子地区接口下钻。示例 ID 0-EU-ES-28-07-001-079 与 location=es 一起返回了马德里的结果(filter.locationName 为 Madrid)。请选择与 ID 所属国家一致的 es、it 或 pt。
卧室筛选条件怎么用?
bedrooms0 到 bedrooms3 是各自独立的布尔开关,bedrooms4 表示四间或更多卧室。预计同时开启多个开关会像多选一样扩大匹配范围,但观察到的调用没有覆盖这种情况,请自行测试你需要的组合。
最大页面大小是多少?怎样翻页?
maxItems 最大为 40,超过的值会被忽略。递增 numPage,并在到达 totalPages 时停止。在观察到的样例中,numPage=1 且 maxItems=5 时返回 actualPage 为 1、itemsPerPage 为 5、total 为 271、totalPages 为 55,因此总数反映的是调用时刻的市场状况。
能识别每个单元所属的楼盘吗?
观察到的数据行包含 promoName 和 newDevelopment 标志,但样例中没有看到专门的楼盘标识字段。在把结果接入本 API 的楼盘单元接口之前,请先检查实际响应。