# Imovirtual Portugal Rent & Sale Listing Scraper (`crawlyth-forge/imovirtual-portugal-rent-and-sale-listing-scraper`) Actor

Search Imovirtual.com for apartments, houses, land, garages and commercial properties to rent or buy across Portugal, filtered by city, price, area and room count, with agency details, images and location.

- **URL**: https://apify.com/crawlyth-forge/imovirtual-portugal-rent-and-sale-listing-scraper.md
- **Developed by:** [crawlyth forge](https://apify.com/crawlyth-forge) (community)
- **Categories:** Real estate, Lead generation, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 Portugal Rent & Sale Listing Scraper

Imovirtual is one of Portugal's largest real-estate portals. This actor collects its public rent and sale listings: apartments, houses, land, garages, commercial property, offices, warehouses, rooms and new developments. Build a search from a location and filters, use a keyword, or paste Imovirtual search and listing URLs.

### What this actor does

- **Browse rent or sale listings** by location and property type without constructing a URL.
- **Search by keyword** in listing descriptions, such as `piscina`, `varanda` or `garagem`.
- **Scrape your own Imovirtual URLs**: search-result URLs are paginated from page to page, and individual listing URLs produce one record each.
- **Apply the site's own filters** for price, area, typology, features, private-owner status, listing age, build year and building floors, plus sort order.
- **Avoid duplicate rows** when pages, sponsored placements or multiple URLs overlap.
- **Enrich every listing** with its detail page by default: description, bathrooms, energy certificate, construction year, building details, amenities, equipment, GPS coordinates, floor plans and agency contact details.
- **Returns one flat record per listing** with prices as numbers, ISO dates, absolute URLs and omit-empty fields.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `forRent` | `forRent`, `forSale`, `search` or `byUrl`. |
| `propertyType` | select | `apartment` | `any`, `apartment`, `house`, `land`, `garage`, `commercial`, `office`, `warehouse`, `room` or `development`. |
| `transactionType` | select | `rent` | `rent` or `sale`; used by `search` mode. |
| `location` | text | `Lisboa` | Council or city, e.g. `Porto`, `faro`. Use `faro/*` for a whole district and a full path for a parish, e.g. `lisboa/lisboa/benfica`. Empty means all Portugal. |
| `searchQuery` | text | – | Words to find in listing descriptions. Also used by `search` mode. |
| `minPrice` | integer | – | Minimum monthly rent or total sale price in EUR. |
| `maxPrice` | integer | – | Maximum monthly rent or total sale price in EUR. |
| `minArea` | integer | – | Minimum usable area in m2. |
| `maxArea` | integer | – | Maximum usable area in m2. |
| `rooms` | multi-select | `[]` | Typologies to include: `T0`, `T1`, `T2`, `T3`, `T4`, `T5+`. |
| `extras` | multi-select | `[]` | Features to require: private owner, lift, garage, air conditioning, balcony, terrace, photos, internet, garden, cable TV, separate kitchen. |
| `privateOwnerOnly` | boolean | `false` | Keep only private-owner listings. |
| `daysSinceCreated` | select | `any` | `any`, `1`, `3` or `7` days. |
| `buildYearMin` | integer | – | Minimum construction year. |
| `buildYearMax` | integer | – | Maximum construction year. |
| `floorsNumberMin` | integer | – | Minimum number of floors in the building. |
| `floorsNumberMax` | integer | – | Maximum number of floors in the building. |
| `sortBy` | select | `relevance` | `relevance`, `newest`, `oldest`, `priceAsc`, `priceDesc`, `areaAsc` or `areaDesc`. |
| `listingUrls` | string list | `[]` | Imovirtual search or listing URLs for `byUrl` mode. |
| `includeDetails` | boolean | `true` | Open each listing page for the full record. Turn off for faster bulk collection. |
| `maxItems` | integer | `20` | Maximum number of listings to save, up to 50,000. |

#### Example: apartments for rent in Lisbon under EUR 2,000

```json
{
  "mode": "forRent",
  "propertyType": "apartment",
  "location": "Lisboa",
  "maxPrice": 2000,
  "rooms": ["T1", "T2"],
  "sortBy": "priceAsc",
  "maxItems": 100
}
```

#### Example: houses for sale in Porto with three or more bedrooms

```json
{
  "mode": "forSale",
  "propertyType": "house",
  "location": "Porto",
  "rooms": ["T3", "T4", "T5+"],
  "includeDetails": true,
  "maxItems": 50
}
```

#### Example: keyword search for swimming pools in the Algarve

```json
{
  "mode": "search",
  "transactionType": "sale",
  "propertyType": "house",
  "location": "faro",
  "searchQuery": "piscina",
  "maxItems": 50
}
```

#### Example: scrape search and listing URLs directly

```json
{
  "mode": "byUrl",
  "listingUrls": [
    "https://www.imovirtual.com/pt/resultados/arrendar/apartamento/lisboa/lisboa?priceMin=1000&priceMax=1500",
    "https://www.imovirtual.com/pt/anuncio/apartamento-t3-em-areeiro-de-126-00-m2-ID1iXZM"
  ],
  "maxItems": 40
}
```

### Output per listing

- `listingId`, `title`, `listingUrl`
- `propertyType`, `transactionType`, `isDevelopment`, `developmentTitle`, `developmentUrl`
- `price`, `currency`, `pricePerSqm`, `priceType`, `rentPrice`
- `area`, `terrainArea`
- `rooms`, `bedrooms`, `typology`, `floor`, `floorLabel`, `bathrooms`
- `address`, `city`, `council`, `district`, `parish`, `neighborhood`, `postalCode`
- `latitude`, `longitude`
- `energyCertificate`, `buildYear`, `buildingFloors`, `buildingType`, `constructionStatus`, `usageLicense`, `market`, `availableFrom`
- `description`
- `features`, `amenities`, `equipment`, `security`
- `imageUrls`, `imageCount`, `floorPlanUrls`, `videoUrl`, `virtualTourUrl`
- `agencyName`, `agencyId`, `agencyUrl`, `agencyType`, `agencyLicenseNumber`, `agentName`, `advertiserType`, `advertiserAddress`
- `isPrivateOwner`, `isPromoted`, `isExclusiveOffer`, `isCrossListed`, `hasVideo`, `hasVirtualTour`, `hasFloorPlan`
- `dateCreated`, `firstListedAt`, `modifiedAt`, `pushedUpAt`
- `sourceUrl`, `recordType`, `scrapedAt`

Fields a listing does not carry are omitted rather than returned as null or empty.

### Use cases

- Track asking prices and price per square metre across districts, councils and parishes.
- Shortlist rentals by budget, typology and features before contacting agents.
- Collect private-owner listings for lead generation.
- Monitor new listings by listing age and sort order.
- Compare resale and new-development inventory.
- Build a repeatable Portugal housing-market dataset for analysis or valuation models.

### FAQ

**Do I need an account, cookies or an API key?**
No. The actor reads Imovirtual's public listing pages and detail pages without login.

**What is the difference between the modes?**
`forRent` and `forSale` build the search from `location`, `propertyType` and the filters. `search` adds a description keyword and uses `transactionType`. `byUrl` ignores the builder fields and scrapes the URLs you provide.

**Why are some fields missing on some listings?**
Imovirtual only publishes what the seller supplied. A listing without an energy certificate has no `energyCertificate`; a private-owner listing has no agency fields. The actor omits those fields instead of inventing values.

**Why does `rooms` differ from `bedrooms`?**
Imovirtual's room count includes the living room, so a Portuguese T2 usually has `rooms: 3` and `bedrooms: 2`. `typology` gives the familiar T number directly.

**How many listings can one search return?**
The site paginates 36 listings at a time and exposes thousands of pages in broad searches. The actor keeps paging until `maxItems` is reached or the search is exhausted, and removes duplicate listings across pages and URLs.

**How do I search a whole district instead of one council?**
Use a slash and asterisk, e.g. `faro/*` for the Faro district or `lisboa/*` for the Lisbon district. A plain `Lisboa` searches the Lisbon council.

**What does `propertyType: any` do?**
It visits every compatible Imovirtual category in turn and mixes the results: apartments, houses, land, garages, commercial property, offices, warehouses and rooms for rent, or new developments for sale. Rooms are rent-only and developments are sale-only on Imovirtual.

**Does the actor use a proxy?**
It normally connects directly. If Imovirtual blocks a request, it retries and can fall back to Apify Proxy automatically; no proxy setup is required from you.

**Are phone numbers included?**
No. Phone numbers are not part of the public listing data returned by the pages this actor reads.

**Is this affiliated with Imovirtual?**
No. This is an independent, third-party actor that reads publicly available Imovirtual listing pages.

### Limitations

- Some Imovirtual filters (heating type, building type, floor level, availability window and map radius) are not exposed as actor inputs.
- A plain `location` value resolves as a council. Use `faro/*` for a whole district and the site's path form for a parish, e.g. `lisboa/lisboa/benfica`.
- English location aliases are provided for Lisbon and Oporto; other locations should use their Portuguese names.
- Detail fields such as bathrooms, reference ID, build year, floor plans and video are present only when the seller or agency published them.

# Actor input Schema

## `mode` (type: `string`):

How to find listings. Browse rent or sale listings, search by keyword, or paste Imovirtual URLs.

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

Property category. Any type searches every category one by one.

## `transactionType` (type: `string`):

Rent or sale for mode=search. The For rent and For sale modes set this automatically.

## `location` (type: `string`):

City, district, council or parish. Examples: Lisboa, Porto, Faro, lisboa/sintra, lisboa/lisboa/benfica. Leave empty for all Portugal.

## `searchQuery` (type: `string`):

Optional words to find in listing descriptions, e.g. piscina, varanda, garagem. Also used by mode=search.

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

Minimum monthly rent or total sale price in euros.

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

Maximum monthly rent or total sale price in euros.

## `minArea` (type: `integer`):

Minimum usable floor area in square metres.

## `maxArea` (type: `integer`):

Maximum usable floor area in square metres.

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

One or more Portuguese typologies: T0 is a studio, T3 has three bedrooms. Matches any selected value.

## `extras` (type: `array`):

Only return listings with any of these features.

## `privateOwnerOnly` (type: `boolean`):

Skip agency listings and keep only properties posted by private owners.

## `daysSinceCreated` (type: `string`):

Only include listings first published within this period.

## `buildYearMin` (type: `integer`):

Minimum construction year.

## `buildYearMax` (type: `integer`):

Maximum construction year.

## `floorsNumberMin` (type: `integer`):

Minimum number of floors in the building.

## `floorsNumberMax` (type: `integer`):

Maximum number of floors in the building.

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

Order of the results.

## `listingUrls` (type: `array`):

Search result or listing URLs. Search URLs are paginated; listing URLs produce one record each. Examples: https://www.imovirtual.com/pt/resultados/arrendar/apartamento/lisboa/lisboa and https://www.imovirtual.com/pt/anuncio/... .

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

Open each listing page for description, bathrooms, energy certificate, build year, amenities, GPS coordinates and agency details. Turn off for faster bulk runs.

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

Maximum number of listing records to save.

## Actor input object example

```json
{
  "mode": "forRent",
  "propertyType": "apartment",
  "transactionType": "rent",
  "location": "Lisboa",
  "rooms": [],
  "extras": [],
  "privateOwnerOnly": false,
  "daysSinceCreated": "any",
  "sortBy": "relevance",
  "listingUrls": [],
  "includeDetails": true,
  "maxItems": 3
}
```

# Actor output Schema

## `properties` (type: `string`):

Dataset containing all scraped Imovirtual property listings.

# 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 = {
    "mode": "forRent",
    "propertyType": "apartment",
    "transactionType": "rent",
    "location": "Lisboa",
    "rooms": [],
    "extras": [],
    "privateOwnerOnly": false,
    "daysSinceCreated": "any",
    "sortBy": "relevance",
    "listingUrls": [],
    "includeDetails": true,
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlyth-forge/imovirtual-portugal-rent-and-sale-listing-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 = {
    "mode": "forRent",
    "propertyType": "apartment",
    "transactionType": "rent",
    "location": "Lisboa",
    "rooms": [],
    "extras": [],
    "privateOwnerOnly": False,
    "daysSinceCreated": "any",
    "sortBy": "relevance",
    "listingUrls": [],
    "includeDetails": True,
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlyth-forge/imovirtual-portugal-rent-and-sale-listing-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 '{
  "mode": "forRent",
  "propertyType": "apartment",
  "transactionType": "rent",
  "location": "Lisboa",
  "rooms": [],
  "extras": [],
  "privateOwnerOnly": false,
  "daysSinceCreated": "any",
  "sortBy": "relevance",
  "listingUrls": [],
  "includeDetails": true,
  "maxItems": 3
}' |
apify call crawlyth-forge/imovirtual-portugal-rent-and-sale-listing-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlyth-forge/imovirtual-portugal-rent-and-sale-listing-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/PBuY58X41MQGWJZmc/builds/LNFor5LdH4n7klqTp/openapi.json
