Loading Light/Dark Toggle
De volta ao blog

Resposta JSON da API de Pesquisa Google: organic_results explicado

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

Resumo rápido (TL;DR):

  • organic_results é uma coleção de registros de resultados orgânicos de busca. Leia a posição retornada, o título, o snippet e o link de cada registro sem misturá-los com outros módulos de resultados.
  • A posição retornada e a ordem no array são valores diferentes. Preserve ambos ao preparar um conjunto de dados.
  • Um link retornado não é automaticamente uma URL final verificada. Mantenha distintos os estados intermediários e de candidato a destino.
  • Campos ausentes devem continuar visíveis. Um snippet ausente, uma string vazia e um registro malformado exigem tratamentos diferentes.

Introdução: Leia a resposta antes de achatá-la

Uma resposta JSON da Google Search API pode conter resultados orgânicos ao lado de painéis de conhecimento, seções locais, perguntas relacionadas e outros módulos dependentes da consulta. Achatar todo objeto que contenha um campo title produz um conjunto de dados com significados misturados.

Este tutorial foca em organic_results na Scrapeless Google Search API. O objetivo é um formato de registro pequeno e inspecionável para títulos, snippets, posições e links. Ele não constrói um rastreador de posições nem afirma que todo link retornado já foi verificado contra uma URL de destino final.

O exemplo de resposta do Google Search e o workflow de requisição do actor fornecem o contexto de requisição em torno disso. Aqui, o trabalho útil começa depois que uma resposta concluída foi salva.

O que organic_results contém

O campo organic_results é um array de objetos de resultados orgânicos, com campos cuja disponibilidade precisa ser verificada em cada item. Um registro não é uma cópia completa da página de destino.

Field Meaning in the Dataset Handling Rule
position Posição retornada pela API Preserve sem recomputar
title Título do resultado Mantenha valores nulos ou ausentes distinguíveis de texto
snippet Trecho do resultado de busca Trate-o como uma observação da busca, não como conteúdo completo da página
link URL de resultado retornada Classifique-a antes da correspondência de destino a jusante
redirect_link Link adicional em forma de redirecionamento quando presente Armazene separadamente; não substitua link automaticamente
source Rótulo de fonte exibida quando disponível Não presuma que seja um domínio registrável

A tabela descreve campos a serem inspecionados, não uma garantia de que cada item contenha cada chave. A referência de parâmetros define controles de requisição; ela não deve ser lida como uma promessa de módulos de resultados idênticos entre consultas.

JSON permite valores como null, strings e arrays, conforme descrito na especificação JSON. Um formato de resposta flexível ainda precisa de um contrato de consumo deliberado. Decida quais valores ausentes sua aplicação pode reter e quais devem interromper o processamento.

Preserve a posição sem inventar um ranking

Mantenha o position retornado, o índice no array e o deslocamento (offset) da requisição como campos separados ao combinar páginas. Cada valor descreve uma parte diferente da observação.

O índice no array registra onde um item apareceu no array retornado. A posição retornada é o valor fornecido pela API. O deslocamento da requisição registra qual página você requisitou. Somar um deslocamento a uma posição sem primeiro estabelecer a semântica dessa posição pode contar um deslocamento em dobro ou implicar um ranking que a resposta não declarou.

Não conte anúncios, um grafo de conhecimento e registros orgânicos em uma única sequência a menos que você tenha definido e validado essa métrica personalizada. Um desenvolvedor que precise de rankings orgânicos deve reter contexto suficiente para inspecionar a página de busca que produziu o registro.

Armazene o JSON intacto mesmo que seu banco de dados precise apenas de algumas colunas. Você pode mais tarde precisar de um campo que o primeiro script de normalização descartou, ou pode precisar distinguir um campo ausente de um valor introduzido pela sua própria transformação.

Uma classificação de URL é uma decisão de roteamento para validação posterior; não é prova de um destino final. A resposta básica para coffee incluiu valores link diretos e valores redirect_link separados do Google nos mesmos registros orgânicos.
Inspecione o esquema, o hostname e o caminho em vez de testar se uma string simplesmente contém a palavra Google. O modelo de componentes de URI torna essas partes explícitas. Uma URL com um nome de marca familiar dentro de seu caminho não é necessariamente hospedada por essa marca.

Classificações úteis incluem valor ausente, link relativo, intermediário Google observado e candidato a URL absoluta. Preserve valores opacos em links /goto?url=.... Um parâmetro opaco não é um destino que você possa recuperar adivinhando um esquema de decodificação.

Comece a Scraping com o Scrapeless

Potencialize seu fluxo de trabalho de web scraping e automação com o Scrapeless!
Inscreva-se hoje e receba US$ 5 em crédito grátis — sem necessidade de cartão de crédito.

Solicite seu crédito grátis agora no Painel do Scrapeless.

Normalizar uma Resposta JSON Salva

O programa a seguir cria registros normalizados sem visitar nenhuma URL de resultado. Ele preserva ambos os campos de link e anexa uma classificação local para revisão posterior.

Os pré-requisitos são Python e uma resposta concluída do Google Search salva como serp.json. Salve o próprio objeto de resposta da API, não um wrapper personalizado contendo seus metadados de logging. A requisição de início rápido fornece essa resposta. Salve o script como normalize_organic.py e execute python normalize_organic.py ao lado do arquivo JSON.

O hostname definido no exemplo cobre os hosts do Google observados nessa família de respostas. Ele não é, intencionalmente, um registro global de todos os domínios do Google. Estenda-o apenas quando suas respostas reais justificarem a adição. Outras URLs absolutas permanecem candidatas não verificadas.

python Copy
import json
from pathlib import Path
from urllib.parse import urlsplit


def classify_link(value):
    if not isinstance(value, str) or not value.strip():
        return "missing"
    if value.startswith("/"):
        return "relative_review"
    try:
        parts = urlsplit(value)
        host = (parts.hostname or "").lower()
    except ValueError:
        return "invalid_review"
    if parts.scheme not in ("https", "http") or not host:
        return "invalid_review"
    # These are observed Google hosts, not a global Google-domain registry.
    google_hosts = {"google.com", "www.google.com"}
    if host in google_hosts and parts.path in ("/url", "/goto"):
        return "google_intermediary"
    if host in google_hosts:
        return "google_page_review"
    return "absolute_candidate"


data = json.loads(Path("serp.json").read_text(encoding="utf-8"))
if not isinstance(data, dict) or not isinstance(data.get("organic_results"), list):
    raise ValueError("Expected an object with an organic_results array")
normalized = []
for index, row in enumerate(data["organic_results"], start=1):
    if not isinstance(row, dict):
        raise ValueError(f"Invalid result at index {index}")
    normalized.append({
        "array_index": index,
        "returned_position": row.get("position"),
        "title": row.get("title"),
        "snippet": row.get("snippet"),
        "link": row.get("link"),
        "redirect_link": row.get("redirect_link"),
        "link_state": classify_link(row.get("link")),
    })
Path("organic-normalized.json").write_text(
    json.dumps(normalized, ensure_ascii=False, indent=2), encoding="utf-8"
)
counts = {}
for row in normalized:
    state = row["link_state"]
    counts[state] = counts.get(state, 0) + 1
print(json.dumps({"rows": len(normalized), "link_states": counts}))

As funções de parsing de URL do Python separam componentes, mas o parsing por si só não valida confiança ou alcançabilidade de rede. Portanto, o estado absolute_candidate do script significa exatamente isto: estava presente uma URL HTTP absoluta com um hostname.

Decidir Quando uma URL Final é Necessária

A verificação da URL final torna-se necessária quando sua conclusão depende da identidade da página de destino. A descoberta de palavras-chave pode reter um link candidato para inspeção posterior; classificação por domínio-alvo, atribuição e entrega de citações exigem evidências mais fortes.

Tarefa Downstream O que o Link Retornado Pode Sustentar Trabalho Adicional
Descoberta de tópicos Um candidato a fonte ao lado de um snippet Revisar a página antes de confiar em suas alegações
Auditoria de resposta de busca O texto do link que a API retornou Preservar a resposta original e o HTML quando necessário
Correspondência de domínio Uma classificação preliminar de candidato Resolver e validar o domínio de destino
Citação verificada Uma referência candidata Verificar URL final, conteúdo acessível e suporte à alegação

Se você construir um resolvedor de destino, mantenha a URL original e a URL final como colunas separadas. Registre a cadeia de redirecionamentos e o resultado da resolução. Não envie a chave de API do Scrapeless para sites de resultado e não trate uma falha de rede como evidência de que a página não existe.

Evite remover parâmetros de query indiscriminadamente. Alguns parâmetros fazem parte da identidade de uma página. Mesmo remover uma barra final pode mesclar URLs que uma origem trata de forma diferente. Comece com regras de comparação conservadoras e depois documente qualquer política de normalização que seu conjunto de dados utilize.

Diagnosticar Campos Ausentes ou Inesperados

Um relatório de qualidade de campos deve mostrar o que chegou em vez de fabricar silenciosamente valores de substituição. Conte strings não vazias separadamente de chaves que meramente existem.

Para snippet, distinga uma chave omitida, um valor nulo, uma string vazia e texto não vazio. Esses estados afetam se uma linha pode sustentar análise de texto. Mantenha uma linha com snippet ausente se seu título ainda servir para sua tarefa, mas sinalize o material ausente para que um analista entenda a limitação.

No nível de coleção, um array orgânico ausente não é equivalente a um array orgânico vazio. Itens do tipo errado devem parar um consumidor estrito ou ser registrados em um relatório de rejeição. Nenhuma das escolhas deve aumentar silenciosamente uma métrica de sucesso.

Conclusão: Preserve o Significado de Cada Campo

Um parser confiável de resposta JSON da Google Search API preserva os campos de origem e adiciona apenas transformações que consegue explicar. Posição, ordem de arrays e estado da URL permanecem visíveis, enquanto suposições não suportadas sobre o destino ficam fora do registro.
Comece com a Scrapeless Google Search API, escolha a frequência de coleta em função da precificação atual e valide algumas respostas salvas antes de definir um schema de banco de dados.

Construa Seu Fluxo de Trabalho de Dados de Busca

Junte-se aos 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: organic_results inclui todas as seções visíveis na SERP?

Não. Outros recursos de busca podem aparecer em seções de resposta separadas. Um parser do array de resultados orgânicos não deve absorver esses módulos silenciosamente.

P: position é o mesmo que o índice do item no array?

Não presuma que sejam intercambiáveis. Mantenha separadamente a posição retornada e o índice do array, particularmente em requisições paginadas.

P: redirect_link deve substituir link?

Não. Preserve ambos quando existirem. Escolha uma política de processamento de destino com base no estado real da URL e na sua tarefa downstream.

P: Um link codificado do Google pode ser tratado como o destino decodificado?

Não. Preserve valores opacos e use um processo de resolução validado quando a identidade do destino final for necessária.

P: Um snippet não vazio prova que o resumo é preciso?

Não. Texto não vazio mede a disponibilidade do campo. Precisão e sustentação das afirmações exigem inspeção do conteúdo de origem.

P: A normalização precisa de um agente de IA ou de um proxy separado?

Não. Este script de normalização opera em JSON salvo e não faz requisições de rede.

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