Como extrair dados do Idealista: Um manual para 2026

Se já passou algum tempo a tentar descobrir como extrair dados do Idealista, já sabe que o manual é curto e brutal: enviar algumas solicitações limpas, ser bloqueado, trocar de user-agents, ser bloqueado novamente, ver um captcha e recomeçar. O Idealista é o portal imobiliário dominante em Espanha, Portugal e Itália, com milhões de anúncios de venda e arrendamento, o que o torna uma mina de ouro para analistas de mercado, agentes de compra e equipas de proptech. É também um dos sites mais agressivamente defendidos da categoria.

Este guia foi escrito para programadores Python de nível intermédio que procuram uma receita testada em campo, e não um fragmento de código. Irá aprender primeiro o contexto legal e técnico, depois percorrer um fluxo de trabalho concreto do Selenium com o undetected-chromedriver, e, por fim, integrar proxies, tratamento de captchas, deduplicação e rastreamento incremental, com as realidades de produção que a maioria dos tutoriais ignora.

O Idealista é um dos maiores mercados imobiliários do sul da Europa, com milhões de anúncios de venda e arrendamento nos sites espanhóis, italianos e portugueses. Para a pesquisa de investidores, modelos de preços comparativos e enriquecimento de leads para agências, essa presença é difícil de replicar apenas a partir de APIs públicas, razão pela qual tantas equipas perguntam, em primeiro lugar, como extrair dados do Idealista.

Quando planear uma extração, decida antecipadamente quais os campos de que realmente precisa. O cartão do anúncio e as páginas de detalhes normalmente apresentam:

• Título e URL do anúncio (o /inmueble/<id>/ )
• Preço e moeda, além do preço por metro quadrado nas páginas de detalhes
• Área útil em m², número de quartos e casas de banho
• Texto descritivo, data de publicação e data de atualização
• Tipo de agente ou proprietário (particular vs. agência), com telefone e botões de contacto
• Fotografias, plantas e, por vezes, links para visitas virtuais
• Coordenadas aproximadas e metadados do bairro

Os sites italiano (idealista.it) e português (idealista.pt) tendem a espelhar o layout espanhol, pelo que um único design de scraper se adapta geralmente aos três com pequenos ajustes nos seletores. Abordaremos essas diferenças na secção de resolução de problemas.

Os dados de anúncios públicos são geralmente considerados legítimos quando recolhidos a um ritmo razoável, mas os termos de serviço do Idealista e o RGPD da UE alteram a equação no momento em que se lida com dados pessoais. Nomes de agentes, números de telefone e endereços de e-mail são dados pessoais ao abrigo do RGPD, pelo que o seu armazenamento em grande escala requer normalmente uma base legal documentada, limites de retenção e um procedimento de eliminação de dados.

Medidas de segurança práticas: respeite robots.txt, limite agressivamente, evite áreas de acesso privado e remova detalhes de contacto pessoais de qualquer conjunto de dados que redistribuir. Trate esta secção como orientação e não como aconselhamento jurídico, e consulte o seu advogado sobre qualquer assunto sensível antes da produção. A postura jurídica aqui é genuinamente contestada, por isso verifique o âmbito atual do RGPD para o seu caso de utilização específico antes de implementar um scraper em grande escala.

A maioria dos relatórios públicos atribui o captcha intersticial da Idealista ao DataDome, um serviço comercial de mitigação de bots. Considere essa atribuição como um consenso da comunidade e não como uma declaração oficial, uma vez que a Idealista não publica a sua pilha de deteção.

A deteção ocorre em camadas, e compreender cada uma delas é a diferença entre um scraper que sobrevive uma semana e um bloqueado numa hora:

• Impressão digital TLS e JA3. Simples requests e muitas bibliotecas HTTP produzem uma assinatura de handshake TLS facilmente distinguível de uma sessão real do Chrome. Mesmo com um User-Agent perfeito, a ordem de encriptação denuncia-o.
• Coerência dos cabeçalhos. Os motores de deteção de bots verificam que Accept, Accept-Language, sec-ch-uae User-Agent se concordam entre si. Um UA do Chrome 120 emparelhado com um sec-ch-ua-platform é um indício.
• Desafios de JavaScript. O DataDome serve uma pequena carga de JS que sonda navigator.webdriver, hashes de canvas, renderizadores WebGL e sinais de temporização. O Headless Chrome e o Selenium padrão falham em vários testes por predefinição.
• Sinais comportamentais e de IP. Velocidade, navegação sem rato, intervalos de ASN de centros de dados e cookies reutilizados contribuem todos para uma pontuação de risco que aciona o captcha.

O seu bot precisa de uma impressão digital de navegador real, cabeçalhos plausíveis, IPs residenciais ou móveis e um ritmo semelhante ao humano. Nenhuma solução isolada é suficiente.

Não existe uma resposta universalmente correta sobre como extrair dados do Idealista em grande escala; a escolha certa depende do volume, do orçamento e da quantidade de JavaScript que consegue suportar na renderização. Aqui está uma matriz de decisão rápida que pode colar num documento de planeamento.

As pilhas HTTP puras são a opção mais barata quando funcionam, mas falham assim que o Idealista se transforma num desafio de JS. O Selenium com o undetected-chromedriver oferece uma impressão digital real do navegador e execução DOM, ao custo de ser significativamente mais lento e consumir mais memória. Uma API gerida oculta totalmente a camada de proxy e de resolução de desafios, o que é a escolha certa quando se ultrapassa a capacidade de uma única máquina. A maioria das equipas de produção acaba por combinar estas opções: um caminho HTTP rápido para páginas simples, um fallback de navegador para as mais complexas e uma API de scraping como rede de segurança.

Vais precisar do Python 3.10 ou mais recente, um virtualenv limpo e dependências fixadas. O frontend do Idealista muda frequentemente, pelo que fixar as versões facilita o diagnóstico de regressões mais tarde.

python -m venv .venv
source .venv/bin/activate
pip install selenium==4.* undetected-chromedriver selenium-wire             httpx parsel tenacity python-dotenv

Um layout prático:

idealista-scraper/
├── .env                  # proxy credentials, API keys
├── config.py             # constants, base URLs
├── scraper/
│   ├── driver.py         # uc.Chrome factory + waits
│   ├── crawl.py          # provinces → municipalities → listings
│   └── parse.py          # XPath/CSS extractors
├── storage.py            # JSON/CSV/SQLite writers
└── main.py

Fixa a versão principal do Chrome em relação à tua compilação undetected-chromedriver ; incompatibilidades são a causa mais comum de falhas silenciosas.

Antes de escreveres um único seletor, percorre o site manualmente. O esquema de URLs do Idealista é bastante regular assim que percebes o padrão, e um mapa mental claro evita que voltes a rastrear os mesmos nós.

A hierarquia é mais ou menos assim:

• Página inicial: https://www.idealista.com/ (e .it, .pt para as versões em italiano e português)
• Diretório de províncias: com link na parte inferior da página inicial
• Diretório de municípios: em cada província, uma página que lista os municípios
• Páginas de listagem: /venta-viviendas/<municipality>/ para venda, /alquiler-viviendas/<municipality>/ para arrendamento (os padrões de URL para arrendamento e IT/PT tendem a seguir este modelo, mas verifique primeiro numa página ativa)
• Paginação: pagina-2.htm, pagina-3.htm, anexada ao URL do anúncio
• Detalhes do imóvel: /inmueble/<id>/, o identificador canónico único do anúncio
• Ordenação por data: acrescentar ?ordenado-por=fecha-publicacion-desc para apresentar primeiro as propriedades recém-listadas

Internalize esse inmueble/<id> slug; o resto do artigo usa-o como chave de deduplicação e pivô de rastreamento de alterações. Uma referência sólida de seletores CSS é inestimável aqui quando os seletores mudam.

Com o mapa de URLs em mãos, pode criar o scraper propriamente dito. O plano: inicie um Chrome modificado através de undetected-chromedriver, navegar até à página inicial e usar esperas explícitas para confirmar que o DOM foi renderizado antes de o consultar. Os próximos quatro passos constroem o rastreador numa varredura de cima para baixo, das províncias aos municípios, aos cartões de listagem e à paginação.

A página inicial em espanhol apresenta um diretório de províncias perto do rodapé. Recolhemos cada âncora dentro desse bloco, guardamos o nome visível e mantemos o URL absoluto para o próximo passo.

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

def make_driver():
    opts = uc.ChromeOptions()
    opts.add_argument("--window-size=1366,900")
    # use_subprocess=True is currently required to avoid a destructor
    # bug in some undetected-chromedriver builds; verify against the
    # upstream repo before pinning, since package internals change often.
    return uc.Chrome(options=opts, use_subprocess=True)

def fetch_provinces(driver):
    driver.get("https://www.idealista.com/")
    WebDriverWait(driver, 20).until(
        EC.presence_of_element_located((By.CSS_SELECTOR, "div.locations-list"))
    )
    anchors = driver.find_elements(
        By.XPATH, "//div[contains(@class,'locations-list')]//a"
    )
    return {a.text.strip(): a.get_attribute("href") for a in anchors if a.text.strip()}

A primeira chamada irá quase certamente encontrar um captcha DataDome, por isso envolva-a com um gancho de resolução manual (abordado mais adiante) na primeira execução. Assim que a sua sessão tiver um cookie limpo, o resto do rastreamento decorre normalmente.

Cada página de província apresenta os seus municípios através de um location_list bloco. Percorremos o dicionário da Etapa 1 e anexamos o nome e a URL de cada município abaixo da sua província pai.

def fetch_municipalities(driver, provinces):
    out = {}
    for name, url in provinces.items():
        driver.get(url)
        WebDriverWait(driver, 15).until(
            EC.presence_of_element_located((By.ID, "location_list"))
        )
        anchors = driver.find_elements(By.XPATH, "//ul[@id='location_list']//a")
        out[name] = {
            "url": url,
            "municipalities": [
                {"name": a.text.strip(), "url": a.get_attribute("href")}
                for a in anchors if a.text.strip()
            ],
        }
        time.sleep(random.uniform(2.5, 6.0))  # polite pacing
    return out

Há duas coisas que vale a pena destacar: os intervalos aleatórios imitam a navegação humana de forma mais convincente do que os atrasos fixos, e deve guardar este dicionário aninhado no disco após cada província, para que uma falha na província número 30 não o faça perder as 29 anteriores.

As páginas de listagem apresentam um article.item nó por imóvel, com filhos estruturados para os campos canónicos. Os padrões XPath abaixo utilizam contains(@class, ...) em vez de igualdade estrita porque o Idealista ocasionalmente acrescenta classes modificadoras aos seus cartões.

def parse_listing_page(driver):
    cards = driver.find_elements(By.XPATH, "//article[contains(@class,'item')]")
    rows = []
    for c in cards:
        try:
            link = c.find_element(By.XPATH, ".//a[contains(@class,'item-link')]")
            url = link.get_attribute("href")
            title = link.text.strip()
            price = c.find_element(
                By.XPATH, ".//span[contains(@class,'item-price')]"
            ).text.strip()
            details = [
                d.text.strip() for d in c.find_elements(
                    By.XPATH, ".//span[contains(@class,'item-detail-char')]/span"
                )
            ]
            description = c.find_element(
                By.XPATH, ".//div[contains(@class,'item-description')]"
            ).text.strip()
            rows.append({
                "id": url.rstrip("/").split("/")[-1],
                "url": url, "title": title, "price": price,
                "details": details, "description": description,
            })
        except Exception:
            # Sponsored or malformed cards: skip rather than abort.
            continue
    return rows

Duas notas de produção. Primeiro, o Idealista intercala cartões de anúncios que parecem quase idênticos aos orgânicos; o try/except em torno de cada cartão evita que um nó incorreto bloqueie a página. Segundo, os seletores sofrem alterações; espere atualizar estes XPaths a cada dois meses. Mantenha-os num único parse.py módulo para que a comparação seja fácil.

A Idealista utiliza um esquema de paginação numérica com um Siguiente ligação «Siguiente» envolvida em li.next. Alguns tutoriais recorrem à URL seguinte até esta desaparecer, mas a recursão ilimitada é a forma de ultrapassar os limites de taxa e atingir o limite de recursão do Python em municípios densos. Limite o loop em vez disso.

MAX_PAGES = 40

def crawl_municipality(driver, start_url, max_pages=MAX_PAGES):
    rows, url, page = [], start_url, 0
    while url and page < max_pages:
        driver.get(url)
        WebDriverWait(driver, 15).until(
            EC.presence_of_element_located((By.XPATH, "//main"))
        )
        rows.extend(parse_listing_page(driver))
        try:
            next_link = driver.find_element(
                By.XPATH, "//li[contains(@class,'next')]/a"
            )
            url = next_link.get_attribute("href")
        except Exception:
            url = None
        page += 1
        time.sleep(random.uniform(3.0, 7.0))
    return rows

Um limite de 40 páginas corresponde aproximadamente ao próprio limite de paginação profunda do Idealista e mantém cada trabalhador dentro dos limites. Se realmente precisar de mais, divida a pesquisa por faixa de preço ou tipo de imóvel e execute essas subconsultas em paralelo, em vez de aprofundar-se num único conjunto de resultados.

Qualquer pessoa que esteja a aprender a extrair dados da Idealista acabará por se deparar com o intersticial do DataDome. A boa notícia, confirmada por relatos em várias comunidades de scrapers, é que, uma vez resolvido o desafio numa sessão, este normalmente não reaparece durante o resto dessa sessão de navegação. Pode contar com isso através de algumas táticas concretas.

A mais simples é um gancho de resolução manual para desenvolvimento:

def open_with_captcha_pause(driver, url):
    driver.get(url)
    if "captcha" in driver.page_source.lower() or "datadome" in driver.page_source.lower():
        input("Solve the captcha in the browser, then press Enter to continue...")

Para qualquer coisa além de uma ocorrência pontual, suba de nível:

• Perfil persistente. Passar --user-data-dir=./chrome-profile os cookies e o DataDome _dd sobrevivam às execuções.
• Mude de IP após um desafio. Um captcha num IP residencial é recuperável; um captcha que se repete no mesmo IP geralmente significa que este está bloqueado. Mude para uma nova saída e tente novamente.
• Abrande. Insira um intervalo aleatório mais longo (30 a 90 segundos) antes de tentar novamente após um desafio, em vez de martelar o mesmo URL.
• Recorra a um solucionador gerido. Quando o rendimento é mais importante do que o controlo, encaminhe o pedido através de uma API de scraping que lida com a identificação e os desafios do seu lado.

Trate o captcha como um sinal de que a sua impressão digital, IP ou ritmo ultrapassaram um limite, e não como um simples pop-up para fechar.

A parte difícil de como extrair dados do Idealista em volume de produção não é analisar o HTML; é antecipar-se aos bloqueios. Assim que o seu protótipo funcionar, a escalabilidade expõe novos modos de falha. Os IPs do centro de dados que sobreviveram às suas primeiras 200 solicitações são desafiados em massa, cabeçalhos idênticos em todos os trabalhadores destacam-se e as solicitações fortemente sincronizadas parecem um bot coordenado.

Organize as suas defesas nesta ordem e só adicione complexidade quando a camada anterior deixar de funcionar.

1. Proxies residenciais ou móveis, com segmentação geográfica. O tráfego do Idealista é dominado por consumidores espanhóis, italianos e portugueses. Os IPs residenciais desses países misturam-se; um ASN de um centro de dados dos EUA não. Com selenium-wire:

from seleniumwire.undetected_chromedriver import Chrome

seleniumwire_options = {
    "proxy": {
        "http":  "http://user:pass@es.proxy.example:8000",
        "https": "http://user:pass@es.proxy.example:8000",
        "no_proxy": "localhost,127.0.0.1",
    }
}
driver = Chrome(seleniumwire_options=seleniumwire_options, use_subprocess=True)

2. Rotação de cabeçalhos. Alterne entre um pequeno conjunto de cabeçalhos realistas do Chrome 12x (correspondentes User-Agent, sec-ch-uae Accept-Language). Mantenha-os coerentes; dicas de cliente incompatíveis são sinalizadas mais rapidamente do que qualquer cabeçalho incorreto isolado.

3. Limites de simultaneidade. Limite os trabalhadores a 1 por IP, de 4 a 8 por região e, por rastreamento, ao que o seu plano de proxy suportar. Adicione atrasos aleatórios de 3 a 10 segundos entre as recuperações de páginas para que o seu tráfego não seja pulsado.

4. Uma API de scraping gerida como rede de segurança. Assim que ultrapassar alguns milhares de páginas por dia, manter a sua própria pilha de fingerprinting custa mais do que poupa. Uma API de Scraper gerida lida com a rotação de IP, a resolução de desafios e a lógica de repetição por trás de um único ponto de extremidade, o que lhe permite manter o seu código de análise e apenas trocar a camada de obtenção. Trate-a como um caminho alternativo em vez de como o padrão.

Imprimir linhas para o stdout serve para uma demonstração, mas é inútil em produção. O stream grava no disco à medida que avança, para que uma falha na oitava hora não apague as horas um a sete.

import json, sqlite3

def upsert_sqlite(db_path, rows):
    conn = sqlite3.connect(db_path)
    conn.execute(
        "CREATE TABLE IF NOT EXISTS listings ("
        "id TEXT PRIMARY KEY, url TEXT, title TEXT, price TEXT, "
        "details TEXT, description TEXT, scraped_at TEXT)"
    )
    conn.executemany(
        "INSERT OR REPLACE INTO listings VALUES (?,?,?,?,?,?,datetime('now'))",
        [(r["id"], r["url"], r["title"], r["price"],
          json.dumps(r["details"]), r["description"]) for r in rows],
    )
    conn.commit(); conn.close()

Use o inmueble/<id> slug como chave primária; títulos e preços mudam, IDs não. Para pipelines mais leves, JSONL de apenas adição mais uma passagem diária de deduplicação na mesma chave funciona bem.

A maioria das equipas que perguntam como extrair dados da Idealista de forma recorrente preocupa-se menos com um dump em massa único e mais com o que apareceu nas últimas 24 horas. Agentes de compradores, fundos de investidores e ferramentas de geração de leads querem todos um delta atualizado, não o arquivo completo. A Idealista disponibiliza uma ordenação por recência com ?ordenado-por=fecha-publicacion-desc, que é a base para um fluxo de trabalho leve de rastreamento de alterações.

O padrão é simples: execute o rastreador na URL ordenada por data de atualização para cada município monitorizado, compare os IDs resultantes com a sua última execução e emita apenas as novas linhas.

def diff_new_listings(rows, seen_ids_path):
    seen = set(pathlib.Path(seen_ids_path).read_text().splitlines())         if pathlib.Path(seen_ids_path).exists() else set()
    new_rows = [r for r in rows if r["id"] not in seen]
    pathlib.Path(seen_ids_path).write_text(
        "\n".join(seen | {r["id"] for r in new_rows})
    )
    return new_rows

Agende a tarefa de hora a hora via cron ou Airflow, receba alertas sobre novas linhas pelo Slack ou e-mail, e terá um radar imobiliário funcional sem um backend personalizado.

Alguns padrões são responsáveis pela maioria das falhas relatadas pelos leitores.

• use_subprocess Peculiaridade. As versões recentes undetected-chromedriver necessitam use_subprocess=True em algumas plataformas para evitar um aviso de destrutor que pode corromper o driver. Verifique no repositório upstream, uma vez que a solução alternativa varia entre versões.
• NoSuchElementException em cartões. Normalmente, o Idealista trocou o nome de uma classe. Reexamine o DOM e dê preferência contains(@class, ...) em vez de igualdade estrita.
• /en/ diferenças de layout. A localização em inglês apresenta um DOM ligeiramente diferente. Fixe à localização que realmente deseja e mantenha os seletores por localização se atravessar sites.
• Incompatibilidade entre o Chrome e o driver. Fixe ambos. Um SessionNotCreatedException significa quase sempre que o driver corrigido e o Chrome instalado têm versões principais diferentes.

• A pilha de bloqueio da Idealista combina desafios do DataDome, impressão digital TLS e reputação de IP, pelo que uma única tática como a rotação de User-Agents não será eficaz em grande escala.
• Use o inmueble/<id> slug como sua chave de deduplicação e identificador principal; títulos e preços mudam, IDs não.
• Limite a sua paginação (cerca de 40 páginas por município) e divida as consultas mais detalhadas por faixa de preço ou tipo de imóvel, em vez de recorrer indefinidamente.
• Organize as suas defesas por ordem: impressão digital de navegador real, IPs residenciais com segmentação geográfica, rotação de cabeçalhos, ritmo de acesso moderado e, por fim, uma API de scraping gerida como plano de contingência.
• Acompanhe novos anúncios ordenando fecha-publicacion-desc e comparando os IDs com a sua última execução; é isto que transforma um scraper num produto útil.

A recolha de dados de anúncios públicos é geralmente legal, desde que feita a um ritmo razoável, mas os nomes, números de telefone e e-mails dos agentes são dados pessoais ao abrigo do RGPD e requerem uma base legal documentada, limites de retenção e um procedimento de eliminação. Armazenar ou redistribuir contactos de agentes em grande escala sem esses controlos é a parte mais arriscada de qualquer pipeline do Idealista. Consulte um advogado para obter orientação específica para a sua jurisdição.

A Idealista não publica uma API de anúncios públicos de uso geral. O seu programa para programadores está orientado para integrações de parceiros e colocação de anúncios, em vez de acesso aberto aos dados. Para a maioria dos casos de utilização em análise ou investigação, a extração do site público ou a compra de um conjunto de dados imobiliários gerido são as opções realistas. Consulte diretamente o portal de programadores atual antes de assumir que qualquer ponto final específico está disponível.

O undetected-chromedriver corrige apenas um sinal, o navigator.webdriver flag e alguns elementos internos do Chrome. O DataDome também avalia impressões digitais TLS, coerência de cabeçalhos, reputação de IP e ritmo comportamental. Se o seu IP estiver num intervalo de datacenters sinalizado, ou se os seus cabeçalhos forem inconsistentes, o desafio continuará a ser apresentado. Adicione primeiro proxies residenciais e um ritmo mais lento.

Depende do volume. Para algumas centenas de páginas, o HTTPX com parsel é o mais rápido. Para uma extração fiável por página com renderização JS, o Selenium com o undetected-chromedriver é o meio-termo comprovado. Acima de alguns milhares de páginas por dia, uma API de scraping gerida elimina a sobrecarga do proxy e da resolução de desafios, e é normalmente mais barata do que manter a sua própria pilha de impressões digitais.

Em grande parte, sim. Os sites italiano (idealista.it) e português (idealista.pt) partilham normalmente o layout espanhol, e os arrendamentos seguem um alquiler-viviendas padrão que espelha venta-viviendas. Verifique os seletores em páginas ativas, uma vez que a Idealista ocasionalmente realiza testes A/B com ajustes específicos para cada localização em torno dos layouts dos cartões e da paginação.

Descobrir como extrair dados do Idealista é, em grande parte, um exercício de respeitar as defesas em camadas que o site construiu ao longo dos anos. Obtenha o mapa de URLs correto, use uma impressão digital de navegador real com o undetected-chromedriver, vincule a sua paginação, deduplique no inmueble/<id> slug e transmita as gravações para o disco para que uma falha nunca lhe custe uma execução completa. Encare os desafios do DataDome como um sinal de que o seu IP, impressão digital ou ritmo ultrapassaram um limite, e não como um pop-up para clicar. Assim que passar da fase de protótipo para a escala de produção, o manual de estratégias em camadas (proxies residenciais, segmentação geográfica, rotação de cabeçalhos, lógica de repetição) começa a compensar-se quase imediatamente.

Se preferir ignorar completamente a configuração de proxies e a resolução de desafios, a API Scraper da WebScrapingAPI lida com a camada de obtenção por trás de um único ponto de extremidade, devolvendo HTML que pode inserir diretamente nos analisadores acima. De qualquer forma, o fluxo de trabalho aqui oferece-lhe um caminho claro desde um protótipo numa única máquina até um pipeline programado que rastreia novos anúncios em espanhol, italiano e português com uma cadência útil.