# Imovirtual Scraper (`ribtools/imovirtual-scraper`) Actor

Extract Imovirtual (Portugal) property listings for sale and rent with price, area, rooms and location. Optional add-ons: ad details and agency phones. Proxies included.

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

## Pricing

from $1.99 / 1,000 property data results

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

## Imovirtual Scraper

Extract property listings from **Imovirtual**, one of Portugal's largest real-estate portals. Each listing comes with price, area, rooms, floor, full location and agency, for sale or rent. Optional add-ons fetch the full ad details and agency office phone numbers.

### What is Imovirtual Scraper?

**Imovirtual Scraper** collects property listings from [Imovirtual](https://www.imovirtual.com/), a Portuguese portal for homes, land, commercial property and new developments. You give it starting URLs and it returns structured data for each listing:

- property type, sale or rent, and price (including price per m²)
- area and plot area, rooms and floor
- district, council, parish, neighborhood and street
- the agency or developer, plus promotion and exclusivity flags
- for new developments: delivery date, number of units and the range of unit areas

Two optional add-ons go further. Ad details adds the full description, every photo, map coordinates, the energy certificate and every listed attribute. Seller data adds the agency's or developer's office phone numbers and address.

The scraper handles pagination, retries and data normalization itself, so the dataset is ready to analyze or feed into your systems.

### What can this Actor do?

- **Extract every property type**: apartments, houses, rooms, land, commercial property, warehouses, garages and new developments, for sale and for rent
- **Handle multiple entry points**: searches with any filters, single ad URLs, development URLs, and agency or developer pages
- **Automatic pagination**: crawls through every search result page, 72 properties per page
- **Ad details add-on**: full description, every photo, map coordinates, publication and update dates, bathrooms, build year, energy certificate, features and every listed attribute
- **Seller data add-on**: agency or developer office phone numbers, address and Imovirtual page
- **No duplicates**: each property is returned (and charged) once per run, even when listings move between pages
- **Premium proxies included**: high-quality proxies built in at no additional cost
- **Structured output**: JSON, CSV and Excel formats
- **API integration**: real-time data access through the Apify API
- **Scheduled runs**: automated daily or weekly collection

### What data can Imovirtual Scraper extract?

| Field | Description | Example |
| ----- | ----------- | ------- |
| **ID** | Imovirtual ad identifier | 18910135 |
| **Title** | Ad title | Apartamento, 118 m², Santo António dos Cavaleiros e Frielas |
| **Property Type** | What is for sale or rent | flat, house, room, terrain, commercial_property, hall, garage, investment |
| **Transaction** | Sale or rent | sale, rent |
| **Price** | Asking price or monthly rent in euros, and price per m² | 442500, 3750 |
| **Area** | Usable area and plot area in m² | 118 |
| **Rooms / Floor** | Room count and floor (0 = ground floor) | 4, 2 |
| **Location** | District, council, parish, neighborhood, street | Lisboa, Loures, Santo António dos Cavaleiros e Frielas |
| **Development** | State, delivery, units and unit area range for new developments | ready, 2026-Q4, 4 |
| **Agency** | Seller type, agency or developer name and page | agency, Century 21 Sandra Silva |
| **Flags and tags** | Promoted, exclusive, search highlights | AIR_CONDITIONING, POOL, GARDEN |
| **Media** | Thumbnail, photo count, video and virtual tour links | |
| **Dates** | Original publication and last push-up | 2025-10-15T10:17:33+00:00 |
| **Details** (add-on) | Description, photos, coordinates, energy certificate, attributes | See below |
| **Seller** (add-on) | Agency or developer office phones and address | See below |

### How to scrape Imovirtual

#### Step-by-step tutorial:

1. **Add starting URLs**: paste Imovirtual search, ad, development or agency URLs (see compatible formats below)
2. **Configure options** (optional): turn on the ad details and/or seller data add-ons
3. **Run the scraper**: click "Start" and watch progress in real time
4. **Download results**: export the data as JSON, CSV or Excel

Proxies are included automatically — no setup required.

#### Compatible URL examples:

- **Search for sale**: `https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa`
- **Search for rent**: `https://www.imovirtual.com/pt/resultados/arrendar/moradia/porto`
- **Filtered search (price, rooms, sort)**: `https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa?priceMax=300000&roomsNumber=%5BTWO%5D&by=LATEST&direction=DESC`
- **All of Portugal**: `https://www.imovirtual.com/pt/resultados/comprar/terreno/todo-o-pais`
- **New developments**: `https://www.imovirtual.com/pt/resultados/comprar/empreendimento/todo-o-pais`
- **Single ad**: `https://www.imovirtual.com/pt/anuncio/apartamento-t2-em-estrela-de-116-00-m2-ID1da8C`
- **Single development**: `https://www.imovirtual.com/pt/empreendimento/entroncamento-premium-lote-63-novo-empreendimento-no-entroncamento-ID1iYrF`
- **Agency page (whole inventory, sale and rent)**: `https://www.imovirtual.com/pt/empresas/agencias-imobiliarias/iad-portugal-ID316266`
- **Developer page**: `https://www.imovirtual.com/pt/empresas/promotores-imobiliarios/terrace-benefit-lda-ID5420304`

**Important**: only URLs that match these patterns will work. Search URLs are run exactly as you copied them, with every filter. Imovirtual answers a search for a property type it doesn't recognise with apartments from all of Portugal. The scraper skips such a URL rather than return results you didn't ask for.

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

Imovirtual Scraper uses **pay-per-result (PPR)** pricing: you only pay for properties it successfully extracts.

#### Is scraping Imovirtual free?

The scraper follows Apify's PPR model with the following structure:

- **Base extraction**: one charge per scraped property (price, area, rooms, location, agency)
- **Ad details add-on**: one additional charge per property, only when the details add-on is on and the ad returns data
- **Seller data add-on**: one additional charge per property, only when at least one office phone number is returned. You are never charged it for private owners or for agencies without a published phone.

The scraper keeps compute usage low while maintaining a high success rate. Contact support for volume discounts on large-scale projects.

### Input configuration

The scraper accepts the following inputs:

#### Start URLs

Imovirtual URLs copied from your browser:

- searches for sale (`/pt/resultados/comprar/...`) or rent (`/pt/resultados/arrendar/...`), for any property type and with any filters applied (location, price, area, rooms, sort)
- single ad URLs (`/pt/anuncio/...-ID1da8C`) and development URLs (`/pt/empreendimento/...`)
- agency or developer pages (`/pt/empresas/agencias-imobiliarias/...-ID316266`)

#### Maximum items

Maximum number of properties to scrape (each result is a charged event). Leave empty for no limit.

#### Fetch ad details (add-on)

Opens each ad to add:

- the full description and every photo
- map coordinates and the publication and update dates
- bathrooms, build year and the energy certificate
- features and every listed attribute

Charged per property with details.

#### Fetch seller data (add-on)

Adds the seller profile: the agency's or developer's office phone numbers, address and Imovirtual page. You are charged only when a phone number is returned.

### Output example

```json
{
  "type": "property",
  "id": 18910135,
  "url": "https://www.imovirtual.com/pt/anuncio/apartamento-118-m-santo-antonio-dos-cavaleiros-e-frielas-ID1hlob",
  "title": "Apartamento, 118 m², Santo António dos Cavaleiros e Frielas",
  "property_type": "flat",
  "transaction": "sale",
  "price": 442500,
  "currency": "EUR",
  "price_per_m2": 3750.0,
  "price_from_per_m2": null,
  "area_m2": 118.0,
  "terrain_area_m2": null,
  "rooms": 4,
  "rooms_label": "FOUR",
  "floor": 2,
  "district": "Lisboa",
  "council": "Loures",
  "parish": "Santo António dos Cavaleiros e Frielas",
  "neighborhood": "Santo António dos Cavaleiros",
  "street": "Rua José Monteiro da Rocha",
  "development_state": null,
  "development_delivery": null,
  "development_units": null,
  "development_area_min_m2": null,
  "development_area_max_m2": null,
  "seller_type": "agency",
  "agency_id": 3910917,
  "agency_name": "Century 21 Sandra Silva",
  "agency_url": "https://www.imovirtual.com/pt/empresas/agencias-imobiliarias/century-21-sandra-silva-ID3910917",
  "is_promoted": false,
  "is_exclusive": false,
  "tags": ["AIR_CONDITIONING"],
  "thumbnail": "https://ireland.apollo.olxcdn.com/v1/files/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmbiI6ImUzbDc4bXRtYTZhbjMtRUNPU1lTVEVNIiwidyI6W3siZm4iOiI2OW5scGE3ZWNxbTcxLUFQVCIsInMiOiIxNiIsImEiOiIwIiwicCI6IjEwLC0xMCJ9XX0.D-asPQJxQnZnGwEjZiDDajrE_iOgBMbUsEPWO_QI7Sw/image;s=1280x1024;q=80",
  "photos_count": 15,
  "video_url": null,
  "virtual_tour_url": null,
  "listed_at": "2025-10-15T10:17:33+00:00",
  "bumped_at": "2026-10-06T15:19:24+01:00",
  "details": {
    "description": "A sua nova casa com vista para o futuro!!\n\nDescubra o Aurya Vista, o novo empreendimento situado em Santo António dos Cavaleiros, Loures, onde a modernidade encontra a tranquilidade...",
    "photos": [
      "https://ireland.apollo.olxcdn.com/v1/files/eyJmbiI6ImUzbDc4bXRtYTZhbjMtRUNPU1lTVEVNIiwidyI6W3siZm4iOiI2OW5scGE3ZWNxbTcxLUFQVCIsInMiOiIxNCIsInAiOiIxMCwtMTAiLCJhIjoiMCJ9XX0.mRpRFesxci2E7RRkCHLINX8yBsZPEGtbMPIZAQbJ-Zc/image;s=1280x1024;q=80"
    ],
    "latitude": 38.8175856,
    "longitude": -9.1661561,
    "published_at": "2025-10-15T11:17:33+01:00",
    "updated_at": "2026-10-06T15:19:24+01:00",
    "bathrooms": 2,
    "build_year": 2026,
    "energy_certificate": "exempt",
    "construction_status": "to_completion",
    "building_type": null,
    "features": ["ar condicionado", "elevador"],
    "attributes": {
      "market": "primary",
      "energy_certificate": "exempt",
      "bathrooms_num": "2",
      "floor_no": "floor_2",
      "build_year": "2026",
      "lift": "y",
      "extras_types": "air_conditioning"
    }
  },
  "seller": {
    "type": "agency",
    "id": 3910917,
    "name": "Century 21 Sandra Silva",
    "phones": ["+351210207727"],
    "address": "Rua Abel Manta - 10 B, 2675-614, Odivelas, Lisboa",
    "profile_url": "https://www.imovirtual.com/pt/empresas/agencias-imobiliarias/century-21-sandra-silva-ID3910917"
  }
}
```

This example is shortened: real items carry the full description, every photo and every listed attribute.

The search-only fields (`is_promoted`, `tags`, `photos_count`, `rooms_label`, `development_delivery`, `development_units`, `development_area_min_m2`, `development_area_max_m2`) are empty for single ad and development URLs. `photos_count` is also empty for agency pages.

You can download the dataset extracted by **Imovirtual Scraper** as **JSON, HTML, CSV or Excel**. The data is already cleaned and normalized, ready for analysis tools, databases or business applications.

### Use cases and applications

- **Housing market research**: track asking prices, rents and price per m² by district, council and property type across Portugal
- **Property valuation**: compare comparable listings by area, rooms, floor and energy certificate
- **New-development tracking**: follow developments, their delivery dates, unit counts and price per m²
- **Agency lead generation and monitoring**: build lists of agencies and developers with office phones, or follow an agency's whole inventory on a schedule

### Integrations and API access

Imovirtual Scraper integrates with these platforms:

- **Zapier**: automate data workflows and notifications (via the [Apify Zapier integration](https://docs.apify.com/platform/integrations/zapier))
- **Make (Integromat)**: build multi-step automations (via the [Apify Make integration](https://www.make.com/en/integrations/apify))
- **Google Sheets**: export data directly for analysis
- **REST API**: programmatic access to the extracted data ([instructions here](https://docs.apify.com/academy/api/run-actor-and-retrieve-data-via-api))
- **Python/Node.js SDKs**: integrate the scraper into your applications ([instructions here](https://docs.apify.com/academy/api/run-actor-and-retrieve-data-via-api#javascript-and-python-client))

### FAQ and Support

#### Do I need to configure a proxy?

No. Direct requests to Imovirtual can be blocked, so the Actor includes high-quality proxies automatically at no additional cost. There's nothing to configure.

#### Why are there no phone numbers for private owners or agents?

To protect individuals' privacy under the EU's GDPR, the seller data add-on returns only agency and developer **office** phone numbers. Private owners come back as `type: "private"` with no name and no phone, and they are not charged for the add-on. Individual agents' names and personal mobiles are never returned.

#### Why is a T2 apartment listed with 3 rooms?

`rooms` is Imovirtual's own room count. It includes the living room, so a "T2" (two bedrooms) has 3 rooms. `price` is empty for new developments (the units have their own prices) and for "price on request" ads.

#### How often is the data updated?

Imovirtual updates listings in real time. For fresh data, schedule regular runs or call the API on demand.

#### What if some URLs don't work?

The scraper only supports the Imovirtual URL patterns listed above, and it skips any other URL. That includes searches for a property type Imovirtual doesn't recognise.

#### Do you offer custom solutions?

Yes. We can customize the scraper for specific requirements, extra data points, or integration with your existing systems. Contact us through the Issues tab for enterprise solutions.

#### Need help or have feedback?

- **Report issues**: use the Issues tab for bug reports and feature requests
- **Custom development**: contact us for tailored solutions and enterprise integrations

### Em português

**Imovirtual Scraper** extrai anúncios de imóveis à venda e para arrendar do [Imovirtual](https://www.imovirtual.com/). Cada anúncio inclui:

- tipo de imóvel e preço (incluindo preço por m²)
- área, área de terreno, divisões e andar
- distrito, concelho, freguesia, zona e rua
- a agência ou promotor
- nos empreendimentos: estado, data de entrega, número de frações e áreas

Proxies incluídos, sem configuração.

**URLs aceites:**

- pesquisas de venda (`/pt/resultados/comprar/...`) ou arrendamento (`/pt/resultados/arrendar/...`), de qualquer tipo de imóvel e com quaisquer filtros (localização, preço, área, tipologia, ordenação)
- anúncios individuais (`/pt/anuncio/...-ID1da8C`) e empreendimentos (`/pt/empreendimento/...`)
- páginas de agências e promotores (`/pt/empresas/agencias-imobiliarias/...-ID316266`, `/pt/empresas/promotores-imobiliarios/...`), com todo o inventário de venda e arrendamento

Uma pesquisa com um tipo de imóvel que o Imovirtual não reconhece é ignorada: o site mostraria apartamentos de todo o país em vez da pesquisa pedida.

**Add-ons opcionais:**

- **Detalhes do anúncio**: descrição completa, todas as fotos, coordenadas, datas de publicação e atualização, casas de banho, ano de construção, certificado energético, características e todos os atributos do anúncio. Cobrado por imóvel com detalhes.
- **Dados do vendedor**: telefones de escritório da agência ou do promotor, morada e página no Imovirtual. Por respeito ao RGPD, apenas telefones de empresas. Particulares devolvem `type: "private"`, sem nome nem telefone, e não são cobrados. Os contactos pessoais dos agentes nunca são devolvidos. Cobrado apenas quando é devolvido pelo menos um telefone.

**Notas:**

- Cada imóvel é devolvido (e cobrado) uma só vez por execução.
- `rooms` é a contagem de divisões do Imovirtual: um "T2" tem 3 divisões.
- `price` fica vazio nos empreendimentos e nos anúncios com "preço sob consulta".
- Os campos exclusivos da pesquisa (`is_promoted`, `tags`, `photos_count`, `rooms_label`, `development_delivery`, `development_units`, `development_area_min_m2`, `development_area_max_m2`) ficam vazios nos anúncios e empreendimentos individuais. `photos_count` fica também vazio nas páginas de agências.

# Changelog

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

# Actor input Schema

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

Imovirtual URLs copied from your browser. Search URLs for sale (`/pt/resultados/comprar/...`) or rent (`/pt/resultados/arrendar/...`) of any property type, with any filters applied (location, price, area, rooms, sort), e.g. `https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa?priceMax=300000`. Single ad URLs (`/pt/anuncio/...-ID1da8C`), development URLs (`/pt/empreendimento/...`) and agency or developer pages (`/pt/empresas/agencias-imobiliarias/...-ID316266`) also work.

## `maxRequests` (type: `integer`):

Maximum number of properties to scrape (each result is a charged event). Leave empty for no limit.

## `detailsAddon` (type: `boolean`):

Open each ad to add the full description, every photo, map coordinates, publication and update dates, bathrooms, build year, energy certificate, features and every listed attribute. Charged per property with details.

## `sellerDataAddon` (type: `boolean`):

Add the seller profile: agency or developer office phone numbers, address and Imovirtual page. Phone numbers are returned for agencies and developers only, never for private owners. You are charged only when a phone number is returned.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa"
    }
  ],
  "maxRequests": 10,
  "detailsAddon": false,
  "sellerDataAddon": false
}
```

# Actor output Schema

## `items` (type: `string`):

All scraped properties.

# 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": [
        {
            "url": "https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa"
        }
    ],
    "maxRequests": 10,
    "detailsAddon": false,
    "sellerDataAddon": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("ribtools/imovirtual-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": [{ "url": "https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa" }],
    "maxRequests": 10,
    "detailsAddon": False,
    "sellerDataAddon": False,
}

# Run the Actor and wait for it to finish
run = client.actor("ribtools/imovirtual-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": [
    {
      "url": "https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa"
    }
  ],
  "maxRequests": 10,
  "detailsAddon": false,
  "sellerDataAddon": false
}' |
apify call ribtools/imovirtual-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ribtools/imovirtual-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/LcUz2xRyvvFaF1PwM/builds/OgquGYxcdcWGMab55/openapi.json