# Idealista Scraper: Spain, Italy & Portugal Property Listings (`themineworks/idealista-listings-scraper`) Actor

Scrape Idealista property listings from Spain, Italy and Portugal by place name or search link: price, rent per month, price per m², price drops, rooms, size, floor, parking, description, tags, agency and photos. Only new listings mode for alerts. No login.

- **URL**: https://apify.com/themineworks/idealista-listings-scraper.md
- **Developed by:** [The Mine Works](https://apify.com/themineworks) (community)
- **Categories:** Real estate, Lead generation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.69 / 1,000 listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Idealista Scraper: Spain, Italy & Portugal Property Listings

[![120 Idealista listings in 72 seconds](https://api.apify.com/v2/key-value-stores/cUXz95yxflDho41nn/records/idealista-listings-scraper-hero.png)](https://console.apify.com/actors/GQduV6HeTgV02nPFw/input)

From **The Mine Works**, makers of [Threads Scraper](https://apify.com/themineworks/threads-scraper) and [B2B Leads Finder](https://apify.com/themineworks/b2b-leads-finder), with over 140,000 runs across 170+ public actors.

### Why choose this actor?

- **Three countries, one table.** Homes for sale and for rent from idealista.com (Spain), idealista.it (Italy) and idealista.pt (Portugal) come back in the same columns: price, rent per month, price per m², the previous price after a drop, rooms, size, floor, parking, description, tags, agency, photo count and link. Our proof run returned **120 listings from Madrid and Barcelona in 72 seconds**, with price, size and link on every row. No Idealista account, no cookies to paste, no proxy to set up.
- **Type a place or paste your own search.** Give a town, district or province name and the actor uses Idealista's own search to find it, or paste any Idealista results link with your filters (price, size, bedrooms, property type, order) and every filter is kept. A Barcelona rentals link capped at 2,000 € a month returned only rents up to 2,000 €.
- **You pay only for listings you receive.** One charge per listing saved to your dataset, plus a flat start fee per run. Pages Idealista refused, place names it does not know, and a listing already delivered earlier in the run cost nothing; with "only listings not delivered before" a daily alert pays only for new listings.

[![Run it on Apify](https://api.apify.com/v2/key-value-stores/cUXz95yxflDho41nn/records/button-run.png)](https://console.apify.com/actors/GQduV6HeTgV02nPFw/input)

**Part of The Mine Works Real estate family:** [Zillow Rentals Scraper](https://apify.com/themineworks/zillow-rental-listings), [Zillow Sold Comps Scraper](https://apify.com/themineworks/zillow-recently-sold), [India Real Estate MCP](https://apify.com/themineworks/india-real-estate-mcp), [Housing.com Scraper](https://apify.com/themineworks/housing-com-scraper), [99acres Scraper](https://apify.com/themineworks/99acres-scraper), [MagicBricks Scraper](https://apify.com/themineworks/magicbricks-scraper).

### Try it in one minute

Paste this input and press Start. It returns the first 30 homes for sale that Idealista shows for Madrid, each with price, rooms, size, floor, agency and link, in about 35 seconds:

```json
{
  "locations": ["Madrid"],
  "country": "es",
  "operation": "sale",
  "maxItemsPerSearch": 30
}
```

You can tell the actor what to read in two plain forms, and mix them in one run:

- **Place names** in `locations`: a town, district or province as you would type it on Idealista (`Madrid`, `Marbella`, `Chamberí`, `Milano`, `Bergamo`, `Lisboa`), searched for homes for sale or for rent on the country site you choose. In Spain and Italy Idealista's own text search finds the place. In Portugal the name is used as the place part of the link (`lisboa`, `porto`), so use the spelling Idealista uses in its links.
- **Idealista search links** in `startUrls`: copy the address of any results page from idealista.com, idealista.it or idealista.pt after setting filters and order there. Any property type works (homes, rooms, offices, premises, garages, land, new builds), and a link to page 3 starts at page 3.

Apify's free plan includes $5 of credit every month, which covers about 4,800 results at this actor's price.

#### Copy to your AI assistant

```text
themineworks/idealista-scraper on Apify. Returns Idealista property listings from Spain (idealista.com), Italy (idealista.it) and Portugal (idealista.pt) by place name or Idealista search link, one row per listing with property code, link, title, price, price period for rents, price per m², previous price and drop percent, rooms, size in m², floor, parking included, detail lines, description snippet, tags, professional or private advertiser, agency name and page for professionals, photo count, main photo, and floor plan, video and 3D tour flags. Call ApifyClient("TOKEN").actor("themineworks/idealista-scraper").call(run_input={"locations": ["Marbella"], "country": "es", "operation": "sale", "maxItemsPerSearch": 90}), then client.dataset(run["defaultDatasetId"]).list_items().items. Required: locations (place names) or startUrls (Idealista search results links). Optional: country ("es", "it" or "pt", default "es", for place names), operation ("sale" or "rent", default "sale", for place names), maxItemsPerSearch (30 to 1,800, default 90), onlyNewListings (default false). Skip rows that have "_type": "info". Full spec: GET https://api.apify.com/v2/acts/themineworks~idealista-scraper/builds/default (Bearer TOKEN), which returns inputSchema and readme. Token: https://console.apify.com/account/integrations
```

### Key features

- **About 30 fields per listing**: property code, link, title (type and address), price, price as shown, currency, price period (month for rentals), price per m², previous price and drop percent, rooms (bedrooms in Spain, locali in Italy, the T number in Portugal), size in m², floor line, parking included, the raw detail lines, the start of the description, Idealista tags, professional or private advertiser, agency name and Idealista page, photo count, main photo, and whether there is a floor plan, a video or a 3D tour.
- **Spain, Italy and Portugal**, sale and rent, from place names or from any Idealista results link, in the site's own language.
- **Idealista's own filters, through your link**: the filters and order you set on Idealista become part of the page address, so pasting that link makes the actor read the same results you see. Tested with a Barcelona rentals link capped at 2,000 € a month: 749 results on Idealista, and every row we read was at or under 2,000 €.
- **Up to 1,800 listings per search, 30 a page.** After the first page the actor knows the total and fetches the pages it still needs four at a time.
- **Alerts on a schedule**: "only listings not delivered before" remembers what earlier runs with the same searches delivered and returns only new listings.
- **Private advertisers are respected**: they are marked `is_professional: false`, carry no name, and any phone number or email they wrote into the description is removed.

### How to use it

#### Basic: homes for sale in one town

```json
{
  "locations": ["Marbella"],
  "country": "es",
  "operation": "sale",
  "maxItemsPerSearch": 300
}
```

#### Several places at once

Each line is its own search on the chosen country site.

```json
{
  "locations": ["Roma", "Bergamo"],
  "country": "it",
  "operation": "rent",
  "maxItemsPerSearch": 150
}
```

#### Your own filters: paste the Idealista link

Set price, size, bedrooms, property type and order on Idealista, copy the address of the results page and paste it. Links from all three countries can go in one run.

```json
{
  "startUrls": [
    "https://www.idealista.com/alquiler-viviendas/barcelona-barcelona/con-precio-hasta_2000/",
    "https://www.idealista.pt/arrendar-casas/porto/"
  ],
  "maxItemsPerSearch": 120
}
```

#### Daily alert: new listings in a town

Investors and buyers' agents watch a few areas for anything new. Turn on "only listings not delivered before" and put the run on an Apify schedule once a day; each run returns, and charges for, only listings that earlier runs with the same searches did not deliver.

```json
{
  "locations": ["Marbella"],
  "country": "es",
  "operation": "sale",
  "maxItemsPerSearch": 90,
  "onlyNewListings": true
}
```

Tip: in your Idealista link choose the newest first order, so the newest listings are on the first pages.

#### Price drop watch for an agency or investor

Every row carries `previous_price` and `price_drop_percent` when Idealista shows a drop. Run a city weekly and filter the dataset on `price_drop_percent` to see who is cutting prices and by how much.

```json
{
  "locations": ["Madrid"],
  "country": "es",
  "operation": "sale",
  "maxItemsPerSearch": 900
}
```

#### Rental market snapshot for Portugal

```json
{
  "locations": ["lisboa", "porto"],
  "country": "pt",
  "operation": "rent",
  "maxItemsPerSearch": 300
}
```

### Input parameters

| Parameter | Type | Default | What it does |
|---|---|---|---|
| `locations` | array of strings | `["Madrid"]` | Place names, one per line, searched on the `country` site for the `operation`. Idealista links are accepted here too. |
| `country` | string | `es` | `es` (idealista.com), `it` (idealista.it) or `pt` (idealista.pt), for place names. |
| `operation` | string | `sale` | `sale` or `rent`, homes, for place names. |
| `startUrls` | array of strings | empty | Idealista search results links with your filters and order, from any of the three sites. |
| `maxItemsPerSearch` | integer | `90` | Most listings per place or link, 30 to 1,800. |
| `onlyNewListings` | boolean | `false` | Skip listings that an earlier run with the same searches delivered. |

Up to 50 searches per run. Links keep their own country, operation, property type, filters and order.

### What data do you get?

One row per listing, grouped here by what it describes:

- **The listing**: `property_code`, `url`, `title`, `description`, `tags`, `details`, `photo_count`, `main_photo_url`, `has_floor_plan`, `has_video`, `has_3d_tour`.
- **Price**: `price`, `price_text`, `currency`, `price_period`, `price_per_m2`, `previous_price`, `price_drop_percent`.
- **The property**: `rooms`, `size_m2`, `floor`, `parking_included`.
- **Who advertises it**: `is_professional`, `agency_name`, `agency_url` (agencies and developers only).
- **Where it came from**: `country`, `site`, `search`, `page`, `rank`, `scraped_at`.

`title` holds the property type and the address as Idealista shows it (for example "Piso en Calle de Ibiza, Ibiza, Madrid"). A field Idealista does not show for a listing is left out of that row, for example `price_period` on sales and `previous_price` when there was no drop.

#### Stable fields for automations

These fields were present in every row of our proof runs (180 listings from Spain, Italy and Portugal) and are safe to build on:

| Field | Meaning |
|---|---|
| `property_code` | Idealista's listing code, the same across runs |
| `url` | Link to the listing |
| `title` | Property type and address |
| `price` | Asking price, or rent per period |
| `price_text` | Price as Idealista shows it |
| `currency` | EUR |
| `size_m2` | Size in square metres |
| `parking_included` | True or false |
| `is_professional` | Agency or private advertiser |
| `photo_count` | Number of photos |
| `country` | es, it or pt |
| `search` | Your place name or link |
| `rank` | Position in the results |
| `scraped_at` | Collection time, UTC |

These names will not change. New fields may be added next to them.

#### Output examples

A flat for sale in Madrid with a price drop (description shortened):

```json
{
  "property_code": "111278716",
  "url": "https://www.idealista.com/inmueble/111278716/",
  "title": "Piso en Calle de Ibiza, Ibiza, Madrid",
  "price": 895000,
  "price_text": "895.000€",
  "currency": "EUR",
  "previous_price": 945000,
  "price_drop_percent": 5,
  "rooms": 3,
  "size_m2": 104,
  "floor": "1ª planta exterior con ascensor",
  "parking_included": false,
  "details": ["3 hab.", "104 m²", "1ª planta exterior con ascensor"],
  "description": "PISO EN VENTA REFORMADO EN CALLE IBIZA Piso exterior en venta en Calle Ibiza...",
  "tags": [],
  "is_professional": true,
  "agency_name": "aProperties Real Estate Madrid",
  "agency_url": "https://www.idealista.com/pro/aproperties-mad/",
  "photo_count": 49,
  "main_photo_url": "https://img4.idealista.com/blur/591_420_mq/0/id.pro.es.image.master/52/48/fe/1431430872.jpg",
  "has_floor_plan": true,
  "has_video": true,
  "has_3d_tour": true,
  "country": "es",
  "site": "idealista.com",
  "search": "Madrid",
  "page": 1,
  "rank": 1,
  "scraped_at": "2026-10-05T22:01:56.520Z"
}
```

A flat for rent in Barcelona with a garage, from a filtered link:

```json
{
  "property_code": "112541737",
  "url": "https://www.idealista.com/inmueble/112541737/",
  "title": "Piso en Paseo de Francesc Candel, 47, La Marina del Prat Vermell, Barcelona",
  "price": 1750,
  "price_text": "1.750€/mes",
  "currency": "EUR",
  "price_period": "month",
  "rooms": 2,
  "size_m2": 70,
  "floor": "5ª planta exterior con ascensor",
  "parking_included": true,
  "details": ["Garaje incluido", "2 hab.", "70 m²", "5ª planta exterior con ascensor"],
  "is_professional": true,
  "agency_name": "Glover Barcelona Real Estate S.L",
  "photo_count": 38,
  "country": "es",
  "search": "https://www.idealista.com/alquiler-viviendas/barcelona-barcelona/con-precio-hasta_2000/",
  "rank": 16
}
```

A rental in Rome from idealista.it:

```json
{
  "property_code": "32410651",
  "url": "https://www.idealista.it/immobile/32410651/",
  "title": "Appartamento in Via della Castelluccia di San Paolo, Castel di Leva, Roma",
  "price": 1500,
  "price_text": "1.500€/mese",
  "price_period": "month",
  "rooms": 5,
  "size_m2": 90,
  "floor": "2º piano senza ascensore",
  "is_professional": true,
  "agency_name": "Ciacci Studio Immobiliare",
  "agency_url": "https://www.idealista.it/pro/ciacci-immobiliare-roma/",
  "photo_count": 33,
  "has_floor_plan": true,
  "has_video": true,
  "country": "it",
  "site": "idealista.it",
  "search": "Roma"
}
```

A studio for rent in Porto from a private advertiser (no name, no contact details; title shortened):

```json
{
  "property_code": "34790115",
  "url": "https://www.idealista.pt/imovel/34790115/",
  "title": "Apartamento T0 na Rua dos Caldeireiros, 90, ...",
  "price": 850,
  "price_text": "850€/mês",
  "price_period": "month",
  "rooms": 0,
  "size_m2": 30,
  "floor": "3º andar sem elevador",
  "is_professional": false,
  "photo_count": 12,
  "country": "pt",
  "site": "idealista.pt"
}
```

The last row of every run that delivered something is an information row. It is never charged; skip rows that have `"_type": "info"`.

### Pricing

Pay per event: you pay for each listing delivered to your dataset, plus a flat $0.005 per run, whatever memory you choose. Prices by Apify plan:

| Event | Free plan | Bronze (Starter) | Silver (Scale) | Gold and above (Business) |
|---|---|---|---|---|
| Listing delivered (`listing-scraped`), per 1,000 | $0.99 | $0.89 | $0.79 | $0.69 |
| Run start (`run-start`), once per run | $0.005 | $0.005 | $0.005 | $0.005 |

What is never charged:

- Place names Idealista does not know, and searches with no listings.
- Pages Idealista refused, even after a retry.
- A listing already delivered earlier in the same run (two searches that overlap).
- Listings an earlier run delivered, when "only listings not delivered before" is on.
- The information row at the end of the dataset (it has `"_type": "info"`).

The proxy that gets through Idealista's bot protection is included in the price; there is no separate proxy fee. To cap a run's cost, set a maximum total charge in the run options; the actor stops cleanly when it is reached.

### FAQ

**What is Idealista, and what does this actor read?**
Idealista is the largest property portal in Spain and one of the largest in Italy and Portugal, listing homes, rooms, offices, shops, garages and land for sale and rent. The actor reads Idealista's public search results pages, the same pages any visitor sees, and returns each listing card as a row.

**How many listings can I get?**
Up to 1,800 per place or link and up to 50 searches per run. Idealista shows 30 listings a page. For a big city, split it into districts or use links with price bands, and run them as separate lines.

**How fresh is the data?**
Live. Every run reads Idealista at that moment. For alerts, put the run on a schedule with "only listings not delivered before".

**Do I need an Idealista account, cookies or an API key?**
No. Nothing to sign in to and nothing to supply. The actor reads what an anonymous visitor sees.

**Do I need to set up a proxy?**
No. Idealista blocks plain automated requests, so the actor sends every page through Apify's unblocking proxy, which is included in the price. A page takes about 25 seconds to come back; the actor fetches four at a time.

**Does it read the full listing page?**
No. It reads the search results, which carry the price, size, rooms, floor, description start, tags and agency for every listing at one request per 30 listings. That keeps runs fast and the price low. Use `url` to open a listing.

**What about private advertisers?**
They are marked `is_professional: false` and the row has no advertiser name. If a private advertiser wrote a phone number or an email into the description, it is replaced with "\[phone removed]" or "\[email removed]". Phone numbers are never read.

**Why is a field missing on some rows?**
Idealista does not show it on that card: `price_per_m2` appears on some sites and cards only, `previous_price` only after a drop, `floor` not for houses, and `agency_name` not for private advertisers. Missing fields are left out of the row instead of being set to empty.

**What happens when a place is not found?**
That search is reported in the run summary (`OUTPUT` in the key-value store) as `not_found`, the rest of the run continues, and nothing is charged for it. In Portugal, use the place as Idealista writes it in its links (`lisboa`, `porto`), or paste a link.

**Can I search offices, garages, rooms or new builds?**
Yes, with a link: choose the property type on Idealista, copy the results address and put it in `startUrls`. Place names search homes.

**Which export formats are there?**
JSON, CSV, Excel, XML, HTML table and RSS from the dataset, or the API.

**Can I use it from Claude, ChatGPT or Cursor (MCP)?**
Yes, through Apify's MCP server.

- Connector URL: https://mcp.apify.com/?tools=themineworks/idealista-listings-scraper
- Claude: Settings > Connectors > Add custom connector, paste the URL, sign in with Apify.
- ChatGPT: developer mode, add an MCP connector with the URL, sign in with Apify.
- Cursor or VS Code: add it as an HTTP MCP server with that URL.
- Claude Code: `claude mcp add -t http idealista-listings-scraper "https://mcp.apify.com/?tools=themineworks/idealista-listings-scraper"`

**Is it legal to scrape Idealista?**
The actor reads only public listing pages that any visitor can see, leaves out private advertisers' names and contact details, and never reads phone numbers. You are responsible for how you use the data, including Idealista's terms and data protection law such as GDPR.

### Integrations

- **Google Sheets**: add the Google Sheets integration to the actor or a schedule, and new listings land in a sheet after each run.
- **Make, Zapier and n8n**: use the Apify app to start a run and read the dataset, for example to send each new listing in your areas to Slack or email.
- **Webhooks**: call your own endpoint when a run finishes.
- **API**: start runs and read results from any language; the Python and JavaScript clients are a few lines each.
- **MCP clients**: Claude, ChatGPT, Cursor, VS Code and Claude Code, as in the FAQ above.

### More from The Mine Works

**Real estate**

- [Zillow Rentals Scraper](https://apify.com/themineworks/zillow-rental-listings)
- [Zillow Sold Comps Scraper](https://apify.com/themineworks/zillow-recently-sold)
- [India Real Estate MCP](https://apify.com/themineworks/india-real-estate-mcp)
- [Housing.com Scraper](https://apify.com/themineworks/housing-com-scraper)
- [99acres Scraper](https://apify.com/themineworks/99acres-scraper)
- [MagicBricks Scraper](https://apify.com/themineworks/magicbricks-scraper)
- [Zillow Property Scraper](https://apify.com/themineworks/zillow-property-details)
- [Zillow Photos Scraper](https://apify.com/themineworks/zillow-photos)
- [Real Estate MCP](https://apify.com/themineworks/real-estate-mcp)
- [Airbnb Scraper](https://apify.com/themineworks/airbnb-scraper)
- [Domain.com.au Property Scraper](https://apify.com/themineworks/domain-property-scraper)
- [realestate.com.au Scraper](https://apify.com/themineworks/realestate-com-au-scraper)

**Social media and video**

- [Threads Scraper](https://apify.com/themineworks/threads-scraper)
- [Reddit Scraper](https://apify.com/themineworks/reddit-scraper)
- [Threads Search Scraper](https://apify.com/themineworks/threads-search-scraper)
- [Instagram Profile Scraper](https://apify.com/themineworks/instagram-profile-scraper)

**Leads and business directories**

- [B2B Leads Finder](https://apify.com/themineworks/b2b-leads-finder)
- [Skip Trace Lookup](https://apify.com/themineworks/skip-trace-lookup)
- [Google Maps Email Scraper](https://apify.com/themineworks/maps-leads)
- [2GIS Places Scraper](https://apify.com/themineworks/2gis-places-search)

**Marketing, SEO and reviews**

- [Facebook Ad Library Scraper](https://apify.com/themineworks/meta-ad-library-scraper)
- [Google Ads Transparency Scraper](https://apify.com/themineworks/google-ads-transparency)
- [Similarweb Scraper](https://apify.com/themineworks/similarweb-scraper)
- [Google News Scraper](https://apify.com/themineworks/google-news)

**LinkedIn**

- [LinkedIn Company Scraper](https://apify.com/themineworks/linkedin-company-details)
- [LinkedIn Post Scraper](https://apify.com/themineworks/linkedin-post-search)
- [LinkedIn Employees Scraper](https://apify.com/themineworks/linkedin-employees)
- [LinkedIn Profile Scraper](https://apify.com/themineworks/linkedin-profile-scraper)

**Science, health and government data**

- [Academic Research MCP](https://apify.com/themineworks/academic-research-mcp)
- [CourtListener Scraper](https://apify.com/themineworks/courtlistener-court-records)
- [Socrata Open Data Scraper](https://apify.com/themineworks/socrata-open-data)
- [OpenAlex Scraper](https://apify.com/themineworks/openalex-scholarly-works)

**Jobs and hiring**

- [Foundit Monster India Jobs](https://apify.com/themineworks/foundit-jobs-scraper)
- [Hirist Jobs Scraper](https://apify.com/themineworks/hirist-jobs-scraper)
- [India Jobs MCP](https://apify.com/themineworks/india-jobs-mcp)
- [Naukri Jobs Scraper](https://apify.com/themineworks/naukri-jobs)

**Company and business data**

- [Company Domain Finder](https://apify.com/themineworks/company-domain-finder)
- [GST Taxpayer Lookup](https://apify.com/themineworks/gst-taxpayer-lookup)
- [Company KYB Resolver](https://apify.com/themineworks/company-identity-resolver)
- [SEC EDGAR Filings Scraper](https://apify.com/themineworks/sec-edgar-filings)

**E-commerce and marketplaces**

- [Ozon.ru Scraper](https://apify.com/themineworks/ozon-product-search)
- [⭐ Amazon Reviews Scraper](https://apify.com/themineworks/amazon-reviews)
- [Amazon Product Scraper](https://apify.com/themineworks/amazon-products)
- [Etsy Listings Scraper](https://apify.com/themineworks/etsy-search-scraper)

**Food and local services**

- [NoBroker Scraper](https://apify.com/themineworks/nobroker-scraper)
- [Swiggy Restaurant Scraper](https://apify.com/themineworks/swiggy-scraper)
- [Zomato Scraper](https://apify.com/themineworks/zomato-scraper)

**Developer and AI tools**

- [Website to Markdown Crawler](https://apify.com/themineworks/rag-crawler)
- [GitHub Skill Finder](https://apify.com/themineworks/github-skill-discovery)
- [GitHub Repo Scraper](https://apify.com/themineworks/github-repo-intelligence)
- [GitHub Trending Scraper](https://apify.com/themineworks/github-trending-scraper)

**More tools**

- [G2 Reviews Scraper](https://apify.com/themineworks/g2-reviews-scraper)
- [Naver Blog Scraper](https://apify.com/themineworks/naver-blog-posts-scraper)
- [WeChat Article Scraper 微信公众号文章](https://apify.com/themineworks/wechat-article-scraper)
- [Taobao Products Scraper 淘宝 天猫](https://apify.com/themineworks/taobao-products-scraper)

### Support

Found a place, link or field that does not come through? Open an issue on the Issues tab and include the input you used; we answer there. For a new site or source, email dmineworks@gmail.com.

*Idealista Scraper turns place names and Idealista links from Spain, Italy and Portugal into one clean table of listings with prices, drops, sizes and agencies, with a charge only for the listings you get.*

# Actor input Schema

## `locations` (type: `array`):

Place names, one per line: a town, district or province as you would type it on Idealista (for example Madrid, Marbella, Chamberí, Milano, Bergamo, Lisboa). Searched on the country site below, for homes for sale or for rent. In Spain and Italy Idealista's own text search finds the place; in Portugal the name is used as the place part of the link (lisboa, porto, cascais). You can also paste Idealista search links here.

## `country` (type: `string`):

Which Idealista site the place names are searched on. Links always use their own site.

## `operation` (type: `string`):

Homes for sale or for rent, for place names. Links keep their own.

## `startUrls` (type: `array`):

Optional. Search results links from idealista.com, idealista.it or idealista.pt, copied from your browser after choosing filters and order there, for example https://www.idealista.com/alquiler-viviendas/barcelona-barcelona/con-precio-hasta_2000/ or https://www.idealista.pt/arrendar-casas/porto/. Any property type (homes, rooms, offices, premises, garages, land, new builds). A link to page 3 starts at page 3.

## `maxItemsPerSearch` (type: `integer`):

Most listings to return for each place or link, 30 to 1,800. Idealista shows 30 listings a page. You pay per listing delivered.

## `onlyNewListings` (type: `boolean`):

For alerts on a schedule: skip listings an earlier run with the same searches already delivered, so each run returns and charges only new ones.

## Actor input object example

```json
{
  "locations": [
    "Madrid"
  ],
  "country": "es",
  "operation": "sale",
  "maxItemsPerSearch": 30,
  "onlyNewListings": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        "Madrid"
    ],
    "maxItemsPerSearch": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("themineworks/idealista-listings-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "locations": ["Madrid"],
    "maxItemsPerSearch": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("themineworks/idealista-listings-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "locations": [
    "Madrid"
  ],
  "maxItemsPerSearch": 30
}' |
apify call themineworks/idealista-listings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,themineworks/idealista-listings-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/GQduV6HeTgV02nPFw/builds/2NhUkxbL7mH5ixjOm/openapi.json