# Imovirtual Scraper - Lisbon & Portugal Property Listings (`lukehunter/imovirtual-scraper`) Actor

Scrape Imovirtual property listings in Lisbon, Porto and all of Portugal: apartments for sale or rent with price, price per m2, area, rooms, floor, agency and listing date. Imovirtual alerts for new listings to Discord, Telegram, Slack or any webhook. No login.

- **URL**: https://apify.com/lukehunter/imovirtual-scraper.md
- **Developed by:** [Luke Hunter](https://apify.com/lukehunter) (community)
- **Categories:** Real estate, Lead generation
- **Stats:** 1 total users, 0 monthly users, 98.5% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.50 / 1,000 properties

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 - Lisbon & Portugal Property Listings

**For property investors, estate agencies and anyone relocating to Portugal who needs bulk Imovirtual listings data.** Pick a city or district (or paste your own Imovirtual search URLs) and it returns every property on the results pages - price, price per m², area, rooms, floor, location down to the parish, agency, private-owner flag, listing date and photo - read from Imovirtual's own public search pages. No login, no private-owner personal data. Turn on **new-listing alerts** (`onlyNewSinceLastRun`) and run it on a schedule to get only newly listed properties for a saved search.

Pay-per-result: **$0.0015 per property — 1,000 properties = $1.50.**

### Quick start (1 minute)

1. Open the **Input** tab, leave **Buy or rent** on *Buy* and **Property type** on *Apartments*.
2. Type a **Location** such as `lisboa`, `porto` or `lisboa/cascais`.
3. Click **Start**. Export the dataset to CSV/Excel/JSON, or pull it through the API shown below.

```json
{
  "transaction": "comprar",
  "propertyType": "apartamento",
  "location": "lisboa",
  "maxPagesPerSearch": 1,
  "maxItems": 20
}
```

That prefilled example finishes in well under a minute and costs $0.03.

### How it works

Imovirtual (`imovirtual.com`, a major Portuguese property portal) renders each search results page on the server and embeds the listings in the page itself, so no login or private API is needed. This Actor:

1. Checks Imovirtual's `robots.txt` for the exact path and query of **every** results page before requesting it (`?page=2`, `?page=3`, ...), and skips - without fetching - any page it disallows, saying so in the run's status message.
2. Pages through the results (36 listings per page), stopping at the site's last page, at `maxPagesPerSearch`, or at `maxItems`, whichever comes first.
3. Reads each listing into one flat dataset row. A listing the page shows twice is delivered and charged once.
4. Is polite: about one request every 3 seconds, a plain self-identifying User-Agent, no proxies, no cookies. A block, a challenge page or a changed page layout is reported honestly - never worked around - and you are not charged for a search that returns nothing.

### Use cases

- **Property investors - Portugal property investment data**: pull a city's apartments for sale on a schedule and compare `price`, `pricePerM2` and `areaM2` by `municipality` and `parish` to spot cheap pockets and track price levels over time.
- **Estate agencies - competitor and market monitoring**: see who is listing what in your patch. `agencyName` and `isPrivateOwner` show agency inventory against private sellers, and `createdAt` shows how long listings have been up.
- **Relocating to Portugal - apartment search for expats**: export all apartments in the districts or parishes you are considering into a spreadsheet, sort by price per m², and switch on alerts so a new listing in your target area reaches you the day it appears.

### New-listing alerts: get only new properties

Turn on `onlyNewSinceLastRun` and put this Actor on a **schedule**: every run after the first delivers (and charges for) only properties it hasn't delivered before for that exact search.

1. Set your search as usual, plus alert mode:

```json
{
  "transaction": "comprar",
  "propertyType": "apartamento",
  "location": "lisboa/cascais",
  "maxPagesPerSearch": 3,
  "maxItems": 200,
  "onlyNewSinceLastRun": true
}
```

2. Click **Schedule** on the run page (or **Schedules** in the Apify Console) - once a day is plenty for most searches.
3. **The first scheduled run is a baseline**: it delivers every listing currently on those pages (it is all new to you) and remembers it; you are charged normally for that run. Every run after that only delivers listings it hasn't seen for this exact search.
4. Add a **Webhook** under the schedule's **Integrations** for `ACTOR.RUN.SUCCEEDED`, pointing at Apify's Slack/email integration (or a Zapier/Make step), to be told when a run finds something new.

The status message says what happened: `"First run for 1 search: 108 listing(s) delivered and remembered; next runs return only new ones."`, then `"4 new listing(s) since last run across 1 search (104 already seen)."`. A run that finds nothing new still **succeeds** with an empty dataset - that is the point of the mode.

**Keep alert searches narrow.** An alert only sees the pages the run fetches, and Imovirtual's default order is its own ranking, not strictly newest-first. A municipality or parish (`lisboa/cascais`) or a filtered URL with a few hundred results works well; a whole district with 16,000+ listings does not fit in 10 pages. To watch a broad search, sort it by newest on imovirtual.com, copy that URL into `startUrls`, and keep `maxPagesPerSearch` at 2-3. Each search (the structured one, or each `startUrls` entry) is tracked as its **own watch**, so several saved searches in one task never mix their history.

### Get Imovirtual alerts in Discord, Telegram, Slack, Teams, Google Chat, your phone (ntfy/Pushover) or any app (webhook)

Want a **Imovirtual Discord alert**, a **Imovirtual Telegram bot**, or new listings pushed to Slack, Teams, Google Chat or your phone instead of checking a dataset? Add one or more destinations in the Actor's **Notifications (optional)** section and each run sends the listings it delivered. It is a **monitor that notifies you**: it only reads public Imovirtual search pages and never contacts sellers, buys anything or logs in anywhere, and the messages go only to the places you set up.

| Channel | Fill in | What you get |
|---|---|---|
| Discord | `discordWebhookUrl` | One card per listing, 10 per message |
| Telegram | `telegramBotToken` + `telegramChatId` | Up to 10 listings per message, one line each |
| Slack | `slackWebhookUrl` | Block Kit message, up to 10 listings per message |
| Mattermost, Rocket.Chat | `slackCompatibleWebhookUrl` | Slack-style incoming webhook: a Markdown list (these apps do not render Slack Block Kit) |
| Microsoft Teams | `teamsWebhookUrl` | Adaptive Card from a Teams Workflows webhook, up to 10 listings per card |
| Google Chat | `googleChatWebhookUrl` | Card in a space, up to 10 listings per message |
| ntfy (phone push, no account) | `ntfyTopic` (optional `ntfyServer`, `ntfyToken`) | A push per listing, up to 10, then one "...and N more" |
| Pushover (phone push) | `pushoverUserKey` + `pushoverAppToken` | A push per listing, up to 10, then one "...and N more" |
| Any app: Zapier, Make, n8n, Pipedream, IFTTT, Home Assistant | `webhookUrl` | One JSON POST per run with the delivered rows |

Fill in as many as you like; each channel works on its own and a failing one never stops the others.

#### Setup, channel by channel

- **Discord (1 minute):** Server Settings → Integrations → Webhooks → New Webhook → pick the channel → **Copy Webhook URL**.
- **Telegram (2 minutes):** chat with **@BotFather**, send `/newbot`, paste the token into `telegramBotToken`. Add the bot to the chat or channel (administrator for a channel; for a chat with yourself press **Start** on the bot). `telegramChatId` is a numeric id (`123456789`, or `-1001234567890` for a group or channel) or a public `@channelusername`.
- **Slack:** at api.slack.com/apps create an app (**From scratch**) → **Incoming Webhooks** → switch it on → **Add New Webhook to Workspace** → pick the channel → copy the `https://hooks.slack.com/services/...` URL.
- **Mattermost or Rocket.Chat:** create an **incoming webhook** in the app and paste its public `https://` URL into `slackCompatibleWebhookUrl`. Localhost, private IP addresses and `.local` / `.internal` names are rejected.
- **Microsoft Teams:** in the channel open **... → Workflows** → **Post to a channel when a webhook request is received** → finish the wizard and copy the URL (a host ending in `.logic.azure.com` or `.powerplatform.com`). The old "Office 365 connector" webhooks are retired and not supported.
- **Google Chat:** in the space open **Apps & integrations → Webhooks → Add webhook**, name it and copy the `https://chat.googleapis.com/v1/spaces/...` URL (needs a Google Workspace account that allows webhooks).
- **ntfy (free, no account):** install the ntfy app (or open ntfy.sh), subscribe to a topic with a long random name, and put the same name in `ntfyTopic`. Anyone who knows the topic can read it, so make it unguessable. Own server or a protected topic: set `ntfyServer` (public `https://` address) and `ntfyToken`.
- **Pushover:** copy your user key from pushover.net into `pushoverUserKey`, create an application at pushover.net/apps/build and put its API token in `pushoverAppToken`. Pushover itself is a separate paid app after its trial: check their pricing.
- **Any app (webhook):** paste the catch-hook URL from Zapier, Make, n8n, Pipedream, IFTTT or Home Assistant into `webhookUrl`. It must be a public `https://` address.

#### The recipe: a Imovirtual new-listing alert in five steps

1. Pick a search with `transaction`, `propertyType` and `location`, or paste an imovirtual.com results URL into `startUrls`.
2. Turn on `onlyNewSinceLastRun`, so only listings not delivered before are sent.
3. Add your destination(s) from the table above.
4. Run it once. The first run is the baseline and sends what is currently listed (up to `maxNotifications`).
5. Create a **Schedule** (for example every few hours). From then on you only hear about listings it has not delivered before for that search.

```json
{
  "transaction": "comprar",
  "propertyType": "apartamento",
  "location": "lisboa",
  "onlyNewSinceLastRun": true,
  "maxItems": 100,
  "ntfyTopic": "your-long-random-topic-name",
  "maxNotifications": 25
}
```

#### The generic webhook (`webhookUrl`)

Each run sends **one POST per 100 delivered rows** (so usually one) with this body, followed by whatever your tool does with it:

```json
{
  "source": "apify",
  "actor": "imovirtual-scraper",
  "runId": "HG7ML7M8z78YcAPEB",
  "count": 2,
  "total": 2,
  "part": 1,
  "parts": 1,
  "items": [ { "...": "the full dataset rows" } ]
}
```

`count` is the number of rows in this POST, `total` the number in the run, and `part` / `parts` number the POSTs when a run delivers more than 100 rows. `maxNotifications` does not cap the webhook. Your endpoint should answer with a 2xx status; redirects are not followed and a failure is reported in the run status, never retried in a loop.

#### What to expect

- **What a message contains:** title, price in euro, price per m², floor area, rooms, floor, location, property type, the agency (a private owner is shown only as "Private owner", never by name), the listed date and a photo, plus the link.
- **Only delivered listings are sent.** A run that finds nothing new sends nothing, so there is no "no new listings" spam. Rows the run could not deliver (for example because your spending limit was reached) are not sent.
- **`maxNotifications` (default 25, max 100)** caps how many listings go to chat and phone channels per run (the webhook is not capped). The rest are still in the dataset and the status message says so. ntfy and Pushover send at most 10 individual pushes, then one "...and N more" summary.
- **Cost: notifications are free.** You pay only for delivered listings at the usual price, exactly as without alerts. There is no extra charge for any channel.
- **Failures never fail the run.** A deleted webhook or an unreachable service leaves the run successful and the dataset complete, and the status message says what happened, for example `Notified: Discord 12, Slack 12, ntfy 10 (+summary). Teams failed (HTTP 404) - check the webhook URL.` The logs show the channel name and HTTP status only, never a URL or token.
- **Your URLs, tokens and ntfy topic are stored as secret inputs.** Anyone holding a webhook URL can post to that channel, so treat it like a password.
- **The dataset is unchanged.** The output rows are identical whether or not you set a destination; the run's status message just gains a short note such as `Notified: Discord 12, ntfy 10 (+summary).`
- **It is a monitor that notifies you.** It never contacts sellers, buys anything or logs in to Imovirtual, and the messages go only to the destinations you set up.

### Input

```json
{
  "transaction": "comprar",
  "propertyType": "apartamento",
  "location": "lisboa",
  "startUrls": [],
  "maxPagesPerSearch": 2,
  "maxItems": 100,
  "onlyNewSinceLastRun": false,
  "stateStoreName": "imovirtual-scraper-seen-items"
}
```

| Field | Type | Default | Description |
|---|---|---:|---|
| `transaction` | `"comprar"` | `"arrendar"` | `"comprar"` | Buy or rent. Sale searches are the verified path; rent uses the site's equivalent path (see Limitations). Ignored when `startUrls` is given. |
| `propertyType` | `"apartamento"` | `"apartamento"` | Apartments. For houses, land, commercial or other types, paste that results URL into `startUrls`. Ignored when `startUrls` is given. |
| `location` | string | `"lisboa"` | Location slug path: a district (`lisboa`, `porto`), municipality (`lisboa/cascais`) or parish (`lisboa/cascais/carcavelos-e-parede`); `todo-o-pais` for all of Portugal. Lower-case, hyphens, no accents. |
| `startUrls` | string\[] | *(none)* | Full `https://www.imovirtual.com/pt/resultados/...` URLs to scrape instead of the three fields above. Filters already in the URL are kept; only the page number is added. Up to 50 per run. |
| `maxPagesPerSearch` | integer | 2 | 1-10. Results pages per search, 36 listings each. |
| `maxItems` | integer | 100 | 1-5,000. Hard cap on rows delivered across the whole run - your cost cap. |
| `onlyNewSinceLastRun` | boolean | `false` | New-listing alerts mode - see above. |
| `stateStoreName` | string | `imovirtual-scraper-seen-items` | Name of the store that remembers what each alert search has already delivered. Change it only to isolate several tasks or reset a watch. |
| `discordWebhookUrl` | string (secret) | *(none)* | Discord webhook URL. Must look like `https://discord.com/api/webhooks/<id>/<token>`. Empty means no Discord messages. |
| `telegramBotToken` | string (secret) | *(none)* | Telegram bot token from @BotFather. Needs `telegramChatId`. |
| `telegramChatId` | string | *(none)* | Telegram chat to post to: a numeric chat id or `@channelusername`. The bot must be added to that chat or channel. Needs `telegramBotToken`. |
| `slackWebhookUrl` | string (secret) | *(none)* | Slack incoming webhook, `https://hooks.slack.com/services/...`. |
| `slackCompatibleWebhookUrl` | string (secret) | *(none)* | Mattermost / Rocket.Chat incoming webhook (public `https://` URL; Markdown list, no Block Kit). |
| `teamsWebhookUrl` | string (secret) | *(none)* | Microsoft Teams Workflows webhook (host ending `.logic.azure.com` or `.powerplatform.com`). |
| `googleChatWebhookUrl` | string (secret) | *(none)* | Google Chat space webhook, `https://chat.googleapis.com/v1/spaces/...`. |
| `ntfyTopic` | string (secret) | *(none)* | ntfy topic name; setting it turns ntfy phone pushes on. Pick a long, unguessable name. |
| `ntfyServer` | string | `https://ntfy.sh` | ntfy server. Only change it for your own public `https://` ntfy server. |
| `ntfyToken` | string (secret) | *(none)* | Optional ntfy access token for a self-hosted server or protected topic. Needs `ntfyTopic`. |
| `pushoverUserKey` | string (secret) | *(none)* | Pushover user key. Needs `pushoverAppToken`. |
| `pushoverAppToken` | string (secret) | *(none)* | Pushover application API token. Needs `pushoverUserKey`. |
| `webhookUrl` | string (secret) | *(none)* | Generic JSON webhook (Zapier, Make, n8n, Pipedream, IFTTT, Home Assistant): the delivered rows, 100 per POST. Public `https://` only. |
| `maxNotifications` | integer | 25 | 1–100. Most listings sent to chat and phone channels per run (the webhook is not capped). Extra rows are still in the dataset. Only used when a destination is set. |

### Output fields

| Category | Fields |
|---|---|
| Identity | `id`, `url`, `title` |
| Price | `price`, `currency`, `pricePerM2` |
| Property | `areaM2`, `rooms`, `floor`, `propertyType`, `transaction` |
| Place | `location`, `district`, `municipality`, `parish` |
| Advertiser | `agencyName`, `isPrivateOwner` |
| Listing | `createdAt`, `imageUrl` |
| Search context | `searchUrl` |

Missing values are returned as `null`. Nothing is invented: a listing that hides its price has `price: null`, and `rooms` is Imovirtual's own room count (a listing titled "T2" can be published with 3 rooms).

### Output example

```json
{
  "id": "19061825",
  "url": "https://www.imovirtual.com/pt/anuncio/apartamento-t2-duplex-com-vista-rio-no-beato-em-lisboa-ID1hYQN",
  "title": "Apartamento T2 dúplex com vista rio, no Beato em Lisboa",
  "price": 320000,
  "currency": "EUR",
  "pricePerM2": 3855.42,
  "areaM2": 83,
  "rooms": 3,
  "floor": 3,
  "propertyType": "apartamento",
  "transaction": "comprar",
  "location": "Madre de Deus, Beato, Lisboa, Lisboa",
  "district": "Lisboa",
  "municipality": "Lisboa",
  "parish": "Beato",
  "agencyName": "Casas Rui Pedro",
  "isPrivateOwner": false,
  "createdAt": "2026-03-03T18:22:59Z",
  "imageUrl": "https://ireland.apollo.olxcdn.com/v1/files/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmbiI6InY5cHJrOGhtYTE5czMtRUNPU1lTVEVNIiwidyI6W3siZm4iOiI2OW5scGE3ZWNxbTcxLUFQVCIsInMiOiIxNiIsImEiOiIwIiwicCI6IjEwLC0xMCJ9XX0.HAfuwqZNpGdaGi2KkTbrmsiAfSUGkPnI4_o4v7FtU9Y/image;s=655x491;q=80",
  "searchUrl": "https://www.imovirtual.com/pt/resultados/comprar/apartamento/lisboa"
}
```

### Use it as an API

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("lukehunter/imovirtual-scraper").call(
    run_input={
        "transaction": "comprar",
        "propertyType": "apartamento",
        "location": "porto",
        "maxPagesPerSearch": 3,
        "maxItems": 100,
    }
)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["title"], item["price"], item["areaM2"], item["pricePerM2"])
```

### Pricing and cost control

Pay per delivered property.

**$0.0015 per property — 1,000 properties = $1.50.**

| Properties delivered | Cost |
|---:|---:|
| 20 | $0.03 |
| 1,000 | $1.50 |
| 10,000 | $15.00 |

There is no charge for starting a run, and none for a search that is skipped, blocked or returns nothing. `maxItems` gives you a hard upper bound on cost, and the run's own spending limit is respected row by row.

Notifications to Discord, Telegram, Slack, Teams, Google Chat, ntfy, Pushover and webhooks are free: you pay only for delivered listings, never for messages sent.

### Limitations

- **No private-owner personal data, by design.** Advertiser names, phone numbers, emails and contact forms are never collected. `agencyName` is a business name and is `null` for private owners.
- **Search results pages only.** The Actor does not open individual listing pages, so it does not collect full descriptions, all photos, energy certificates, amenity tags or contact details.
- **No bathrooms, no price history.** The search pages do not publish a bathroom count, and the Actor reports each listing's price as of the run; track changes by scheduling runs and comparing datasets.
- **Rent searches and other property types are less tested.** Our reference captures are apartments for sale in Lisbon. `arrendar` uses the site's equivalent path; if Imovirtual answers that path with an error, the run says so and charges nothing. For houses, land or commercial listings, paste the results URL into `startUrls` - the same listing structure is read, but verify a small run first. Listings with no photo have `imageUrl: null`.
- **Boosted listings appear once.** Imovirtual repeats some promoted listings at the end of a page; those copies are skipped so you are not charged twice.
- **Default order is Imovirtual's own ranking**, not strictly newest-first - see "Keep alert searches narrow".
- **No login, no private API, no bypassing.** If Imovirtual shows a bot-check or block page, the Actor reports it per search and stops that search; it does not evade it.
- **Data use.** Imovirtual's `robots.txt` carries a content signal that does not permit AI-training or AI-input use of its content. This Actor is a data export tool, not an AI crawler, but you are responsible for how you use the data - do not use it to train AI models.
- This is an independent tool, not affiliated with, endorsed by, or connected to Imovirtual or OLX. You are responsible for using the collected data in accordance with Imovirtual's terms and applicable law, including data-protection law.

### Use it from your code, Make, Zapier or n8n

Built for automated pipelines: small runs, stable field names, one row per item, and you pay only for rows actually delivered.

**One API call that runs the Actor and returns the data** (replace `$APIFY_TOKEN` with your token from Apify Console → Settings → Integrations):

```bash
curl -s -X POST "https://api.apify.com/v2/acts/lukehunter~imovirtual-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"transaction": "comprar", "propertyType": "apartamento", "location": "lisboa", "maxPagesPerSearch": 1, "maxItems": 20}'
```

**JavaScript** (`npm i apify-client`):

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('lukehunter~imovirtual-scraper').call({
  "transaction": "comprar",
  "propertyType": "apartamento",
  "location": "lisboa",
  "maxPagesPerSearch": 1,
  "maxItems": 20
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

**Python** (`pip install apify-client`):

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('lukehunter~imovirtual-scraper').call(run_input={"transaction": "comprar", "propertyType": "apartamento", "location": "lisboa", "maxPagesPerSearch": 1, "maxItems": 20})
items = client.dataset(run['defaultDatasetId']).list_items().items
```

**Schedules, webhooks and no-code tools:** save your input as a Task, add a Schedule (e.g. hourly or daily), and attach a webhook or one of the Integrations tab's connectors (Make, Zapier, n8n, Google Sheets, Slack) to push each run's results into your own system.

**Only new items each run:** set `"onlyNewSinceLastRun": true` on a scheduled Task and every run after the first delivers, and charges for, only items it hasn't delivered before for that same input. That makes it a ready-made change feed.

**Reliability:** an automated test runs this Actor's parser against the live site every day, and failures are fixed fast.

**Feedback:** an honest rating on the Store page, good or bad, helps others decide if this Actor fits their needs. Missing a field or found a problem? Open an issue on the Actor page.

### FAQ

#### Does this collect seller or owner information?

Only the business name of an agency or developer, and only when the listing is not a private one. Private owners' names and contact details are never collected - see "Limitations".

#### Can I search a whole city or a single parish?

Yes. Use a district (`lisboa`), a municipality (`lisboa/cascais`) or a parish (`lisboa/cascais/carcavelos-e-parede`) in `location`, or paste any Imovirtual results URL with the filters you want (price range, rooms, ...) into `startUrls`; the filters are kept on every page.

#### Why do I get fewer rows than `maxItems`?

The search ran out of results, hit `maxPagesPerSearch` (36 listings per page), or robots.txt disallowed a later page. The run's status message says which.

#### How do I get alerted to new listings instead of the same ones every time?

Set `onlyNewSinceLastRun: true` and put the Actor on a schedule - see "New-listing alerts" above. The first run delivers everything and remembers it; later runs deliver only what is new.

#### Why does `price` or `floor` come back `null`?

Because Imovirtual did not publish it for that listing - some advertisers hide the price, and floors such as "above tenth" are not a plain number. The Actor never fills a gap with a guess.

#### Can I get Imovirtual alerts by email?

Not natively. There are two routes. (1) Set `webhookUrl` to a Zapier, Make or n8n catch hook and add an email or Gmail step: the webhook delivers the listings as JSON, so the email can list them. (2) Apify's own run integrations and run notifications can email you when a run finishes, but they only send a link to the run or dataset, not the listings themselves. For instant alerts without building anything, Telegram, ntfy or Pushover reach your phone directly.

#### Can I get Imovirtual alerts in WhatsApp?

Not natively, and we do not use unofficial WhatsApp APIs, which risk getting your number banned. The official route is the WhatsApp Business Platform (Cloud API) with its own business account, message templates and pricing: point `webhookUrl` at a Zapier, Make or n8n flow that calls it. For free phone alerts use Telegram or ntfy instead.

### More from this publisher

- **[Zillow ZIP Code Scraper](https://apify.com/lukehunter/zillow-zip-scraper)**: ZIP-code Zillow search results for homes for sale, for rent, and recently sold.
- **[Rightmove Property Scraper](https://apify.com/lukehunter/rightmove-scraper)**: UK property listings from Rightmove search results, with price, address, bedrooms and agent details.
- **[Vinted Scraper](https://apify.com/lukehunter/vinted-scraper)**: Vinted search results with prices, brands, sizes and favourites, across any Vinted country.

# Actor input Schema

## `transaction` (type: `string`):

Whether to search properties for sale ("comprar") or to rent ("arrendar"). Ignored when "Imovirtual search URLs" below are given. Sale searches are the verified path; rent searches use the site's equivalent path and report an error, without charge, if the site has none.

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

Type of property to search. Apartments are built in; for houses, land, commercial or other types, copy that results page's URL from imovirtual.com into "Imovirtual search URLs" below. Ignored when search URLs are given.

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

Imovirtual location slug path: a district such as "lisboa" or "porto", a municipality such as "lisboa/cascais", or a parish such as "lisboa/cascais/carcavelos-e-parede". Use "todo-o-pais" for all of Portugal. Lower-case, hyphens, no accents. Ignored when search URLs are given.

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

Full Imovirtual results URLs to scrape instead of the Buy/Property type/Location fields above, e.g. "https://www.imovirtual.com/pt/resultados/comprar/apartamento/porto?priceMax=300000". Filters already in the URL are kept; only the page number is added. Must be a www.imovirtual.com/pt/resultados/ URL. Maximum 50 per run.

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

How many results pages to fetch for each search, 1-10, default 2. Imovirtual shows 36 listings per page, and the Actor waits about 3 seconds between pages.

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

Hard cap on the number of property rows delivered across all searches, 1-5000, default 100. You are charged $0.0015 per delivered property, so this is your cost cap.

## `onlyNewSinceLastRun` (type: `boolean`):

Turn this on and run the Actor on a schedule to get only properties you haven't seen before: listings already delivered on a previous run for the same search are skipped and never charged again. The first run for a search delivers everything and remembers it; later runs deliver only what is new. Each search is tracked as its own watch. Off by default so a one-off run gets the full current results.

## `stateStoreName` (type: `string`):

Only used when "New-listing alerts" is on. Name of the key-value store that remembers which listings each search has already delivered, so it persists across scheduled runs. Leave as the default unless several Actor tasks must keep separate alert history. Letters, numbers and hyphens only.

## `discordWebhookUrl` (type: `string`):

Post results to a Discord channel. In Discord: Server Settings -> Integrations -> Webhooks -> New Webhook -> choose the channel -> Copy Webhook URL. Example: https://discord.com/api/webhooks/<id>/<token>. Leave empty to skip Discord.

## `telegramBotToken` (type: `string`):

Post results to Telegram. Create a bot by chatting with @BotFather on Telegram (send /newbot) and paste the token it gives you, e.g. 123456789:AA.... Needs "Telegram chat ID" below. Leave empty to skip Telegram.

## `telegramChatId` (type: `string`):

Where the bot should post: a numeric chat id (e.g. 123456789, or -1001234567890 for a group or channel) or a public @channelusername. The bot must be added to that chat or channel first (as an administrator for a channel), and for a private chat you must press Start on the bot. Needs "Telegram bot token" above.

## `slackWebhookUrl` (type: `string`):

Post results to a Slack channel (Block Kit cards, up to 10 per message). Create an incoming webhook at api.slack.com/apps -> Create New App -> Incoming Webhooks -> Add New Webhook to Workspace. Example: https://hooks.slack.com/services/T000/B000/XXXX. Leave empty to skip Slack.

## `slackCompatibleWebhookUrl` (type: `string`):

Post results to a Mattermost or Rocket.Chat incoming webhook, which accept Slack-style webhook payloads. Must be a public https:// address, e.g. https://chat.example.com/hooks/abc123 (no localhost, private IP or .local/.internal hosts). These apps do not render Slack Block Kit, so they get a plain Markdown list. For real Slack use "Slack webhook URL" above. Leave empty to skip.

## `teamsWebhookUrl` (type: `string`):

Post results to a Teams channel as an Adaptive Card. In Teams: channel -> ... -> Workflows -> "Post to a channel when a webhook request is received" -> copy the URL. The host must end in .logic.azure.com or .powerplatform.com, e.g. https://prod-12.westeurope.logic.azure.com/workflows/... The retired Office 365 connector webhooks are not supported. Leave empty to skip Teams.

## `googleChatWebhookUrl` (type: `string`):

Post results to a Google Chat space. In the space: Apps & integrations -> Webhooks -> Add webhook -> copy the URL. Example: https://chat.googleapis.com/v1/spaces/<space>/messages?key=...\&token=.... Leave empty to skip Google Chat.

## `ntfyTopic` (type: `string`):

Get a phone push with no account via ntfy (ntfy.sh). Install the ntfy app, subscribe to a topic name, and enter the same name here. Anyone who knows the topic can read it, so pick a long, unguessable name (letters, numbers, - and \_), e.g. acme-leads-7k2x9q. At most 10 individual pushes per run, then one "...and N more". Leave empty to skip ntfy.

## `ntfyServer` (type: `string`):

Only used with "ntfy topic". Leave as https://ntfy.sh, or enter the public https:// address of your own ntfy server, e.g. https://ntfy.example.com.

## `ntfyToken` (type: `string`):

Only used with "ntfy topic", for a self-hosted server or a reserved topic that needs a login. An access token from ntfy (starts with tk\_, e.g. tk_abc123...). Leave empty for open topics.

## `pushoverUserKey` (type: `string`):

Get a phone push via Pushover. Your user key (30 characters, e.g. uQiRzpo4DXghDmr9QzzfQu27cmVRsG) is shown on the Pushover dashboard (pushover.net). Needs "Pushover app token" below. At most 10 individual pushes per run, then one "...and N more". Leave empty to skip Pushover.

## `pushoverAppToken` (type: `string`):

The API token of a Pushover application you create at pushover.net/apps/build (name it after this Actor), e.g. azGDORePK8gMaC0QOYAMyEEuzJnyUi. Needs "Pushover user key" above.

## `webhookUrl` (type: `string`):

POST the delivered rows as JSON to any public https:// URL: {source, actor, runId, count, items}. At most 100 rows per POST; every delivered row is sent regardless of the max-notifications cap. For example, route results to email, a spreadsheet or any app. Localhost, private IP and .local/.internal addresses are rejected. Leave empty to skip.

## `maxNotifications` (type: `integer`):

Caps how many results are sent to chat and phone channels per run (Discord, Telegram, Slack, Teams, Google Chat, ntfy, Pushover), 1-100, default 25 (e.g. 10). Extra results are still in the dataset. The generic webhook is not capped. Only used when a destination above is set.

## Actor input object example

```json
{
  "transaction": "comprar",
  "propertyType": "apartamento",
  "location": "lisboa",
  "startUrls": [],
  "maxPagesPerSearch": 1,
  "maxItems": 20,
  "onlyNewSinceLastRun": false,
  "stateStoreName": "imovirtual-scraper-seen-items",
  "ntfyServer": "https://ntfy.sh",
  "maxNotifications": 25
}
```

# 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 = {
    "transaction": "comprar",
    "propertyType": "apartamento",
    "location": "lisboa",
    "startUrls": [],
    "maxPagesPerSearch": 1,
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("lukehunter/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 = {
    "transaction": "comprar",
    "propertyType": "apartamento",
    "location": "lisboa",
    "startUrls": [],
    "maxPagesPerSearch": 1,
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("lukehunter/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 '{
  "transaction": "comprar",
  "propertyType": "apartamento",
  "location": "lisboa",
  "startUrls": [],
  "maxPagesPerSearch": 1,
  "maxItems": 20
}' |
apify call lukehunter/imovirtual-scraper --silent --output-dataset

```

## MCP server setup

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