# Supercasa.pt Scraper - Portuguese Real Estate Data Extractor (`studio-amba/supercasa-scraper`) Actor

Scrape real estate listings from Supercasa.pt, one of Portugal's leading property portals. Extract prices, addresses, bedrooms, bathrooms, surface area, geo-coordinates, images, and agency details for sale and rental listings across every Portuguese municipality. No login needed.

- **URL**: https://apify.com/studio-amba/supercasa-scraper.md
- **Developed by:** [Studio Amba](https://apify.com/studio-amba) (community)
- **Categories:** Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 result scrapeds

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Supercasa Scraper

Extract real estate listings from [Supercasa.pt](https://supercasa.pt), one of Portugal's leading property portals. This actor pulls prices, addresses, bedrooms, bathrooms, surface area, geo-coordinates, photos, and agency details for houses and apartments for sale or rent, across every Portuguese municipality.

### Why use this actor?

Supercasa covers the full Portuguese market, from Lisbon and Porto to small inland municipalities, with structured data on every listing (not just a headline price and a photo). That makes it useful for market analysis, price-per-m² benchmarking by neighbourhood, relocation research, and lead generation for proptech and real estate agency tools.

Use cases include investment due diligence, competitor tracking for agencies, academic housing studies, and feeding a property search app or price alert tool with fresh Portuguese listings.

### How to scrape Supercasa.pt data

1. Go to the actor's page on the Apify Store
2. Choose a city or municipality (defaults to Lisboa) and listing type (buy or rent)
3. Or paste a Supercasa.pt search URL (e.g. `https://supercasa.pt/comprar/porto`) or individual listing URLs into Start URLs
4. Set Max Results — the actor paginates automatically until it's reached
5. Click "Start" to run the scraper
6. Download results as JSON, CSV, or Excel when complete

The actor fetches pages through Bright Data's Web Unlocker to get past Supercasa's Cloudflare managed challenge (confirmed live even on `/robots.txt`), then extracts data from the site's own embedded schema.org JSON-LD structured data on each listing's detail page — no fragile CSS scraping for the fields that matter most.

### Input

| Field | Type | Required | Description |
|-------|------|----------|--------------|
| `listingType` | String | No | `comprar` (for sale, default) or `arrendar` (for rent) |
| `city` | String | No | City or municipality URL slug, e.g. `lisboa` (default), `porto`, `cascais`, `braga` |
| `startUrls` | Array | No | Supercasa.pt search result pages or individual listing URLs. Overrides City/Listing Type |
| `maxResults` | Integer | No | Maximum listings to return. Search pages return about 28 listings each; the actor paginates automatically |
| `brightDataApiKey` | String | No | Your own Bright Data API key for the Web Unlocker zone. Leave empty to use the built-in unlocking service |

### Output

Each result contains:

| Field | Type | Example |
|-------|------|---------|
| `title` | String | `"Apartamento T3 c/ garagem e arrecadação na Estrada da Luz"` |
| `price` | Number | `735000` |
| `currency` | String | `"EUR"` |
| `listingType` | String | `"sale"` or `"rent"` |
| `propertyType` | String | `"apartamento"`, `"moradia"`, `"terreno"` |
| `address` | String | `"São Domingos de Benfica, Lisboa"` |
| `city` | String | `"Lisboa"` |
| `province` | String | `"Lisboa"` |
| `latitude` / `longitude` | Number | `38.7457466` / `-9.175513` |
| `bedrooms` | Number | `3` |
| `bathrooms` | Number | `2` |
| `surface` | Number | `147` (m²) |
| `imageUrl` | String | Primary listing photo URL |
| `imageUrls` | Array | All listing photo URLs |
| `description` | String | Full listing description text |
| `agencyName` | String | `"Hall Rede Imobiliária"` |
| `agencyUrl` | String | Agency profile URL on Supercasa.pt |
| `supercasaId` | String | `"2195233"` |
| `url` | String | Full Supercasa.pt listing URL |
| `scrapedAt` | String | ISO 8601 timestamp |

### Example output

```json
{
    "title": "Apartamento T3 c/ garagem e arrecadação na Estrada da Luz",
    "price": 735000,
    "currency": "EUR",
    "listingType": "sale",
    "propertyType": "apartamento",
    "address": "São Domingos de Benfica, Lisboa",
    "city": "Lisboa",
    "province": "Lisboa",
    "latitude": 38.7457466,
    "longitude": -9.175513,
    "bedrooms": 3,
    "bathrooms": 2,
    "surface": 147,
    "imageUrl": "https://imagens.supercasa.pt/Z720x540/OAYES/S5/C96/P30032552/Tphoto/IDa842ca01-0000-0500-0000-000019520947.JPG",
    "description": "Apartamento T3 Área bruta 147 m², Apartamento T3 à venda, Apartamento T3 em Estrada da Luz, São Domingos de Benfica, Lisboa",
    "agencyName": "Hall Rede Imobiliária",
    "agencyUrl": "https://supercasa.pt/agencia/3940",
    "supercasaId": "2195233",
    "url": "https://supercasa.pt/venda-apartamento-t3-lisboa/i2195233",
    "scrapedAt": "2026-08-30T09:24:52.291Z"
}
```

### Cost estimate

This actor fetches one Bright Data Web Unlocker request per search page plus one per listing detail page (1 request ≈ 1 result). Approximate costs:

- **~28 results (1 search page)**: $0.02-0.05 in platform credits
- **~280 results (10 search pages)**: $0.20-0.50 in platform credits
- **Individual listing URLs (`startUrls`)**: one Web Unlocker request per listing

Actual usage cost only settles once the run reports SUCCEEDED — reading the dataset from a still-running run will undercount what you'll actually be charged.

### Tips for best results

- **Start small** — test with `maxResults: 20` before running large scrapes.
- **Use `arrendar` for rentals** — the same city/municipality coverage applies to both for-sale and rental listings.
- **City slugs cover every Portuguese municipality** — not just the big cities. Browse supercasa.pt and read the last URL segment of a `/comprar/{slug}` page to find any municipality's slug.
- **Direct listing URLs work too** — paste a `/venda-{type}-{city}/i{id}` or `/arrendar-{type}-{city}/i{id}` URL into Start URLs to scrape a single known listing.

### Limitations

- Supercasa.pt fronts every page with a genuine Cloudflare managed challenge, confirmed even on static paths like `/robots.txt`. This actor routes requests through Bright Data's Web Unlocker to get past it.
- Search-result pages only expose title, price, and a thumbnail — full structured fields (bedrooms, surface, geo-coordinates, agency) come from a follow-up detail-page fetch per listing, so `maxResults` scrapes roughly `maxResults + (pages of search results)` Web Unlocker requests.
- Price reflects Supercasa's own listed asking price, not a guaranteed final sale price.
- The actor scrapes the public website. No login or authentication is used.

### Related scrapers

- [Idealista Scraper](https://apify.com/itsnotyouitsme/idealista-scraper) — Spain and Portugal's leading real estate portal
- [Storia.ro Scraper](https://apify.com/itsnotyouitsme/storia-ro-scraper) — Romanian real estate listings
- [Booli Scraper](https://apify.com/itsnotyouitsme/booli-scraper) — Swedish real estate listings and sold prices
- [Boligsiden Scraper](https://apify.com/itsnotyouitsme/boligsiden-scraper) — Danish real estate listings and sold prices
- [MyHome.ie Scraper](https://apify.com/itsnotyouitsme/myhome-scraper) — Irish real estate listings
- [Morizon Scraper](https://apify.com/itsnotyouitsme/morizon-scraper) — Polish real estate listings

### Need this data on a schedule, or a custom version?

We run this scraper as a managed service for businesses: scheduled runs,
deduplication, delta detection, and delivery to your inbox, Google Sheets,
or API — maintenance included. We can also build a custom version with your
exact fields and filters, or combine multiple sources into one feed.

See [studioamba.dev/services](https://studioamba.dev/services/) or email
<hello@studioamba.dev> for a free data sample.
We maintain 700+ European web scrapers and answer within one business day.

# Actor input Schema

## `listingType` (type: `string`):

Properties for sale (comprar) or for rent (arrendar).

## `city` (type: `string`):

Supercasa.pt city or municipality URL slug, e.g. 'lisboa', 'porto', 'cascais', 'braga'. Find the slug by browsing supercasa.pt and reading the last segment of a /comprar/{slug} or /arrendar/{slug} URL.

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

Supercasa.pt search result pages (e.g. https://supercasa.pt/comprar/lisboa) or individual listing URLs (/venda-{type}-{city}/i{id} or /arrendar-{type}-{city}/i{id}). Overrides City/Listing Type when provided.

## `maxResults` (type: `integer`):

Maximum number of listings to scrape. Search pages return about 28 listings each; the actor paginates automatically until this limit is reached.

## `brightDataApiKey` (type: `string`):

Optional: your own Bright Data API key for the Web Unlocker zone. Leave empty to use the built-in unlocking service.

## `proxyConfiguration` (type: `object`):

Legacy field, kept for backwards compatibility. Fetching now goes through the built-in Bright Data Web Unlocker, so this is ignored.

## Actor input object example

```json
{
  "listingType": "comprar",
  "city": "lisboa",
  "startUrls": [
    {
      "url": "https://supercasa.pt/comprar/lisboa"
    }
  ],
  "maxResults": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (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 = {
    "city": "lisboa",
    "startUrls": [
        {
            "url": "https://supercasa.pt/comprar/lisboa"
        }
    ],
    "maxResults": 5,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("studio-amba/supercasa-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 = {
    "city": "lisboa",
    "startUrls": [{ "url": "https://supercasa.pt/comprar/lisboa" }],
    "maxResults": 5,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("studio-amba/supercasa-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 '{
  "city": "lisboa",
  "startUrls": [
    {
      "url": "https://supercasa.pt/comprar/lisboa"
    }
  ],
  "maxResults": 5,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call studio-amba/supercasa-scraper --silent --output-dataset

```

## MCP server setup

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