# Idealista Scraper: Spain, Italy, Portugal Homes (`automation_craft/idealista-scraper`) Actor

Scrape Idealista ads for sale and rent in Spain, Italy and Portugal by search link, place, map area, ad id or agency, past the 1,800 result cap, no login. Rows: price, price drop, m², rooms, floor, lift, photos, agency, energy rating, coordinates, phones. JSON, CSV, Excel or API; pay per listing.

- **URL**: https://apify.com/automation_craft/idealista-scraper.md
- **Developed by:** [Automation Craft](https://apify.com/automation_craft) (community)
- **Categories:** Real estate, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.38 / 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 Homes

**Idealista scraper** for idealista.com (Spain), idealista.it (Italy) and idealista.pt (Portugal): paste Idealista search links,
or name places, Spanish or Italian postal codes, map areas, ad ids, agencies or a whole country, and get one row per ad with the
price, the last price drop, the size, bedrooms or rooms, the floor, lift, parking, photos and the agency or private advertiser. Add **Listing details**
for the full ad page (every feature line, energy certificate, year built, community fees, map position, update date, photos with
room tags, floor plans, videos), **Phone numbers**, **Map position** and **Agencies**. Searches holding more than Idealista's
1,800 ads are read in price bands until every ad was met. Homes, rooms, new developments, offices, premises, garages, land,
storage rooms, buildings, business transfers and holiday rentals, for sale and for rent, from professionals or any advertiser
(private advertisers only on Spanish and Italian rooms and on every Italian search). No login and no Idealista API key. A gone ad, an unknown place, a repeat or a page Idealista refused is a free row.

Who uses it: property investors and buy to let landlords comparing prices per m² and price drops, agencies and portals studying
their market and other agencies' stock, relocation and rental services, valuation, research and proptech teams building price
indexes for Spain, Italy and Portugal, lead generation teams that need agencies with their phones, and AI agents that need
Idealista data through an API.

### Quick start

1. Open the **Input** tab and paste an Idealista search link into **Idealista links**, for example
   `https://www.idealista.com/venta-viviendas/madrid/chamberi/` (the prefill). The link keeps its own filters, order and page.
2. Or name places in **Places** (`Chamberí, Madrid`, `Milano`, `Lisboa`, a Spanish or Italian postal code such as `28004`), draw **Map areas**, list
   **Ad ids or ad links** or **Agencies**, or switch on **Whole country**, and pick the **Market**, **Sale or rent**, **Property
   type**, the filters and the order you need.
3. Switch on the add-ons you need: **Listing details**, **Agencies**, **Phone numbers**, **Map position** (all off by default).
4. Set **Maximum listings** to what you want to pay for and click **Start**. Download the rows as JSON, CSV or Excel, or read them
   through the Apify API.

### What you get

One row per ad (`type: "listing"`); one row per agency with the **Agencies** add-on or the **Agencies** setting
(`type: "agency"`); one free row per development page (`type: "development"`); one free coverage row per search
(`type: "search"`); free status rows for anything that could not be delivered (`type: "status"`); and a free run summary
(`type: "summary"`).

Fill rates of the search rows were measured on the Actor's platform run KhnEadthb3dDkcd5h of 2026-10-28: every ad of one Idealista
search, 1,490 homes for sale in Chamberí, Madrid (1,354 from professionals, 136 from private advertisers). The Italian and
Portuguese search rows of the Actor's other platform runs (32 and 24 different ads) carry the same fields; the differences are
named in the table.

| Field | What it is | Filled (1,490 Spanish rows) |
|---|---|---|
| `id`, `url`, `market` | Idealista's ad id (a string), the ad's link, `ES`, `IT` or `PT` | every row |
| `operation`, `propertyType` | `sale` or `rent`; `homes`, `rooms`, `newDevelopments`, `offices`, `premises`, `garages`, `land`, `storageRooms`, `buildings`, `businessTransfers`, `holidayRentals` | every row |
| `isDevelopment` | `true` when the card is a new development (its `url` is then the development page) | every row (`true` on none of these 1,490) |
| `title` | the ad title as Idealista shows it (type, street or area, place) | 100 percent |
| `price`, `currency`, `priceText`, `pricePeriod` | the asking price in EUR, as a number and as Idealista writes it; for rentals the period (`month` and others) | 100 percent (`pricePeriod` rentals only) |
| `previousPrice`, `priceDropPercent` | the price before the last drop and the drop in percent, when Idealista shows a drop | 16.5 percent (ads with a drop) |
| `pricePerM2` | the price per m² where the card shows it | 83.5 percent |
| `sizeM2` | built size in m² | 100 percent |
| `bedrooms`, `rooms` | bedrooms (Spain and Portugal), rooms or locali (Italy: `rooms` on 32 of 32 Italian rows) | bedrooms 98.3 percent |
| `bathrooms` | bathrooms where the card shows them (holiday rentals) and on every ad looked up by id, link, dataset or development unit (from its ad page; with Listing details also in `details`) | lookups and holiday rentals |
| `floorText`, `lift`, `exterior`, `parkingIncluded` | the floor line as Idealista writes it, lift, exterior, parking included in the price | 97.8, 97.7, 97.0 and 17.7 percent |
| `featureLines`, `description`, `highlight`, `tags` | the card's feature lines, the card's description text (the start of it; the full text comes with Listing details), its highlight and tags | description 99.6, tags 20.1 percent |
| `photoCount`, `thumbnail`, `hasFloorPlan`, `has3dTour`, `hasVideo`, `hasVirtualTour`, `hasHomeStaging` | photo count, first photo, and what the ad offers (floor plan on 943, video on 567, 3D tour on 156 of the 1,490) | photo count 98.7 percent |
| `advertiserType` | `professional` or `private` | 100 percent |
| `agency` (`slug`, `name`, `url`) | the agency of a professional ad, with its Idealista page | 65.4 percent |
| `promoted`, `onlineBooking` | the ad's promotion flag, online booking (rooms and holiday rentals) | where Idealista shows them |
| `auction`, `auctionDate` | Italian court auctions: the auction flag and the sale date | auctions only |
| `guests` | holiday rentals: how many guests | holiday rentals only |
| `latitude`, `longitude`, `mapStatus` | the ad's map position, with **Map position** or **Listing details** | 20 of 20 Portuguese rows with Map position on (run WSana4uQgta5DYWT8) |
| `phones`, `phonesStatus` | the advertiser's phone numbers (`number`, `formatted`), with **Phone numbers** | see below |
| `derived` | `pricePerM2`, `pricePerBedroom`, `usableToBuiltRatio`, `daysSinceUpdate`, `distanceFromCentreKm` (circle searches), computed from the row's own figures | price per m² 100 percent |
| `descriptionContacts` | e-mail addresses, phone numbers and web links written in the description | 5 rows (0.3 percent) |
| `detailsStatus`, `details` | the Listing details block (below) | with Listing details |
| `search` (`key`, `url`, `input`, `band`, `page`, `position`) | which input, search, price band, page and place on the page delivered the row | every search row |
| `lookedUpBy`, `development` | for ads looked up by id, link or dataset: which input; for a development's units: the development | lookups only |
| `scrapedAt` | when the row was written | every row |

#### Listing details (add-on)

With **Listing details** (`includeDetails`) on, each ad's own page is read and added in `details`. Measured on the 42 ad pages
read with details in ten of the Actor's platform runs of 2026-10-28 (Spain 25, Italy 14, Portugal 3; 36 from professionals, 6
from private advertisers with personal data off; runs zWdcz5iB5if8b7Wml, SBgHZdgSEN2p0xrnm, sqdn5nMejtFpxuskg, GTUeEHrxDYCDvcBNu,
Wb0tcvwlCen58qyX5, 163TnZnja57Ni4clJ, AO2lrqgcxSVdSlveF, rIVNMyz0rccqGxwrb, bN74nwTlSXUjmFfqW, uxGEq0KPxk785bgUJ; run
KwJ5LxBIlULwZ4OWH read 4 more in the `idealistaApi` row format, which names these fields differently):

| Field in `details` | What it is | Filled (42 ad pages) |
|---|---|---|
| `description`, `descriptionLanguages`, `descriptionTranslations` | the full advertiser description (text, HTML or Markdown), its languages, and Idealista's own translations into up to 5 languages you pick (no extra charge) | description 97.6 percent; translations 8 of 8 Italian ads into English (run bN74nwTlSXUjmFfqW) |
| `featureSections`, `headlineFeatures`, `priceLines` | every feature line of the ad page, by section, as Idealista writes it | 100 percent |
| `bathrooms`, `usableSizeM2`, `plotSizeM2`, `condition`, `yearBuilt`, `orientation`, `heating` | from the feature lines | bathrooms 92.9, year built 50.0, heating 83.3, orientation 59.5 percent |
| `lift`, `parking`, `parkingPrice`, `terrace`, `balcony`, `wardrobes`, `storageRoom`, `airConditioning`, `pool`, `garden`, `furnishing`, `petsAllowed`, `accessible` | the home's features | where the ad names them |
| `communityFees`, `communityFeesText` | the monthly community fees | 35.7 percent |
| `energy` (`rating`, `consumption`, `consumptionClass`, `emissions`, `emissionsClass`) | the energy certificate | rating 85.7 percent |
| `street`, `locationLines`, `location` (`street`, `neighbourhood`, `district`, `municipality`, `province`), `locationId` | the address lines as Idealista lists them, split into named parts where Idealista labels them, and Idealista's deep location id of the ad | location lines 92.9 percent (holiday rentals show none); location id 39 of 42 (not on the 3 new development cards, whose `details` carry the development page) |
| `latitude`, `longitude`, `coordinatesExact` | the ad's map position and whether Idealista shows it exact or approximate | 85.7 percent (36 of 36 professional ads; private ads only with personal data on) |
| `advertiserType`, `advertiserLabel`, `advertiserName`, `agencySlug`, `agencyLogo`, `advertiserLink`, `reference` | the advertiser and the agency's own reference | advertiser name 85.7 percent |
| `updatedText`, `updatedDate` | Idealista's "ad updated on" line and its date | 92.9 percent (holiday rentals show none) |
| `photos` (`url`, `tag`), `floorPlans`, `videos`, `documents` | every photo with its room tag, floor plans, videos and documents | photos 100, floor plans 73.8, videos 52.4 percent |
| `counterOfferEnabled`, `videoGuidedVisit`, `onlineBooking`, `occupancy`, `newDevelopment`, `label` | the ad's flags | where Idealista shows them |
| `auction`, `auctionDate`, `businessTransfer`, `transferRent`, `transferRentText`, `guests`, `touristLicence` | Italian auctions with their date, business transfers with their rent, holiday rentals with guests and tourist registration | those property types only |

`detailsStatus` says `delivered`, `not_requested`, `not_read` or `not_read_run_stopped`; only `delivered` is billed. Two more
status fields appear on a row only when a run stop cut that read: `translationsStatus` (the description translations) and
`locationIdStatus` (the location id), each `not_read_run_stopped`. An ad whose page says it is gone is left out, free (counted
as `ad_gone` in the coverage row).

#### Phone numbers and map positions (add-ons)

**Phone numbers** (`includePhones`) reads the ad page's own phone button and writes the numbers of agencies and other
professionals into `phones` (`number` and `formatted`): 5 of 5 professional Spanish ads (run zWdcz5iB5if8b7Wml) and 8 of 8
Italian ads (run bN74nwTlSXUjmFfqW) on the Actor's platform runs. Idealista's phone button does not serve a private advertiser's
numbers (0 of 6 tries with personal data on, runs FJKkcnvafTIJXEDKA and GhKGaj54CvNmT6y5Q), so private ads get none, whatever the
personal data switch says: `phonesStatus: "not_served_for_private_advertisers"`, never billed. **Map position**
(`includeCoordinates`) reads Idealista's own map for a search row's `latitude` and `longitude` (Listing details already carries
the position): 20 of 20 Portuguese ads (run WSana4uQgta5DYWT8) and 5 of 5 Spanish ads (run nnbOYHGrfgrv7Hzh2); a private
advertiser's position only with personal data on. Each is billed only when it delivered.

- `phonesStatus`: `delivered`, `no_phone` (the ad has none), `not_served_for_private_advertisers`, `not_read` (Idealista refused
  or did not answer), `not_read_run_stopped` (the run stopped before the read) or `not_available_for_development` (a development
  card; its units carry their own).
- `mapStatus`: `delivered`, `no_map`, `private_advertiser_needs_personal_data`, `not_read`, `not_read_run_stopped` or
  `not_available_for_development`.

A phone or map position read Idealista refused is counted in the run's status message, and nothing is charged for it.

#### Agencies

With **Agencies** (`includeAgencies`) on, every agency met in the run gets one row, once: `name`, `addressLines` (with the
postal code), `adsCount`, `clientSince`, `publicationQualityPercent`, `website`, `languagesText`, `description`, `logo`,
`listingTitle`, `locations` (the areas it covers, each with Idealista's `locationId`, its `name` and the agency's own search of
that area in `path`, a relative path on the market's site such as `/pro/homeclub/alquiler-viviendas/balears-illes/`: put
`https://www.idealista.com`, `.it` or `.pt` in front) and the office's own `phones` with `phonesStatus` (free inside the Agency
row, where the agency page names an office: 5 of 6 agencies on runs zWdcz5iB5if8b7Wml and 6Sbg6Yzmdd0876Chl, the sixth
read was not answered and says `not_read`; `not_read_work_allowance` when the run's unpaid work allowance had no room for
this optional read; `no_office` when the agency page names no office). An agency named in the
**Agencies** setting (`/pro/<name>/` or its link) gives its Agency row and its own ads as Listing rows (of the
**Property type** and **Operation** you set; homes for sale by default).

#### Developments

A development link (`/obra-nueva/<id>/`, `/nuova-costruzione/<id>/`, `/empreendimento/<id>/`) in **Idealista links** gives one
free `development` row (`name`, `developer`, `agency`, `priceFromText`, `summary`, `featureSections`, `locationLines`, `units`
with their cells and links, `documents`, `photos`, `description`), then each unit as its own Listing row with its full ad page
(billed as Listing details). In a search (new developments, or a development shown among homes), each development card is one
Listing row whose `url` is the development page; with Listing details its `details` carry the development page, `priceFromText`
and the `units` table.

#### Holiday rentals and auctions

Holiday rentals (Spain, **Property type** `holidayRentals`, for rent) are read with their own link `/es/accommodation/<id>/`,
with `guests` and, with Listing details, the tourist registration in `touristLicence`. Italian court auctions carry `auction` and
the sale date in `auctionDate`; **Auctions** (`only`, `exclude`) filters them where Idealista offers it.

#### The coverage row

Each search gets one free row (`type: "search"`) with its link, Idealista's `total`, the ads `met` and `delivered`, `skipped`
by reason (`price_below_minimum`, `price_above_maximum`, `size_below_minimum`, `size_above_maximum`; `ad_gone` for an ad whose
page says it is gone; `outside_area` for an ad whose known map position lies outside your drawn area or circle; `advertiser_type`
for an ad of the other seller type and `advertiser_type_unknown` for a card without a private or professional mark, when
**Advertiser** is checked on the cards), `pages` and `pagesFailed`, the price `bands` used past the 1,800 cap, a `priceSummary` of
the delivered rows (listings, median, minimum and maximum price, median price per m², sale prices and rents apart), whether the
search was read to its end (`complete`) and why it stopped (`stoppedBy`; for a private sellers walk in Italy also
`started_on_a_later_page`, `seller_unknown_on_some_cards` or `no_price_split_for_private_order`). On run KhnEadthb3dDkcd5h the Chamberí search reported
`total` 1,490, `met` 1,490, `delivered` 1,490, 50 pages, `complete: true`.

#### The summary row

The run's last row (`type: "summary"`, free) counts listings delivered, looked up and gone, details, agencies, places not found
or ambiguous, repeats skipped, rows past the caps, the events charged and those withheld by the charge limit, the requests by
answer, the Portugal browser sessions, and why the run stopped (`stoppedBy`).

### How much does it cost to scrape Idealista?

You pay per event, with Apify's store discounts by plan:

| Event | Free plan | Bronze | Silver | Gold |
|---|---|---|---|---|
| Listing (one ad from a search) | $0.53 per 1,000 | $0.48 per 1,000 | $0.44 per 1,000 | $0.38 per 1,000 |
| Results page (one page of up to 30 ads that delivered at least one Listing) | $0.0077 | $0.0071 | $0.0064 | $0.0055 |
| Listing details (one ad page read, and every ad looked up by id or link) | $0.0049 | $0.00448 | $0.00406 | $0.0035 |
| Agency (one agency, once per run) | $0.0077 | $0.00704 | $0.00638 | $0.0055 |
| Phone number (one ad's phone numbers) | $0.0014 | $0.00128 | $0.00116 | $0.001 |
| Map position (one ad's position) | $0.00042 | $0.00038 | $0.00035 | $0.0003 |
| Portugal session (once per run that reads idealista.pt) | $0.483 | $0.44 | $0.40 | $0.345 |
| Actor start (once per run, charged on every run) | $0.016 | $0.016 | $0.016 | $0.016 |

Platinum and Diamond plans pay the Gold price.

The Store pricing card shows every event per 1,000 events: "$0.38 / 1,000" on the Listing row means one listing costs USD 0.00038
at Gold; "$5.50 / 1,000" on the Results page row means one results page costs 0.55 cents, and the same figure on the Agency row
means one agency costs 0.55 cents; "$3.50 / 1,000" on the Listing details row means one ad page costs 0.35 cents; "$345.00 /
1,000" on the Portugal session row means one Portugal session costs 34.5 cents, charged at most once per run.

- Never billed: status rows, coverage rows, development rows and the summary; an ad met twice in one run; ads outside your price,
  size or seller type filters, or whose known map position lies outside your drawn area or circle; ads that are gone; places
  Idealista does not know or that match several places (in Portugal the lookup itself opens the run's Portugal session: see the
  next point); Portuguese postal codes (refused before any browser opens); links Idealista does not have; pages, ads, agencies
  or add-ons Idealista refused or did not answer; phone numbers of private advertisers (Idealista does not serve them) and their
  map positions with personal data off; description translations; rows the charge limit withholds. An ad looked up by id, link,
  dataset or development unit is billed as Listing details only (no Listing, no Results page). The office phone of an agency
  comes free inside its Agency row.
- The Portugal session is charged once per run when the run starts its first browser session for idealista.pt, also when
  Idealista Portugal then refuses that browser. Looking up a Portuguese place name needs that browser too, so a run whose
  Portuguese place name matches nothing, or several places, still pays the session fee once. A run without Portuguese entries
  never pays it.
- The Actor start event is charged on every run, whatever it delivers: an input with nothing usable delivers nothing, and only
  the start fee is charged.
- The run obeys the maximum cost you set for it: a row whose events the limit cannot pay is not delivered, nothing after it is
  delivered, and the summary says `stoppedBy: "charge_limit"`. The Portugal session is reserved against the limit before the
  browser starts.
- Example on the Gold plan: 1,000 listings from searches cost $0.016 (start) + $0.38 (1,000 listings) + $0.187 (34 results pages
  of 30) = about $0.58. On the Free plan: $0.016 + $0.53 + $0.262 = about $0.81.
- 100 listings from a search with Listing details and Phone numbers, at Gold: $0.016 + $0.038 (100 listings) + $0.022 (4 results
  pages) + $0.35 (100 Listing details) + at most $0.10 (100 phone numbers; ads without a number are free) = at most about $0.53.
  On the Free plan: $0.016 + $0.053 + $0.031 + $0.49 + $0.14 = at most about $0.73.
- A Portugal run of 100 listings, at Gold: $0.016 + $0.345 (Portugal session) + $0.038 (100 listings) + $0.022 (4 results pages) =
  about $0.42. On the Free plan: $0.016 + $0.483 + $0.053 + $0.031 = about $0.58.

A results page is billed once, on the first Listing it delivers; a page whose ads are all repeats or outside your filters is free,
so a search with many repeats can bill a few more pages than listings divided by 30.

### Input

Every entry you give is read; an entry that cannot be used gets a free status row saying why.

| Setting | What it does |
|---|---|
| `startUrls` | Idealista links of any market, up to 1,000: search results pages (with their own filters, order and page), drawn areas (`/areas/...?shape=`), multi area links (`/multi/...`), map pin links (`/point/...`, read as the area around the pin), ad links (`/inmueble/<id>/`, `/immobile/<id>/`, `/imovel/<id>/`, `/es/accommodation/<id>/`; a unit link `/obra-nueva/<dev>/inmueble/<id>/` is read as its ad), development links and agency links (`/pro/<name>/`). Also accepted as `urls`, `searchUrls` or `listingUrls`. |
| `locations` | Place names as Idealista writes them (`Chamberí, Madrid`, `Milano`, `Lisboa`), Spanish and Italian postal codes (`28004`, `20121`) or the place part of an Idealista link (`madrid-madrid`, `madrid/chamberi`). A name that matches several places, or none, gets a free row with Idealista's own candidates (in Portugal the lookup opens the run's Portugal session). A Portuguese postal code is refused, free, before any browser opens: Idealista Portugal's place search has none; give the town or parish name or its link. |
| `wholeCountry` | Searches every province of the market (Spain 52, Italy 107, Portugal 29 districts and islands), each past the 1,800 cap in price bands. Set `maxItems`. |
| `mapAreas` | A drawn area `lat,lng; lat,lng; lat,lng` (3 to 50 points) or a circle `lat,lng,radiusKm` (0.1 to 50 km). |
| `adIds` | Idealista ad ids (in the market below) or ad links of any market, up to 10,000; each delivered with its full ad page. |
| `agencies` | Agency names from their link (`/pro/<name>/`) or the links: the Agency row and the agency's homes for sale. |
| `datasetId` | A dataset of an earlier run (or any dataset whose rows carry an Idealista link in `url`), up to 10,000 rows: its ads are read again with their full ad page (billed as Listing details), and its development links are read as developments; rows that link to neither are counted in one free row. |
| `market`, `operation`, `propertyType` | For places, map areas, the whole country, bare ad ids and agency names: `es`, `it`, `pt` (default Spain); `sale` (default) or `rent`; `homes` (default), `newDevelopments`, `rooms`, `offices`, `premises`, `garages`, `land`, `storageRooms`, `buildings`, `businessTransfers`, `holidayRentals`. A combination Idealista does not offer refuses the run (only the start fee is charged). Links carry their own. |
| `sortBy` | Idealista's own orders: `relevance`, `priceAsc`, `priceDesc`, `newest`, `oldest`, `biggestPriceDrop`, `pricePerM2Asc`, `pricePerM2Desc`, `sizeDesc`, `sizeAsc`, `highestFloor`, `lowestFloor`, `privateFirst` and `agenciesFirst` (Italy), `mostBedrooms` (holiday rentals). Spain refuses its date order to automated reads: use `publishedWithin` there. |
| Filters | `minPrice`, `maxPrice` (EUR, per month for rentals), `minSize`, `maxSize` (m²), `rooms` (`0` in Spain and Portugal, `1` to `3`, then `4` and `5+` in Italy, `4+` in Spain and Portugal), `bathrooms` (`1`, `2`, `3+`), `homeTypes` (16 types), `condition`, `floor`, `features` (24, from air conditioning to sea views), `energyEfficiency`, `occupancy`, `publishedWithin` (`24h`, `48h`, `week`, `month`), `rentalType`, `furnishing`, `auctions`, `advertiserType`, `withFloorPlan`, `withVirtualTour`, `bankOwned`. Each is sent to Idealista as its own search form sends it; on a pasted link a filter you set replaces that filter of the link. Price and size are checked again on every row before it is charged. `advertiserType`: `professional` works for every property type (each card's own private or professional mark is checked). `private` works where Idealista itself helps find private ads: rooms in Spain and Italy (its own filter) and every Italian search, which is then read in Idealista's own private first order (leave **Order** empty or on `relevance`, which then reads in private first order, or set `privateFirst`; any other order is refused with a free reason) and ends at the first page with no private ad, its coverage row `complete` (in that order the private ads come first: in Bologna 69 private ads filled pages 1 to 3 and page 4 held none; no price bands). For other Spanish and Portuguese searches `private` is refused with a free reason: Idealista offers no private filter or order there and lists professionals first (in Madrid's Chamberí the first private ad was on page 13), so a scan would read pages that earn nothing. Ads of the other type and cards without a mark are left out, free, and counted in the coverage row (`advertiser_type`, `advertiser_type_unknown`). With Listing details on, the ad page's own advertiser is checked again. An agency's own ads (from **Agencies**, or an agency's own listing link in **Idealista links**) are a professional's: with `private` they are not read (a free `seller_type_excludes_agency` row, or a free problem row for the link, says so; the agency's own row is still delivered for **Agencies**). A filter setting Idealista does not offer for the **Property type** and **Market** you set refuses the whole run (only the start fee is charged); against a pasted link of another property type it refuses that link only. A filter word inside a pasted link that the Actor does not know refuses that link only (a free problem row; the rest of the input runs). Filters and the order also apply to an agency's own ads (from **Agencies**), written into the agency's search; a filter Idealista does not offer there gives a free row and that agency's ads are not read. Filters need a search or an agency: with ad ids only they refuse the run. |
| `siteFilters` | Any other filter of Idealista's own search form, as `<form field>=<value>` (list below). |
| `includeDetails`, `includeAgencies`, `includePhones`, `includeCoordinates` | The paid add-ons, off by default. |
| `includePersonalData` | Off by default (below). |
| `maxItems`, `maxItemsPerSearch`, `maxPagesPerSearch`, `splitPastCap` | The most Listing rows of the run (no limit when empty: set it) and of one search; pages per search (1 to 60, Idealista shows at most 60 pages of 30 ads); reading past the 1,800 ad cap in price bands, cheapest first (on by default). Also accepted: `maxResults` for `maxItems`. |
| `language` | Idealista's own page language for titles, labels and descriptions where Idealista translates them: Spanish, Catalan, English, Italian, Portuguese, French, German, Dutch or Norwegian (prices, sizes, rooms and every label are read in each of them). Default: the market's own. Description translations (with Listing details) take 18 languages. |
| `outputFormat`, `descriptionFormat`, `descriptionTranslations`, `descriptionMaxLength`, `omitEmptyFields` | `full` (default), `compact` (core fields) or `idealistaApi` (the field names of Idealista's own partner API: `propertyCode`, `priceByArea`, `hasLift` and more, plus this Actor's `agency` and `advertiserType`); descriptions as `text`, `html` or `markdown`; translations into up to 5 languages (with Listing details); a length cap; empty fields left out. |
| `maxConcurrency`, `proxyUrls` | Parallel reads (1 to 4, default 3); your own proxy links instead of Apify residential proxies (included in the price). |

#### Other Idealista filters (`siteFilters`)

Written as the site's own form field and value, for example `adfilter_hasautomaticdoor=1`. A field with `*` takes any whole
number. The named filters above are not repeated here.

- Homes: Portugal for sale `adfilter_moradiaterrea=1`, `adfilter_quintas=1`, `adfilter_solarpalacete=1`.
- New developments: `adfilter_new_development_finished=1`, `adfilter_new_development_in_project=1`,
  `adfilter_new_development_rent_to_own=1`, `adfilter_new_development_hometype_flat=1`, `adfilter_new_development_hometype_house=1`,
  bedrooms `adfilter_is_rooms_0=1` to `adfilter_is_rooms_3=1` and `adfilter_is_rooms_4_more=1` (Italy `adfilter_is_rooms_1=1`
  to `adfilter_is_rooms_4=1` and `adfilter_is_rooms_5_more=1`).
- Rooms (Spain and Italy, rent): `adfilter_arepetsallowed=0|1`, `adfilter_bedtype=1|2|3|4`, `adfilter_childrenallowed=1`,
  `adfilter_couplesallowed=1`, `adfilter_hasHouseKeeper=1`, `adfilter_hasprivatebathroom=1`, `adfilter_isAccessible=1`,
  `adfilter_issmokingallowed=0|1`, `adfilter_newgender=2|3`, `adfilter_newsexualorientation=2`, `adfilter_occupation=2|3`,
  `adfilter_onlineBooking=1`, `adfilter_onlineBookingWithInsurance=1`, `adfilter_ownerIsNotLiving=1`, `adfilter_tenantnumber_2=2`,
  `adfilter_tenantnumber_3=3`, `adfilter_tenantnumber_4=4`, and in Spain `adfilter_windowViewsId=1`.
- Offices: `adfilter_accessibleBuilding=1`, `adfilter_airconditioningid=1`, `adfilter_distribution=1|3`,
  `adfilter_hashotwater=1`, `adfilter_liftsnumber=1`, `adfilter_officeTypePrivate=1`, `adfilter_officeTypeShared=1`,
  `adfilter_onlyofficebuilding=0|1`, `adfilter_parkingspacenumber=1`; for rent also `adfilter_officeTypeDesk=1`; in Spain also
  `adfilter_officelocationid=1`.
- Premises and warehouses: `adfilter_accessibleBathroom=1`, `adfilter_accommodation=1`, `adfilter_aestheticAndBeauty=1`,
  `adfilter_barsAndNightClub=1`, `adfilter_catering=1`, `adfilter_commercialproperty=1`, `adfilter_educationalCenter=1`,
  `adfilter_foodTrade=1`, `adfilter_hassmokeextractor=1`, `adfilter_inamall=1`, `adfilter_industrialbuilding=2`,
  `adfilter_iscornerlocated=1`, `adfilter_laboratory=1`, `adfilter_mezzanine=3`, `adfilter_newsStand=1`,
  `adfilter_onthestreet=2`, `adfilter_ontopfloor=6`, `adfilter_otherCommercialActivities=1`, `adfilter_otherubication=5`,
  `adfilter_pharmacy=1`, `adfilter_professionalServices=1`, `adfilter_retail=1`, `adfilter_sportsFacilities=1`,
  `adfilter_storehouse=1`, `adfilter_tobaccoShop=1`, `adfilter_underground=4`; for sale `adfilter_saleWarehouseOnly=1`,
  `adfilter_saleWarehouseThirdPartiesRented=1`, `adfilter_saleWarehouseWithBusinessTransfer=1`; for rent
  `adfilter_rentWarehouseOnly=1`, `adfilter_rentWarehouseWithBusinessTransfer=1`, `adfilter_transferCost=*`,
  `adfilter_transferCostMin=*` (Italy also `adfilter_rentWarehouseAndBusiness=1`).
- Business transfers: the premises fields above (without the sale only and rent only ones), plus
  `adfilter_rentWarehouseWithBusinessTransfer=1`, `adfilter_saleWarehouseWithBusinessTransfer=1`, `adfilter_priceRentWarehouse=*`,
  `adfilter_priceRentWarehouseMin=*`, `adfilter_priceSaleWarehouseAndTransfer=*`, `adfilter_priceSaleWarehouseAndTransferMin=*`,
  `adfilter_transferCostForTransfers=*`, `adfilter_transferCostForTransfersMin=*`.
- Garages: `adfilter_garagecapacity=3` (motorbike), `adfilter_hasautomaticdoor=1`.
- Land: `adfilter_urban_landtype=1`, `adfilter_developable_landtype=2`, `adfilter_undevelopable_landtype=3`.
- Holiday rentals (Spain): `adfilter_pricePerNight=*`, `adfilter_pricePerNightMin=*`, `adfilter_vacationalAccessibleHousing=1`,
  `adfilter_vacationalAirConditioning=1`, `adfilter_vacationalBbq=1`, `adfilter_vacationalElevator=1`,
  `adfilter_vacationalFirstLineBeach=1`, `adfilter_vacationalFlat=1`, `adfilter_vacationalGarden=1`, `adfilter_vacationalHosts=1`,
  `adfilter_vacationalHouse=1`, `adfilter_vacationalInternet=1`, `adfilter_vacationalOnlineBooking=1`,
  `adfilter_vacationalParking=1`, `adfilter_vacationalPool=1`, `adfilter_vacationalRooms=1`, `adfilter_vacationalTerrace=1`,
  `adfilter_vacationalTv=1`, `adfilter_vacationalVilla=1`, `adfilter_vacationalWashingMachine=1`,
  `adfilter_vacationalWithPets=1`.
- Storage rooms and whole buildings: price, size and published within only (the named filters; in Italy for sale also auctions).

#### Speed

From the Actor's platform runs of 2026-10-28 (start to finish of each run): the prefill (30 Spanish listings from one search)
took 2.8 to 20.1 seconds over six runs (kgvZpCGGgYcKm4Yre, qubB8iscvKkf4x4B9, UPN6dVMWkwTvsh6Ph, ldjznGccRz9RIoz8X,
P5pBE9m88Pv7FAVNQ, tnYwzQwb0dsoohVdL); a whole search of 1,490 Spanish listings (50 pages) took 52 seconds at 4 parallel reads
(KhnEadthb3dDkcd5h). Listing details, phones and map positions add one small read per ad each: 6 Spanish ads with details,
phones, map positions and agencies took 33 seconds (zWdcz5iB5if8b7Wml), 8 Italian ads with details, phones and an English
translation 57 seconds (bN74nwTlSXUjmFfqW). Portugal is slower because a real browser session starts first: 1 listing took 21
seconds (hVybr59BpY9iC05nv), 20 listings with map positions 67 seconds (WSana4uQgta5DYWT8), one listing from each of 3 districts
of the whole country 85 seconds (8gVocHZBKaZ0i3XGC).

#### Portugal

idealista.pt can only be read through a real browser. A Portugal run starts a browser session on a fresh Portuguese exit, waits
until Idealista lets it in (it never clicks or solves a challenge), and reads the pages inside it; it tries at most 4 sessions a
run. It needs 1,024 MB of memory (the default): at less memory the Portuguese entries get one free row naming the memory and the
rest of the input runs. For long Portugal runs (the whole country, thousands of ads) you may set 2,048 MB: the browser then has
more room (the run costs a little more compute).

Looking up a Portuguese place name in **Places** also goes through that browser, so it opens the run's Portugal session: the
session fee is charged once even when the name matches no place, or several (the place row itself is free). Idealista Portugal's
place search has no postal codes (no Portuguese postal code was found in 6 platform runs), so a Portuguese postal code is refused
before any browser opens, free: give the town or parish name, or its Idealista link.

#### Personal data

Agencies' and other professionals' names, logos, links, office phones and their ads' phone numbers are business data and always
delivered (phones with **Phone numbers** on). For ads of private advertisers, the advertiser's first name, the street line, the
exact map position, the advertiser's own link and the contacts written in the description (`descriptionContacts`) are delivered
only with **Include personal data** (`includePersonalData`) on; with it off those fields are empty, and the Map position add-on is
not read or charged for them. A private advertiser's phone numbers are never delivered, whatever the switch says: Idealista's
phone button does not serve them (`phonesStatus: "not_served_for_private_advertisers"`, not read, never billed). Titles,
descriptions, translations and every other text are delivered exactly
as Idealista serves them, whether the switch is on or off (what an advertiser writes into a text is not rewritten). You are
responsible for using personal data lawfully (GDPR included).

#### When Idealista fails

When Idealista refuses or does not answer after retries, the run still ends normally and its status message says how many calls
Idealista failed, which search pages, ad pages, Listing details reads, agency pages or phone and map position reads could not be
read, that nothing was charged for them, and to try again later. A search page, ad page or agency page that failed also gets a free status row; a failed
add-on leaves its status on the row (`detailsStatus`, `phonesStatus`, `mapStatus`: `not_read`) and is not billed. A search link
Idealista does not have gets a free `search_not_found` row; a link Idealista sends to another page gets a free `search_moved`
row naming that page (the Actor never follows it: it can be a wider area): give the link Idealista shows for your search. When
every connection the run may open is refused (or Idealista Portugal refuses the browser on every try), the run stops there: rows
already delivered stay, and nothing after the stop is delivered or charged; its status message says so.

### API examples

Call it like an API in one HTTP call: the run sync endpoint starts a run, waits for it and answers with the dataset rows (replace
`YOUR_TOKEN`):

```bash
curl -X POST "https://api.apify.com/v2/acts/automation_craft~idealista-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"locations": ["Chamberí, Madrid"], "operation": "rent", "maxPrice": 2500, "rooms": ["2", "3"], "maxItems": 100}'
```

Node.js:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });
const run = await client.actor('automation_craft/idealista-scraper').call({
    startUrls: ['https://www.idealista.it/vendita-case/milano-milano/'],
    includeDetails: true,
    maxItems: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.filter((x) => x.type === 'listing').map((x) => [x.id, x.price, x.details?.energy?.rating]));
```

### What this Actor does not do

- **No France.** idealista.fr is not covered; Spain, Italy and Portugal are.
- **No search by Idealista location id.** Idealista answers a search by location id with an error, so such an entry gets a free
  row with the reason; give the place name, its link part or its link. Every ad read with Listing details carries its own
  location id.
- **No Portuguese postal codes.** Idealista Portugal's place search has none, so a Portuguese postal code in **Places** is refused,
  free, before any browser opens; give the town or parish name or its link. Spanish and Italian postal codes work (`28004` and
  `20121` each delivered listings on runs lqUoSTzSiojCFwtlK and qfmUbyI3V9nWa3Ify).
- **No phone numbers of private advertisers.** Idealista's phone button does not serve them (0 of 6 tries with personal data on);
  private ads get `phonesStatus: "not_served_for_private_advertisers"` and are never billed for it. Agencies' and other
  professionals' numbers are delivered.
- **No private sellers only on Spanish and Portuguese searches other than rooms.** Idealista offers no private filter or private
  first order there and lists professionals first, so `advertiserType: private` is refused with a free reason. Private sellers
  only works on Spanish and Italian rooms (Idealista's own filter) and on every Italian search (its private first order);
  professionals only works everywhere.
- **No newest first order in Spain.** Idealista Spain refuses its date order to automated reads; use **Published within** (last
  24 hours, 48 hours, week or month) for the newest Spanish ads. Italy and Portugal deliver it (Portugal orders by update date).
- **No distance order.** Idealista's search forms have none; every row of a circle search carries
  `derived.distanceFromCentreKm`, so the dataset sorts by it in one step.
- **No price history.** The ad page shows one previous price only: `previousPrice` and `priceDropPercent` are delivered.
- **No IBI property tax.** Idealista shows no IBI line; when an advertiser writes it, it stays in the description. Community fees
  are delivered.
- **No first publication date.** Idealista shows only the last update: `updatedDate`.
- **No postal code of an ad.** The ad page does not show one; agency rows carry their own postal code in `addressLines`.
- **No listing counts per area of an agency.** The agency page lists its areas without counts; the areas are delivered.
- **No views, favourites or contact counts of an ad.** Idealista shows them only to signed in users.
- **No monitoring between runs.** It keeps no memory from one run to the next and does not deliver only new or changed ads; run
  it on a schedule, and give an earlier run's dataset in `datasetId` to read a list of ads again.
- **No agency e-mails.** Agency pages carry a contact form, not an e-mail, and the Actor looks nothing up on agencies' own
  websites; an e-mail an advertiser writes in a description is delivered in `descriptionContacts`.
- **No AI market analysis.** It delivers Idealista's data and a free price summary per search, not yields or forecasts.
- **A run can stop early to protect its margin.** Work that earns nothing is capped (the unpaid work allowance: USD 0.0025 plus 30
  percent of what the run's events earn). Many misses in a row, a very strict filter or very slow answers can end a run with
  `stoppedBy: "work_allowance"` on the summary; nothing is charged for ads not delivered.
- **No login and no captcha solving.** It reads only what Idealista shows any visitor.

### FAQ

#### Is there an Idealista API?

Idealista's own API is for partners it approves. This Actor needs no Idealista account or API key and works as an Idealista API
through Apify: call it with links, places or ad ids and read the rows back as JSON, or pick **Row format** `idealistaApi` for
the field names of Idealista's partner API.

#### Can I export Idealista listings to Excel or CSV?

Yes. Every run's dataset downloads as Excel, CSV, JSON or XML from the Output tab or the API. **Row format** `compact` keeps the
core columns for spreadsheets.

#### Can I get past Idealista's 1,800 results limit?

Yes. Idealista shows at most 60 pages of 30 ads per search; with **Go past the 1,800 ad cap** on (the default) a bigger search is
read in price bands, cheapest first, until every ad was met, and its coverage row says whether it was read to its end.
Holiday rental searches are not split either (Idealista's holiday form filters the price per night, which the bands do not
use): a holiday search over 1,800 ads stops at the cap and its coverage row says so. Searches for premises to rent and for business transfers are the exception: their price filters mix a rent, a transfer amount
and a sale price, so they are left to Idealista and not split into bands; such a search stops at the 1,800 cap and its coverage row
says so.

#### Can I get the agency's phone number?

Yes. **Phone numbers** delivers the numbers of each ad of an agency or other professional (billed per ad that has one), and an
Agency row carries the agency office's own phone, free, where the agency page names an office. Idealista does not serve a private
advertiser's numbers, so private ads get none and are not billed for it.

#### Can I get the price history of an Idealista property?

Only the last change: Idealista's ad page shows the previous price, delivered as `previousPrice` with `priceDropPercent`. To build
a history, run the same search or the same ads (`datasetId`) on a schedule and compare the runs.

#### Why does this Actor run with limited permissions?

Least privilege: it reads and writes only its own run's dataset and key-value store, opens no named store, and reads another
dataset only when you give its id in `datasetId`. Limited permissions keep the rest of your Apify data out of its reach.

### Changelog

- 0.1 (2026-10-28): first release: Idealista Spain, Italy and Portugal by search link, place, Spanish or Italian postal code,
  map area, map pin, whole country, ad id or link, agency, development or dataset; past the 1,800 cap in price bands; seller type
  (private or professional) for every property type; Listing details, Phone numbers, Map position and Agencies add-ons; holiday
  rentals, Italian auctions, business transfers; coverage row and price summary per search; personal data behind its switch.

### More data tools by Automation Craft

- [Zillow Scraper: Homes for Sale, Rent and Sold](https://apify.com/automation_craft/zillow-scraper)
- [SeLoger Scraper: Listings, Prices and Agencies](https://apify.com/automation_craft/seloger-scraper)
- [Bien'ici Scraper: France Real Estate Ads & DPE](https://apify.com/automation_craft/bienici-scraper)
- [PAP Scraper: pap.fr Real Estate Ads & Phones](https://apify.com/automation_craft/pap-scraper)
- [Immowelt Scraper: Rents, Prices and Energy Data](https://apify.com/automation_craft/immowelt-scraper)
- [willhaben Scraper: Immobilien, Cars, Jobs & Ads](https://apify.com/automation_craft/willhaben-scraper)
- [FINN Eiendom Scraper: Norway Homes and Rentals](https://apify.com/automation_craft/finn-eiendom-scraper)
- [Airbnb Scraper: Airbnb Data, Prices, Calendar](https://apify.com/automation_craft/airbnb-scraper)

# Changelog

This Actor's version history is a separate document: https://apify.com/automation_craft/idealista-scraper/changelog.md

# Actor input Schema

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

Links from idealista.com (Spain), idealista.it (Italy) or idealista.pt (Portugal): a search results page (with its own filters, order and page), an ad page (/inmueble/<id>/, /immobile/<id>/, /imovel/<id>/), an agency page (/pro/<name>/), a drawn area (/areas/...?shape=) or a multi area link (/multi/...). Up to 1,000 links.

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

Place names as Idealista writes them ("Chamberí, Madrid", "Milano", "Lisboa"), postal codes ("28004", "20121") or the place part of an Idealista link ("madrid-madrid", "madrid/chamberi"). A name that matches several places, or none, gets a free row listing the site's own candidates. Uses the market, operation, property type, filters and order below.

## `wholeCountry` (type: `boolean`):

Off by default. On, the run searches every province of the chosen country (Spain 52, Italy 107, Portugal 29 districts and islands) with the property type, operation and filters below, each province past the 1,800 ad limit by price bands. Set "maxItems" to what you want to pay for.

## `mapAreas` (type: `array`):

A drawn area as "lat,lng; lat,lng; lat,lng" (3 to 50 points) or a circle as "lat,lng,radiusKm" (0.1 to 50 km). Uses the market, operation, property type, filters and order below.

## `adIds` (type: `array`):

Idealista ad ids (in the market below) or ad links of any market. Each ad is read from its own page and delivered with its full details (billed as Listing details). Gone ads get a free row. Up to 10,000.

## `agencies` (type: `array`):

Agency names as they appear in their Idealista link (/pro/<name>/) or the links themselves. Each gives one Agency row and the agency's own ads (homes for sale) as Listing rows.

## `datasetId` (type: `string`):

The id of a dataset of an earlier run of this Actor (or any dataset whose rows carry an Idealista ad link in "url"): its ads are read again with their full details. Up to 10,000 rows.

## `market` (type: `string`):

The Idealista site of the places, map areas, bare ad ids and agency names. Links carry their own market. Default: Spain.

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

Default: for sale.

## `propertyType` (type: `string`):

Default: homes. Not every type exists in every market and operation; a combination Idealista does not offer refuses the run, free but for the start fee.

## `sortBy` (type: `string`):

Idealista's own orders. Spain does not serve its date order to automated reads: for the newest Spanish ads use "Published within". A search split into price bands to go past the site's 1,800 ad cap is read cheapest first.

## `minPrice` (type: `integer`):

For rent: per month.

## `maxPrice` (type: `integer`):

For rent: per month.

## `minSize` (type: `integer`):

Built size in square metres.

## `maxSize` (type: `integer`):

Built size in square metres.

## `rooms` (type: `array`):

Any of the listed counts. Spain and Portugal count bedrooms; Italy counts rooms (locali).

## `bathrooms` (type: `array`):

Any of the listed counts.

## `homeTypes` (type: `array`):

For homes searches.

## `condition` (type: `array`):

Any of the listed states.

## `floor` (type: `array`):

Any of the listed floors.

## `features` (type: `array`):

Every listed feature must be present (Idealista applies them together).

## `energyEfficiency` (type: `array`):

Idealista's energy certificate bands.

## `occupancy` (type: `array`):

For homes for sale.

## `publishedWithin` (type: `string`):

Idealista's own publication date filter.

## `rentalType` (type: `array`):

For homes for rent.

## `furnishing` (type: `string`):

For homes for rent.

## `auctions` (type: `string`):

Where Idealista offers it (Italy).

## `advertiserType` (type: `string`):

Private advertisers only, or professionals only. Professionals: every property type (each card's own mark is checked; private ads are left out, free). Private: rooms in Spain and Italy (Idealista's own filter) and every Italian search (read in Idealista's private first order, so leave Order empty or set Private first); for other searches in Spain and Portugal Idealista offers no way to find private ads, so private is refused there with a free reason.

## `withFloorPlan` (type: `boolean`):

Only ads with a floor plan.

## `withVirtualTour` (type: `boolean`):

Only ads with a virtual tour.

## `bankOwned` (type: `boolean`):

Only properties sold by banks (Spain and Portugal; Italy has no such filter).

## `siteFilters` (type: `array`):

Any other filter of Idealista's own search form, written as its form field and value, for example "adfilter_hasheating=1" or "adfilter_onlineBooking=1". The README lists them per property type.

## `includeDetails` (type: `boolean`):

Read every delivered ad's own page: full description, every feature line, energy certificate, approximate map position, update date, advertiser, photos with room tags, floor plans and videos. Billed as Listing details per ad.

## `includeAgencies` (type: `boolean`):

One Agency row for every agency met in the run (name, address, ads count, client since, publication quality, website, the areas it covers), once per agency. Billed as Agency.

## `includePhones` (type: `boolean`):

The advertiser's phone numbers of every delivered ad, from the ad page's own phone button. Agencies' and other professionals' numbers; Idealista does not serve a private advertiser's numbers to the Actor, so private ads get none (not read, not billed). Billed as Phone number per ad that has one.

## `includeCoordinates` (type: `boolean`):

The ad's position on Idealista's own map (latitude, longitude) for search rows, from the site's map door (Listing details already carries it). Private advertisers' positions only with personal data on. Billed as Map position per ad.

## `includePersonalData` (type: `boolean`):

Off by default. On, ads of private advertisers also carry the advertiser's first name, the street line, the exact map position and the advertiser's own link as Idealista shows them. You are responsible for a lawful use of personal data (GDPR included).

## `maxItems` (type: `integer`):

The most Listing rows the run delivers in all.

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

The most Listing rows one search delivers.

## `maxPagesPerSearch` (type: `integer`):

Idealista shows at most 60 pages of 30 ads per search. Default 60.

## `splitPastCap` (type: `boolean`):

On by default: a search holding more than 1,800 ads is read in price bands, cheapest first, until every ad was met. Off: the first 1,800 only.

## `language` (type: `string`):

Idealista's own page language for titles, labels and the advertiser's description where Idealista translates it. Default: the market's own language.

## `outputFormat` (type: `string`):

Default: full. "Idealista API field names" writes each listing with the field names of Idealista's own partner API (propertyCode, priceByArea, hasLift and so on), for tools built on that shape.

## `descriptionFormat` (type: `string`):

Default: text with line breaks.

## `descriptionTranslations` (type: `array`):

With Listing details: the advertiser's description in these languages too, as Idealista's own translation offers it (up to 5). No extra charge.

## `descriptionMaxLength` (type: `integer`):

Optional: cut each description to this many characters (the full text otherwise).

## `omitEmptyFields` (type: `boolean`):

Off by default. On, fields with no value are left out of each row instead of written as null.

## `maxConcurrency` (type: `integer`):

Reads in parallel (1 to 4). Default 3.

## `proxyUrls` (type: `array`):

Optional: your own proxy links (http://user:password@host:port), used instead of Apify residential proxies.

## Actor input object example

```json
{
  "startUrls": [
    "https://www.idealista.com/venta-viviendas/madrid/chamberi/"
  ],
  "maxItems": 30
}
```

# Actor output Schema

## `items` (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 = {
    "startUrls": [
        "https://www.idealista.com/venta-viviendas/madrid/chamberi/"
    ],
    "maxItems": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation_craft/idealista-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 = {
    "startUrls": ["https://www.idealista.com/venta-viviendas/madrid/chamberi/"],
    "maxItems": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("automation_craft/idealista-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 '{
  "startUrls": [
    "https://www.idealista.com/venta-viviendas/madrid/chamberi/"
  ],
  "maxItems": 30
}' |
apify call automation_craft/idealista-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation_craft/idealista-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/DlPJSRRi3cjV7cjjF/builds/3GINT6ZKLpi2Zk6pB/openapi.json