# Idealista Real Estate Listing Scraper (Portugal)

Collect Idealista.pt property listings from search results pages: title, price, typology, area, features, description excerpt, and listing URL, with page-by-page pagination.

- Template page: [https://www.octoparse.com/template/idealista-real-estate-listing-scraper-portugal](https://www.octoparse.com/template/idealista-real-estate-listing-scraper-portugal)
- Categories: Real Estate
- Status: `PUBLISHED`
- Run mode: `CLOUD`

## Pricing

Current price: **$0.04/1,000 lines**. Billing is based on output rows; an Octoparse subscription may be required.

## What is an Octoparse template?

An Octoparse template is a ready-to-use scraping workflow with predefined inputs and structured outputs. Use the exact parameter keys below; do not invent parameters.

## Overview

This ready-to-use template collects structured data from listing pages.

## Output

The current workflow extracts 10 fields, including `Descrição`, `Operação`, `Outras_características`, `Preço`, `Timestamp`, `Tipologia`, `Título`, `URL`, `URL_inserido`, `Área`.

## Use Cases

- Use structured results for research, comparison, and monitoring.
- Collect rows without building the extraction workflow from scratch.
- Combine results with other templates for downstream enrichment.
- Review a representative result before starting a large batch.

## Why Octoparse

- **No coding required:** complete List Page URL, Number of pages and start the template in cloud mode.
- **Flexible export:** review and export results as CSV, Excel, or JSON.

## Input

### List Page URL

Required. the URLs of the search results pages on Idealista.pt Constraints: minItems=1; maxItems=2000; items.minLength=1; items.maxLength=10000.

### Number of pages

Optional. Max 100 pages Constraints: minimum=1, maximum=100.

## How to Use

# Idealista Real Estate Listing Scraper (Portugal)

Collect property listings from Idealista.pt search results pages. Returns one row per listing: title, price, typology, area, extra features, description excerpt, and listing URL.

## Input

- **List Page URL**: One or more Idealista.pt search results URLs, one per line. Max 2,000 per task. Example: `https://www.idealista.pt/comprar-casas/caldas-da-rainha/`.
- **Number of pages**: 1–100 per URL. Defaults to 10 when blank. Stops earlier if no more pages. Each page ≈ 30 listings.

## Output Fields

| Field | Description |
|-------|-------------|
| `URL_inserido` | The search URL you submitted |
| `Operação` | Operation shown on page (e.g. `Comprar`) |
| `Título` | Listing title |
| `URL` | Detail page URL of the listing |
| `Preço` | Price (e.g. `365.000€`) |
| `Tipologia` | Property type (e.g. `T3`) |
| `Área` | Area (e.g. `212 m² área bruta`) |
| `Outras_características` | Extra features (e.g. `Garagem incluída`) |
| `Descrição` | Description excerpt shown on the result card |
| `Timestamp` | Collection date and time |

## Pricing

$0.04 per 1,000 output lines (~$0.00004 per line).

## How to Use

1. Open the template and click **Try it!**.
2. Paste one or more Idealista.pt search results URLs into **List Page URL**.
3. Optionally set **Number of pages**.
4. Start the task (runs in cloud).
5. Review collected rows.
6. Export data in your preferred format.

## Limitations

- Only `idealista.pt` URLs are accepted. Other sites return no rows.
- `Descrição` is the card excerpt, not the full listing text. Use Idealista Real Estate Detail Scraper (Portugal) for full details.
- `Outras_características` is empty if no extra features on the card.
- Idealista may block automated access. The template retries automatically; a persistently blocked URL yields no rows and the task is reported as failed. Already collected rows from other URLs are kept.
- A search with no results returns no rows and does not count as failure.
- Runs in cloud only.

## Tips

- Apply filters (location, price, property type) on Idealista.pt first, then copy the results URL.
- Remove duplicate URLs before starting.
- Start with a small Number of pages for testing, then increase.
- Use the `URL` field as input for Idealista Real Estate Detail Scraper (Portugal) to get full property details.

## Limitations

Results depend on what the source site exposes at run time. Fields may be empty when a source page does not provide a value. The template enforces the input limits shown above.

## Tips

Use specific, valid inputs and review a representative result before starting a large batch. Remove duplicate inputs when repeated records are not needed.

## FAQ

### What do I need to enter?

Use the exact inputs and limits listed above.

### What data does this template return?

See Output Schema below; availability can vary by source record.

### How is usage billed?

See the Pricing section above for current pricing and billing details.

## Related Templates

- [Idealista Real Estate Detail Scraper (Portugal)](https://www.octoparse.com/template/idealista-real-estate-detail-scraper-portugal)
- [Idealista Real Estate Listing Scraper (Italy)](https://www.octoparse.com/template/crawler-lista-immobili-idealista)
- [Idealista Real Estate Detail Scraper (Italy)](https://www.octoparse.com/template/crawler-dettagli-immobili-idealista)
- [Immobiliare Real Estate Listing Scraper (Local Only)](https://www.octoparse.com/template/crawler-lista-immobili-immobiliare)
- [Gumtree Scraper (Real Estate Listing)](https://www.octoparse.com/template/gumtree-scraper-real-estate-listing)

## Input Schema

```json
{
  "title": "Idealista Real Estate Listing Scraper (Portugal) input",
  "description": "Input parameters configured for the current published template version.",
  "type": "object",
  "schemaVersion": 1,
  "additionalProperties": false,
  "properties": {
    "list_Page_URL": {
      "title": "List Page URL",
      "description": "the URLs of the search results pages on Idealista.pt",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10000
      },
      "minItems": 1,
      "maxItems": 2000,
      "x-octoparse": {
        "apiEnabled": true
      }
    },
    "number_of_pages": {
      "title": "Number of pages",
      "description": "Max 100 pages",
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "x-octoparse": {
        "apiEnabled": true
      }
    }
  },
  "required": [
    "list_Page_URL"
  ]
}
```

## Input JSON Example

Example 1

```json
{
  "list_Page_URL": [
    "https://www.idealista.pt/comprar-casas/lisboa/"
  ],
  "number_of_pages": 5
}
```

Example 2

```json
{
  "list_Page_URL": [
    "https://www.idealista.pt/comprar-casas/lisboa/"
  ],
  "number_of_pages": 10
}
```

Example 3

```json
{
  "list_Page_URL": [
    "https://www.idealista.pt/comprar-casas/lisboa/"
  ],
  "number_of_pages": 10
}
```

Example 4

```json
{
  "list_Page_URL": [
    "https://www.idealista.pt/comprar-casas/caldas-da-rainha/",
    "https://www.idealista.pt/arrendar-quartos/lisboa/"
  ],
  "number_of_pages": 2
}
```

Example 5

```json
{
  "list_Page_URL": [
    "https://www.idealista.pt/comprar-terrenos/caldas-da-rainha/",
    "https://www.idealista.pt/arrendar-quartos/lisboa/",
    "https://www.idealista.pt/comprar-garagens/porto/"
  ],
  "number_of_pages": 1
}
```


## Output Schema

```json
{
  "schemaVersion": 1,
  "type": "object",
  "properties": {
    "Descrição": {
      "type": "string",
      "description": ""
    },
    "Operação": {
      "type": "string",
      "description": ""
    },
    "Outras_características": {
      "type": "string",
      "description": ""
    },
    "Preço": {
      "type": "string",
      "description": ""
    },
    "Timestamp": {
      "type": "string",
      "description": ""
    },
    "Tipologia": {
      "type": "string",
      "description": ""
    },
    "Título": {
      "type": "string",
      "description": ""
    },
    "URL": {
      "type": "string",
      "description": ""
    },
    "URL_inserido": {
      "type": "string",
      "description": ""
    },
    "Área": {
      "type": "string",
      "description": ""
    }
  },
  "title": "Idealista Real Estate Listing Scraper (Portugal) output",
  "description": "Initial output fields derived from the current published implementation. Field descriptions are maintained by Data Center; production field names and types should be refreshed from recent successful runs.",
  "additionalProperties": false
}
```

## Output Example

Example 1

```json
{
  "Descrição": "T2 com logradouro nas Avenidas Novas | Exterior privado e elevada procura DESCRIÇÃO T2 com logradouro privado no Quartier 100, um edifício exclusivo de apenas 5 apartamentos novos nas Avenidas Novas. Um ativo que combina qualidade de vida, liquidez e potencial de valorização numa das zonas mais procuradas de Lisboa. Exterior privativo •Logradouro exclusivo — espaço raro em contexto urbano •Ideal para uso próprio ou valorização em arrendamento •Extensão natural da zona social Características do imóvel •Sala ampla com boa luminosidade •2 quar",
  "Operação": "Comprar",
  "Outras_características": "Garagem incluída; Rés do chão sem elevador",
  "Preço": "660.000€",
  "Timestamp": "2026-10-26 01:51:18",
  "Tipologia": "T2",
  "Título": "Apartamento T2 na Rua da Beneficência, 100, Entrecampos, Avenidas Novas",
  "URL": "https://www.idealista.pt/imovel/34665653/",
  "URL_inserido": "https://www.idealista.pt/comprar-casas/lisboa/",
  "Área": "151 m² área bruta"
}
```

Example 2

```json
{
  "Descrição": "T2 com logradouro nas Avenidas Novas | Exterior privado e elevada procura DESCRIÇÃO T2 com logradouro privado no Quartier 100, um edifício exclusivo de apenas 5 apartamentos novos nas Avenidas Novas. Um ativo que combina qualidade de vida, liquidez e potencial de valorização numa das zonas mais procuradas de Lisboa. Exterior privativo •Logradouro exclusivo — espaço raro em contexto urbano •Ideal para uso próprio ou valorização em arrendamento •Extensão natural da zona social Características do imóvel •Sala ampla com boa luminosidade •2 quar",
  "Operação": "Comprar",
  "Outras_características": "Garagem incluída; Rés do chão sem elevador",
  "Preço": "660.000€",
  "Timestamp": "2026-10-09 08:47:36",
  "Tipologia": "T2",
  "Título": "Apartamento T2 na Rua da Beneficência, 100, Entrecampos, Avenidas Novas",
  "URL": "https://www.idealista.pt/imovel/34665653/",
  "URL_inserido": "https://www.idealista.pt/comprar-casas/lisboa/",
  "Área": "151 m² área bruta"
}
```

Example 3

```json
{
  "Descrição": "T2 com logradouro nas Avenidas Novas | Exterior privado e elevada procura DESCRIÇÃO T2 com logradouro privado no Quartier 100, um edifício exclusivo de apenas 5 apartamentos novos nas Avenidas Novas. Um ativo que combina qualidade de vida, liquidez e potencial de valorização numa das zonas mais procuradas de Lisboa. Exterior privativo •Logradouro exclusivo — espaço raro em contexto urbano •Ideal para uso próprio ou valorização em arrendamento •Extensão natural da zona social Características do imóvel •Sala ampla com boa luminosidade •2 quar",
  "Operação": "Comprar",
  "Outras_características": "Garagem incluída; Rés do chão sem elevador",
  "Preço": "660.000€",
  "Timestamp": "2026-10-09 08:27:48",
  "Tipologia": "T2",
  "Título": "Apartamento T2 na Rua da Beneficência, 100, Entrecampos, Avenidas Novas",
  "URL": "https://www.idealista.pt/imovel/34665653/",
  "URL_inserido": "https://www.idealista.pt/comprar-casas/lisboa/",
  "Área": "151 m² área bruta"
}
```

Example 4

```json
{
  "Descrição": "Apartamento com várias possibilidades de utilização no centro das Caldas da Rainha. Situada na encantadora cidade de Caldas da Rainha, esta excelente oportunidade de investimento apresenta um conjunto de apartamentos recentemente renovados, com uma área de 120,08 m² + Garagem (50m²), escritório (18m²) e terraço (68m²)",
  "Operação": "Comprar",
  "Outras_características": "Garagem incluída",
  "Preço": "365.000€",
  "Timestamp": "2026-09-23 07:59:31",
  "Tipologia": "T3",
  "Título": "Apartamento T3 na Rua de Santo António, Caldas da Rainha (Nossa Senhora do Pópulo), Nossa Senhora do Pópulo - Coto - São Gregório",
  "URL": "https://www.idealista.pt/imovel/35231715/",
  "URL_inserido": "https://www.idealista.pt/comprar-casas/caldas-da-rainha/",
  "Área": "212 m² área bruta"
}
```

Example 5

```json
{
  "Descrição": "Lote de Terreno para Construção de Moradia Unifamiliar de 2 pisos com Projecto Aprovado e Autorização para Construção, na Quinta do Negrelho em Caldas da Rainha. Óptima localização num dos melhores loteamentos para residir em Caldas da Rainha, a cerca de 2km do acesso à Auto-Estrada A8 (menos de 1h até Lisboa) e da ci",
  "Operação": "Comprar",
  "Outras_características": "Urbano",
  "Preço": "159.500€",
  "Timestamp": "2026-09-23 07:19:49",
  "Tipologia": "",
  "Título": "Terreno na Rua Palmira Bastos, Santo Onofre e Serra do Bouro",
  "URL": "https://www.idealista.pt/imovel/32320845/",
  "URL_inserido": "https://www.idealista.pt/comprar-terrenos/caldas-da-rainha/",
  "Área": "684 m²"
}
```

## API

`POST https://openapi.octoparse.com/api/agentTools/executeTask`

This is the OpenAPI Agent Tools `executeTask` endpoint. Authenticate with a Bearer token.

Request body:

`templateName` is the template slug; `parameters` is a JSON object string whose keys match Input Schema; `taskName`, `idempotencyKey`, and `maxCollectedRows` are optional.

Obtain a token:

```http
POST https://openapi.octoparse.com/token
Content-Type: application/json

{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "grant_type": "password"
}
```

Use `data.access_token` as `Authorization: Bearer <token>`. After starting, poll `getTaskStatus` and export with `exportData`.

```json
{
  "templateName": "idealista-real-estate-listing-scraper-portugal",
  "taskName": "Idealista Real Estate Listing Scraper (Portugal)",
  "parameters": "{\"list_Page_URL\":[\"https://www.idealista.pt/comprar-casas/lisboa/\"],\"number_of_pages\":5}"
}
```

## Python Example

```python
import json
import requests

OPENAPI_BASE = "https://openapi.octoparse.com"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

parameters = json.loads("{\"list_Page_URL\":[\"https://www.idealista.pt/comprar-casas/lisboa/\"],\"number_of_pages\":5}")

response = requests.post(
    f"{OPENAPI_BASE}/api/agentTools/executeTask",
    headers={
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "templateName": "idealista-real-estate-listing-scraper-portugal",
        "taskName": "Idealista Real Estate Listing Scraper (Portugal)",
        "parameters": json.dumps(parameters, ensure_ascii=False),
    },
    timeout=60,
)
print(response.status_code)
print(response.json())
```

## HTTP/cURL Example

```bash
curl -X POST "https://openapi.octoparse.com/api/agentTools/executeTask" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "templateName": "idealista-real-estate-listing-scraper-portugal",
  "taskName": "Idealista Real Estate Listing Scraper (Portugal)",
  "parameters": "{\"list_Page_URL\":[\"https://www.idealista.pt/comprar-casas/lisboa/\"],\"number_of_pages\":5}"
}
JSON
```

## MCP Setup

Connect an MCP-compatible AI client to `https://mcp.octoparse.com` using browser OAuth or an Octoparse API key. Find `idealista-real-estate-listing-scraper-portugal`, inspect its inputs, create a cloud task with the exact Input Schema keys, and export JSON results.

## Machine-readable Resources

- [Template contract](https://www.octoparse.com/templates/idealista-real-estate-listing-scraper-portugal.json)
- [Manifest](https://www.octoparse.com/templates/idealista-real-estate-listing-scraper-portugal-manifest.json)