Loading Light/Dark Toggle
De volta ao blog

API do Google SERP HTML Bruto: Recuperar e Validar rawUrl

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

TL;DR:

  • metadata.rawUrl aponta para o HTML do SERP do Google armazenado. Busque esse URL depois que a resposta JSON concluída chegar.
  • A recuperação do HTML é uma segunda requisição HTTP. A resposta de busca não incorpora esse documento baixado no próprio campo.
  • As verificações do documento fornecem evidências com limites. Status, tipo de mídia, contagem de bytes e estrutura ajudam a detectar problemas, mas não provam que todo recurso esteja completo.
  • Mantenha os bytes originais e um checksum. Uma cópia local permanece inspecionável independentemente da disponibilidade do link de armazenamento remoto.

Introdução: Mantenha uma Página por Trás do Resultado Processado

Dados de busca estruturados são convenientes para análise, mas um campo JSON sozinho não consegue mostrar tudo sobre a página da qual foi extraído. Um documento HTML armazenado oferece outra superfície de inspeção quando um resultado precisa de explicação.

A Scrapeless Google Search API pode retornar metadata.rawUrl junto com resultados estruturados. Este tutorial da Google SERP API raw HTML recupera esse documento e verifica o que foi baixado. O objetivo é um artefato local auditável, não uma alegação de que o markup salvo reproduz todas as interações de uma página de navegador ao vivo.

A resposta de início rápido do Google Search mostra o campo sob metadata. O modelo de requisição de actor mais amplo fornece primeiro os dados de busca; o download do HTML vem depois.

O que rawUrl Representa

O valor rawUrl é um URL para um documento de página armazenado associado à resposta. Ele não é o URL de destino final de um resultado orgânico de busca.

Mantenha três endereços conceitualmente separados: o endpoint da API que aceitou a busca, o endereço do HTML do SERP armazenado e um link de resultado que pode levar à página de um publisher. Baixar o documento do SERP não recupera todos os artigos, produtos ou páginas de negócios vinculados.

Não construa um caminho de armazenamento a partir da consulta ou de um ID de tarefa. Leia o URL exato da resposta concluída. A localização de armazenamento é um valor de saída, e um endereço copiado de um exemplo de documentação não é evidência para a sua própria requisição.

Um rawUrl ausente deve se tornar um estado explícito de “HTML indisponível” no seu fluxo de trabalho. Ele não deve ser substituído por um URL de busca do Google recém-construído, pois isso iniciaria uma observação diferente.

Recupere o JSON Antes de Baixar o HTML

A tarefa de busca deve estar concluída antes que o programa de obtenção de HTML leia seus metadados. Se a busca retornar HTTP 201, use o fluxo de resultados de tarefa para obter primeiro o objeto concluído.

O script abaixo espera esse objeto salvo como serp.json. Seus outros pré-requisitos são Python e Requests, instalados com python -m pip install requests. Salve-o como fetch_serp_html.py e execute python fetch_serp_html.py ao lado da resposta salva.

O URL de armazenamento observado usa HTTPS em api.scrapeless.com sob /storage/. O programa limita downloads a esse host e formato de caminho observados, não segue redirecionamentos e não envia header de chave de API para o armazenamento. Uma mudança futura no host de armazenamento deve acionar a revisão da regra em vez de um fetch irrestrito.

Verificações de URL precisam examinar componentes em vez de substrings. A especificação de sintaxe de URI define o esquema, autoridade, caminho e outros componentes usados por essa verificação.

python Copy
import hashlib
import json
from html.parser import HTMLParser
from pathlib import Path
from urllib.parse import urlsplit

import requests


class DocumentShape(HTMLParser):
    def __init__(self):
        super().__init__()
        self.opened = set()
        self.closed = set()
    def handle_starttag(self, tag, attrs):
        self.opened.add(tag)
    def handle_endtag(self, tag):
        self.closed.add(tag)


data = json.loads(Path("serp.json").read_text(encoding="utf-8"))
metadata = data.get("metadata")
raw_url = metadata.get("rawUrl") if isinstance(metadata, dict) else None
if not isinstance(raw_url, str) or not raw_url:
    raise ValueError("metadata.rawUrl is absent")
parts = urlsplit(raw_url)
if (parts.scheme != "https" or parts.hostname != "api.scrapeless.com"
        or parts.port not in (None, 443) or parts.username or parts.password
        or not parts.path.startswith("/storage/")):
    raise ValueError("Storage URL needs review before downloading")

# The storage fetch uses no API-key header and follows no redirects.
with requests.get(raw_url, timeout=(10, 60), stream=True, allow_redirects=False) as response:
    response.raise_for_status()
    if response.status_code != 200:
        raise ValueError(f"Unexpected storage status: {response.status_code}")
    media_type = response.headers.get("Content-Type", "").split(";")[0].lower()
    if media_type not in ("text/html", "application/xhtml+xml"):
        raise ValueError(f"Unexpected media type: {media_type}")
    chunks = []
    size = 0
    for chunk in response.iter_content(65536):
        size += len(chunk)
        if size > 10 * 1024 * 1024:
            raise ValueError("HTML exceeds this example's local size limit")
        chunks.append(chunk)
    html_bytes = b"".join(chunks)

if not html_bytes:
    raise ValueError("Empty HTML body")
Path("serp.html").write_bytes(html_bytes)
shape = DocumentShape()
shape.feed(html_bytes.decode("utf-8", errors="replace"))
report = {
    "bytes": len(html_bytes),
    "sha256": hashlib.sha256(html_bytes).hexdigest(),
    "has_html": "html" in shape.opened,
    "has_body": "body" in shape.opened,
    "has_closing_html": "html" in shape.closed,
    "source_url": raw_url,
}
Path("serp-html-check.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps({key: value for key, value in report.items() if key != "source_url"}))

O limite local de dez mebibytes é um exemplo de salvaguarda do cliente, não o tamanho máximo de HTML da API. Um documento maior é um motivo para revisar a carga de trabalho esperada e ajustar a política local deliberadamente. O programa grava os bytes somente após um download bem-sucedido e limitado.

Comece a Fazer Scraping com a Scrapeless

Potencialize seu fluxo de trabalho de web scraping e automação com a Scrapeless!
Cadastre-se hoje e ganhe US$ 5 em crédito gratuito — sem necessidade de cartão de crédito.

Solicite seu crédito gratuito agora no Painel da Scrapeless.

Verifique o Download em Vários Níveis

Uma verificação útil de HTML registra sucesso de transporte, tipo de documento, tamanho do payload, estrutura e correspondência com a busca original. Nenhuma verificação isolada prova todos eles.
A resposta coffee usada como base para este tutorial levou a uma segunda requisição com HTTP 200 e Content-Type: text/html. O download continha 1.938.204 bytes e incluía elementos de abertura html e body, além de um elemento de fechamento html. Estas são observações de um documento armazenado, não requisitos de tamanho mínimo para respostas posteriores.

Check O que estabelece O que não estabelece
Status HTTP Que a requisição de armazenamento foi concluída como esperado Que o documento contém os resultados pretendidos
Tipo de mídia Que o servidor identificou a representação como HTML Que todo recurso de busca está presente
Bytes não vazios Que um corpo foi baixado Que o corpo é a página correta
Elementos do documento Que existe uma estrutura básica de marcação Completude semântica ou fidelidade de renderização
Checksum Que bytes posteriores podem ser comparados com a cópia salva Autenticidade de cada declaração na página
Inspeção de consulta e resultado Que o documento corresponde a detalhes selecionados da resposta Completude de todos os possíveis módulos de busca

O significado dos cabeçalhos de resposta e das representações de conteúdo é definido por semântica de representação HTTP. Trate uma verificação de content-type como um sinal, não um substituto para ler o documento.

A interface HTMLParser do Python reconhece eventos de marcação. Ela não é um renderizador de navegador nem um validador de conformidade completo. Os campos booleanos de estrutura no relatório, portanto, permanecem verificações modestas.

Verifique se o HTML Corresponde à Pesquisa

As verificações de correspondência devem comparar o documento armazenado com a requisição e os registros retornados selecionados. Comece pela consulta exibida na página e por uma pequena amostra de títulos ou links que estejam presentes no JSON.

O texto pode estar codificado como entidade, dividido entre elementos ou representado de forma diferente em dados incorporados. A ausência de uma substring bruta é um motivo para inspecionar o documento, não uma prova imediata de que um resultado está ausente. Se você renderizar o arquivo localmente, ativos e scripts externos podem não estar disponíveis ou podem solicitar recursos atuais, de modo que a renderização pode diferir da recuperação original.

Use o documento salvo para responder a uma pergunta específica. Por exemplo, determine se um título aparece na marcação, se uma forma de link inesperada está presente ou se o documento é de fato uma página de busca. Evite transformar essas observações em uma afirmação de que toda expansão dinâmica ou módulo oculto foi capturado.

Solucione Problemas de HTML Ausente ou Inutilizável

Um problema de HTML deve ser classificado na etapa em que ocorre. Mantenha o JSON da busca concluída mesmo quando a recuperação de armazenamento falhar.

Sintoma Verificação
metadata está ausente Confirme que você salvou o objeto de busca concluída
rawUrl está ausente ou vazio Registre o HTML como indisponível para essa resposta
URL rejeitada pelo script Compare a origem real de armazenamento com a origem aprovada
Resposta de armazenamento não-200 Preserve o status e o contexto da requisição; não rotule isso como documento
Tipo de mídia inesperado Inspecione a resposta antes de tratá-la como HTML
Limite de tamanho atingido Revise o limite local e o tamanho esperado do documento
Verificações de estrutura falham Inspecione os bytes; somente uma análise válida é insuficiente
Incompatibilidade entre consulta ou resultado Compare o JSON e o HTML salvos a partir da mesma requisição

Não assuma um período de retenção permanente para um endereço de armazenamento remoto. Baixe o documento enquanto ele estiver disponível se o seu processo precisar de um arquivo. Armazene o JSON, o HTML, o checksum e o contexto da coleta juntos para que outro engenheiro possa entender a relação.

Conclusão: Preserve o que Foi Realmente Baixado

O fluxo de trabalho com HTML bruto tem duas operações distintas: recuperar o JSON de busca concluída e, em seguida, baixar sua URL de HTML armazenado. Salve o documento e registre verificações que digam precisamente o que foi observado.

Use os parâmetros da Google Search API para controlar a consulta original e consulte a precificação atual ao planejar a carga de trabalho de busca. Mantenha a disponibilidade de HTML separada da disponibilidade de resultados orgânicos nos seus próprios relatórios.

Construa o Seu Fluxo de Trabalho de Dados de Busca

Junte-se a desenvolvedores que trabalham com dados de busca em nossa comunidade: Discord · Telegram.

Crie uma conta Scrapeless e aplique este tutorial a um pequeno conjunto de consultas antes de agendar uma coleta maior.

FAQ

P: rawUrl contém o texto HTML?
Não. Ele contém uma URL. Uma segunda requisição HTTP faz o download do documento.

P: rawUrl é o destino final orgânico de um resultado?

Não. Ele aponta para o documento de SERP armazenado associado à resposta, não para cada site listado nessa SERP.

P: Uma tag html de fechamento prova que toda a SERP está completa?

Não. É um sinal estrutural. A correspondência de conteúdo e a completude de recursos dinâmicos exigem inspeção adicional.

P: O pedido de armazenamento deve incluir a chave da API?

O download de armazenamento observado foi bem-sucedido sem o cabeçalho de autenticação. Este exemplo mantém a chave confinada à requisição da API e não a encaminha para o armazenamento ou para sites de resultados.

P: Um link de HTML armazenado é um arquivo permanente?

Não presuma uma garantia de retenção que não foi estabelecida. Mantenha uma cópia local e um checksum quando o documento for necessário posteriormente.

P: O HTML salvo pode substituir a verificação da página de destino?

Não. O HTML da SERP registra a página de busca. A verificação do conteúdo de uma página vinculada é uma tarefa separada.

Na Scorretless, acessamos apenas dados disponíveis ao público, enquanto cumprem estritamente as leis, regulamentos e políticas de privacidade do site aplicáveis. O conteúdo deste blog é apenas para fins de demonstração e não envolve atividades ilegais ou infratoras. Não temos garantias e negamos toda a responsabilidade pelo uso de informações deste blog ou links de terceiros. Antes de se envolver em qualquer atividade de raspagem, consulte seu consultor jurídico e revise os termos de serviço do site de destino ou obtenha as permissões necessárias.

Artigos mais populares

Catálogo