# KW Portugal Scraper - Portuguese Property Listings (`studio-amba/kwportugal-scraper`) Actor

Scrape property listings from Keller Williams Portugal (kwportugal.pt). Houses, apartments, land and commercial for sale and rent with price, size, rooms, energy rating, coordinates, agent, agency and photos.

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

## Pricing

from $1.20 / 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.
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

## KW Portugal Scraper

Scrape property listings from Keller Williams Portugal (kwportugal.pt). Each listing comes back as one structured row: title, reference, sale or rent, property type, price, usable area, bedrooms, bathrooms, energy rating, district, municipality, parish, postal code, coordinates, agent, agency, description, features and photos.

### Why use this actor?

- Covers every listing on kwportugal.pt: houses, apartments, land, commercial and luxury, for sale and for rent.
- Gives coordinates and postal code for most listings, so listings can be placed on a map.
- Gives price, usable area and a price per square metre.
- Filters on sale or rent, property type, district, municipality and price.
- Plain HTTP requests. No browser, so runs are fast and cheap.

### How to scrape KW Portugal data

1. Open the actor and leave the prefill (district Lisboa) or enter your own filters.
2. Set `maxResults` to the number of listings you want.
3. Optionally choose sale or rent, a property type, a municipality or a price range.
4. Start the run and download the dataset as JSON, CSV or Excel.

District, municipality and property type are written the way they appear in kwportugal.pt addresses, without accents: `Lisboa`, `Setubal`, `Porto`, `Faro`, `Apartamento`, `Moradia`. Leave all filters empty to read the whole site, which is about 20,000 listings.

### Input

| Field | Description |
|---|---|
| `businessType` | `sale` or `rent`. Empty reads both. |
| `propertyType` | Property type as in the listing address, for example `Apartamento`, `Moradia`, `Terreno`. Empty reads all types. |
| `district` | District (distrito), for example `Lisboa`, `Porto`, `Faro`, `Setubal`. Empty reads all of Portugal. |
| `municipality` | Municipality (concelho), for example `Cascais`, `Oeiras`, `Sintra`. |
| `minPrice`, `maxPrice` | Price range in euro. Listings without a public price are left out when a price filter is set. |
| `maxResults` | Maximum number of rows. Default 50, maximum 30000. |
| `proxyConfiguration` | Apify Proxy settings. Datacenter addresses work. |

The actor reads the site's own listing sitemaps and then opens each listing page. The filters on sale or rent, type, district and municipality are applied to the listing address before a page is opened, so a narrow filter does not read the whole site.

### What you get back

| Field | Description |
|---|---|
| `listingId`, `reference` | The numeric id and the reference of the listing, for example `1207-2113`. |
| `url`, `title`, `description` | The listing address, headline and full text. |
| `businessType` | `sale` or `rent`. |
| `category`, `propertyType`, `propertySubType` | Residential or commercial, and the type such as apartment or house. |
| `condition` | New, used or similar, as stated by the agent. |
| `price`, `currency`, `priceStatus` | The price in euro. When the site shows a status instead of a price (for example `Reservado`), `price` is empty and `priceStatus` holds the status. |
| `bedrooms`, `bathrooms` | Counts as stated. |
| `usableAreaM2`, `areas` | Usable area in square metres. `areas` holds every area line shown on the page. |
| `pricePerSqm` | Price divided by usable area, rounded. |
| `energyRating` | Energy certificate class, for example `C`. |
| `district`, `municipality`, `parish`, `street`, `postalCode` | Address fields. The street is only filled when the agent shows it. |
| `latitude`, `longitude` | Coordinates. |
| `agentName`, `agentUrl`, `agentPhone`, `agency` | The listing agent and the Keller Williams market centre. |
| `rooms`, `features` | Room list and feature list as shown on the page, such as garage or air conditioning. |
| `videoUrl`, `imageUrl`, `imageUrls` | Video link and photos. |
| `scrapedAt` | Time of the run. |

### Example output

```json
{
  "listingId": "486",
  "reference": "KWPT-002875",
  "url": "https://www.kwportugal.pt/pt/Imovel/Venda/Predio/Lisboa/Lisboa/Arroios/486/KWPT-002875",
  "title": "Prédio de Interesse Municipal | 8 Apartamentos +",
  "businessType": "sale",
  "category": "Residêncial",
  "propertyType": "Prédio",
  "propertySubType": "Prédio habitacional",
  "condition": "Para recuperar",
  "price": 2999000,
  "currency": "EUR",
  "bedrooms": null,
  "bathrooms": null,
  "usableAreaM2": 839,
  "pricePerSqm": 3574,
  "energyRating": "F",
  "district": "Lisboa",
  "municipality": "Lisboa",
  "parish": "LISBOA",
  "street": null,
  "postalCode": "1150-046",
  "latitude": 38.73162,
  "longitude": -9.13514,
  "agentName": "Agent name",
  "agentUrl": null,
  "agentPhone": "+351 9xx xxx xxx",
  "agency": "KW Select",
  "description": "Óptima Localização! Edifício de características Singulares e Exclusivas! Junto à icónica Cervejaria Portugália, encontramos este Edifício Ce...",
  "areas": {
    "área útil": 839
  },
  "priceStatus": null,
  "rooms": [
    "Quarto",
    "Geral"
  ],
  "features": [
    "Proximidade",
    "Aeroporto",
    "Auto-Estrada",
    "Transportes Públicos",
    "Escola/Colégio",
    "Hospital/Centro de Saúde",
    "Polícia",
    "Bombeiros",
    "Banco",
    "Serviços públicos",
    "Farmácia",
    "Praia",
    "Ginásio",
    "Comércio/ Supermercados",
    "Jardim",
    "Estacionamento público",
    "Universidade"
  ],
  "videoUrl": "https://youtu.be/YR0SSWy88Mg?feature=shared",
  "imageUrl": "https://soukwimgsprod.s3.eu-central-1.amazonaws.com/property/2026/486/fb051cf3-ae67-42fb-9acc-973fd16f90fc.jpg",
  "imageUrls": [
    "https://soukwimgsprod.s3.eu-central-1.amazonaws.com/property/2026/486/fb051cf3-ae67-42fb-9acc-973fd16f90fc.jpg",
    "https://soukwimgsprod.s3.eu-central-1.amazonaws.com/property/2026/486/b18a4a18-45a0-4ef2-837c-93f9f32efc8d.jpg"
  ],
  "scrapedAt": "2026-11-12T15:05:33.710Z"
}
```

### Use cases

- Track asking prices per municipality and per postal code.
- Compare price per square metre between districts.
- Watch new listings every day with a schedule.
- Map supply with the coordinates.
- Build a Portuguese property dataset next to other portals and brokers.
- Feed a valuation model or a market report.

### Cost and speed

Each listing is one result row and is billed as one result. The price per result is on the actor page. Every listing needs its own page request, so 100 listings take about one minute and a full read of the site takes a few hours. The usage cost of a run only settles after the run has finished successfully.

### Notes and limits

- The actor reads the listing sitemaps and the listing pages of the site. The search pages are not used.
- Sale or rent, type, district and municipality are matched against the listing address. Write them without accents, as in the address.
- A price filter is applied after a page is read, so a narrow range on a large area reads many pages.
- Some listings show a status such as `Reservado` instead of a price. They have no `price`, and a price filter leaves them out.
- `street`, `usableAreaM2`, `rooms` and `features` are only filled when the agent gives them.
- Descriptions are written by the agents, in Portuguese or English.
- The agent name, phone and market centre are the business contact details shown on the listing.
- A filter with no matching listing ends the run as SUCCEEDED with no rows.
- The actor reads publicly visible data only. It does not log in.
- You are responsible for how you use the data. Check the site's terms and the rules that apply to your use case.

### Frequently asked questions

#### How do I read one district?

Set `district`, for example `Lisboa`. Districts with accents are written without them, for example `Setubal`.

#### How do I read only rentals?

Set `businessType` to `rent`.

#### How do I read only apartments?

Set `propertyType` to `Apartamento`. Use `Moradia` for houses.

#### Why is the price empty on some listings?

The site shows a status such as `Reservado` for those listings. The status is in `priceStatus`.

#### Do I get the full description?

Yes. Every row has the full listing text and the photo links.

#### How often can I run it?

As often as you like. A scheduled run with a small `maxResults` gives a feed of listings.

### Related scrapers

- [RE/MAX Portugal Scraper](https://apify.com/studio-amba/remax-pt-scraper) for RE/MAX listings in Portugal
- [Century 21 Portugal Scraper](https://apify.com/studio-amba/century21-pt-scraper) for Century 21 listings in Portugal
- [ERA Portugal Scraper](https://apify.com/studio-amba/era-pt-scraper) for ERA listings in Portugal

# Actor input Schema

## `businessType` (type: `string`):

Sale (Venda) or rent (Arrendamento). Leave empty for both.

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

Optional. Type as in the listing address, for example Apartamento, Moradia, Terreno, Loja. Leave empty for all types.

## `district` (type: `string`):

Optional. District (distrito) as in the listing address, for example Lisboa, Porto, Faro, Setubal. Leave empty for all of Portugal.

## `municipality` (type: `string`):

Optional. Municipality (concelho), for example Cascais, Oeiras, Sintra. Leave empty for all municipalities.

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

Only listings priced at or above this amount. Listings without a public price (reserved or on request) are left out when a price filter is set.

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

Only listings priced at or below this amount.

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

Maximum number of listings to return. Capped at 30000 per run.

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

The site answers plain requests. The automatic Apify proxy is the default.

## Actor input object example

```json
{
  "district": "Lisboa",
  "maxResults": 20,
  "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 = {
    "district": "Lisboa",
    "maxResults": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("studio-amba/kwportugal-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 = {
    "district": "Lisboa",
    "maxResults": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("studio-amba/kwportugal-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 '{
  "district": "Lisboa",
  "maxResults": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call studio-amba/kwportugal-scraper --silent --output-dataset

```

## MCP server setup

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