# Imovirtual Property Discovery Scraper (`trovevault/imovirtual-property-discovery-scraper`) Actor

Discover public Imovirtual property listings by location, operation, and property type. Extract prices, areas, rooms, seller labels, images, and listing URLs.

- **URL**: https://apify.com/trovevault/imovirtual-property-discovery-scraper.md
- **Developed by:** [Trove Vault](https://apify.com/trovevault) (community)
- **Categories:** Lead generation, Real estate, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.85 / 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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Imovirtual Property Discovery Scraper

Discover public Imovirtual real estate listings from buyer-facing inputs: location, operation, property type, and result limit. The Actor searches Imovirtual for you, then returns structured listing rows with prices, areas, bedrooms, bathrooms, seller labels, public phone numbers when visible, main image, image gallery, features, description, and listing URLs.

This is a discovery Actor. You do not need to provide search result URLs.

### Why Use This Actor

Use this Actor when you need a clean real estate dataset from Imovirtual without manually building search URLs or copying listings from the website.

It is useful for:

- real estate lead discovery by city, region, or country
- market research for sale and rental inventory
- price and area comparison across Portuguese property listings
- agency, investor, and proptech workflows that need listing URLs plus normalized fields
- TroveVault pipelines that combine several property portals into one dataset

### What It Extracts

Each dataset row can include:

- `platform`, `listingId`, `title`, and `url`
- `operation` and `propertyType`
- `price`, `currency`, `priceText`, and `pricePerM2`
- `areaM2`, `bedrooms`, `bathrooms`, `floor`, and `condition`
- `address`, `city`, `region`, `country`, `latitude`, and `longitude` when visible
- `description`
- `features`, such as balcony, terrace, garage, parking, elevator, pool, garden, renovated, or sea view
- `sellerName`, `sellerType`, and `phone` when publicly exposed
- `mainImage` and `images`
- `scrapedAt`
- `runId` when supplied in the input

Fields are only populated when they are publicly visible or can be safely inferred from listing text.

### Input

```json
{
  "location": "Lisbon, Portugal",
  "operation": "sale",
  "propertyType": "apartment",
  "maxItems": 3,
  "datasetId": "",
  "runId": ""
}
````

#### Input Fields

- `location` - City, region, or country to search. City or city plus country is recommended for stable results, for example `Lisbon, Portugal`, `Porto`, or `Faro`.
- `operation` - Dropdown. Use `sale` for properties for sale or `rent` for rental listings.
- `propertyType` - Dropdown. Use `any`, `apartment`, `house`, `land`, or `commercial`.
- `maxItems` - Maximum number of listings to save. Use a small number for quick checks and a larger number for broader discovery.
- `datasetId` - Optional Apify dataset ID. When provided, each saved listing is also appended to that dataset, which is useful when combining several discovery Actors.
- `runId` - Optional workflow run ID. When provided, it is copied into each output row and the `RUN_SUMMARY` key-value record.

### Output Example

```json
{
  "platform": "Imovirtual",
  "listingId": "1i1Nz",
  "title": "Apartamento T4 em Campolide",
  "url": "https://www.imovirtual.com/pt/anuncio/apartamento-t4-em-campolide-ID1i1Nz",
  "operation": "sale",
  "propertyType": "apartment",
  "price": 615000,
  "currency": "EUR",
  "priceText": "615 000 EUR",
  "pricePerM2": 4659.09,
  "areaM2": 132,
  "bedrooms": 4,
  "bathrooms": 2,
  "country": "Portugal",
  "description": "Public listing description when visible.",
  "features": ["terrace"],
  "mainImage": "https://ireland.apollo.olxcdn.com/...",
  "images": ["https://ireland.apollo.olxcdn.com/..."],
  "scrapedAt": "2026-07-19T12:53:00.501Z",
  "runId": "parent-workflow-run"
}
```

### API Usage

```bash
curl -X POST "https://api.apify.com/v2/acts/trovevault~imovirtual-property-discovery-scraper/runs" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"location":"Lisbon, Portugal","operation":"sale","propertyType":"apartment","maxItems":3}'
```

To append the same rows to an existing dataset and tag them with a workflow run:

```bash
curl -X POST "https://api.apify.com/v2/acts/trovevault~imovirtual-property-discovery-scraper/runs" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"location":"Lisbon, Portugal","operation":"sale","propertyType":"apartment","maxItems":50,"datasetId":"YOUR_DATASET_ID","runId":"workflow-2026-07-19"}'
```

### Notes And Limitations

- Use English values for `operation` and `propertyType`; the Actor maps them to Imovirtual search paths internally.
- City-level locations are more precise than whole-country searches.
- Public websites can change layout or temporarily block requests; failed individual listings are skipped and logged instead of failing the entire run.
- Phone numbers are returned only when a visible `tel:` link is exposed by the listing page.
- `mainImage` is the first public content image detected. `images` can contain additional gallery URLs.
- Prices, availability, and listing details can change after scraping. Use `scrapedAt` to judge freshness.
- The Actor does not read search URLs from the input and does not require an upstream dataset for discovery.

### Troubleshooting

- Empty dataset: try a more specific city such as `Lisbon, Portugal` instead of a whole country.
- Fewer results than `maxItems`: the selected combination may have limited visible listings or some pages may not expose enough public data.
- Missing phone: the listing probably hides phone details or requires interaction that is not publicly available in static HTML.
- Missing address or coordinates: Imovirtual does not expose full location details for every listing.
- Slow run: lower `maxItems` for quick validation, then increase it for broader discovery.

### Related Actors

- CASA SAPO Property Discovery Scraper
- Other TroveVault real estate discovery Actors as they are added

### Changelog

- `0.1` - Initial Imovirtual discovery Actor with dropdown operation/property type, optional pipeline IDs, GitHub-backed Apify source, and low-cost default test input.

# Actor input Schema

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

City, region, or country to search. Use English names when possible, for example Lisbon, Portugal; Porto; Madrid; United States. City-level searches are usually more precise and stable than whole-country searches.

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

Choose whether to discover properties offered for sale or for rent.

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

Choose the type of property to discover. Use Any to return the broadest listing set supported by Imovirtual.

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

Maximum number of property listings to return. Use smaller values for quick checks and higher values for broader market discovery.

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

Optional Apify dataset ID to append each saved listing to, in addition to this run's default dataset. Use this when chaining multiple discovery actors into one shared dataset.

## `runId` (type: `string`):

Optional external or Apify run ID copied into each output row and RUN\_SUMMARY. Use this to trace listings back to a parent workflow run.

## Actor input object example

```json
{
  "location": "Lisbon, Portugal",
  "operation": "sale",
  "propertyType": "apartment",
  "maxItems": 3
}
```

# Actor output Schema

## `dataset` (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 = {
    "location": "Lisbon, Portugal"
};

// Run the Actor and wait for it to finish
const run = await client.actor("trovevault/imovirtual-property-discovery-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 = { "location": "Lisbon, Portugal" }

# Run the Actor and wait for it to finish
run = client.actor("trovevault/imovirtual-property-discovery-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "location": "Lisbon, Portugal"
}' |
apify call trovevault/imovirtual-property-discovery-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=trovevault/imovirtual-property-discovery-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Imovirtual Property Discovery Scraper",
        "description": "Discover public Imovirtual property listings by location, operation, and property type. Extract prices, areas, rooms, seller labels, images, and listing URLs.",
        "version": "0.1",
        "x-build-id": "uWG4BSLSTph0qRLhs"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/trovevault~imovirtual-property-discovery-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-trovevault-imovirtual-property-discovery-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/trovevault~imovirtual-property-discovery-scraper/runs": {
            "post": {
                "operationId": "runs-sync-trovevault-imovirtual-property-discovery-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/trovevault~imovirtual-property-discovery-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-trovevault-imovirtual-property-discovery-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "location",
                    "operation",
                    "propertyType"
                ],
                "properties": {
                    "location": {
                        "title": "Location",
                        "type": "string",
                        "description": "City, region, or country to search. Use English names when possible, for example Lisbon, Portugal; Porto; Madrid; United States. City-level searches are usually more precise and stable than whole-country searches.",
                        "default": "Lisbon, Portugal"
                    },
                    "operation": {
                        "title": "Operation",
                        "enum": [
                            "sale",
                            "rent"
                        ],
                        "type": "string",
                        "description": "Choose whether to discover properties offered for sale or for rent.",
                        "default": "sale"
                    },
                    "propertyType": {
                        "title": "Property Type",
                        "enum": [
                            "any",
                            "apartment",
                            "house",
                            "land",
                            "commercial"
                        ],
                        "type": "string",
                        "description": "Choose the type of property to discover. Use Any to return the broadest listing set supported by Imovirtual.",
                        "default": "apartment"
                    },
                    "maxItems": {
                        "title": "Maximum Items",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum number of property listings to return. Use smaller values for quick checks and higher values for broader market discovery.",
                        "default": 3
                    },
                    "datasetId": {
                        "title": "Dataset ID",
                        "type": "string",
                        "description": "Optional Apify dataset ID to append each saved listing to, in addition to this run's default dataset. Use this when chaining multiple discovery actors into one shared dataset."
                    },
                    "runId": {
                        "title": "Run ID",
                        "type": "string",
                        "description": "Optional external or Apify run ID copied into each output row and RUN_SUMMARY. Use this to trace listings back to a parent workflow run."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```