Loading Light/Dark Toggle
De volta ao blog

Tutorial da API de Pesquisa do Google em Python: Requisições e Resultados

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

TL;DR:

  • A Scrapeless Google Search API retorna dados de busca estruturados para Python. Envie q, gl e hl em uma requisição JSON autenticada.
  • HTTP 200 e HTTP 201 exigem tratamentos diferentes. Leia um resultado concluído diretamente; retenha um ID de tarefa pendente e recupere essa tarefa existente.
  • Uma resposta HTTP bem-sucedida ainda precisa de verificação de dados. Valide organic_results antes de usar as linhas.
  • Preservar a resposta facilita análises posteriores. Salve o JSON antes de selecionar títulos, trechos ou links.

Uma requisição de busca só é útil para uma aplicação quando a aplicação consegue distinguir dados concluídos de uma tarefa que ainda está em execução. Um script rápido que imprime response.text ajuda no começo, mas deixa esses estados misturados.

Este tutorial de Google Search API em Python constrói um pequeno cliente para a Scrapeless Google Search API. Você vai configurar uma consulta, enviá‑la, lidar com uma tarefa pendente e salvar uma resposta que outro script pode inspecionar. O exemplo usa a busca comum na Web. Imagens, Local, Vídeos e Shopping têm seções de resultado diferentes e precisam de suas próprias validações.

O código se comunica com a Scrapeless; não é a Custom Search JSON API nem a Search Console API do Google. Sua aplicação recebe um instantâneo dos resultados de busca, e não relatórios de tráfego do seu site. Se você já trabalha com o modelo de requisição de actors da Scrapeless de forma mais ampla, o envelope de requisição será familiar.

Prerequisites

Você precisa de Python, do pacote requests e de uma chave de API da Scrapeless com acesso ao serviço. Use um ambiente virtual para o projeto e instale Requests com python -m pip install requests. Defina SCRAPELESS_API_KEY no ambiente de processo antes de executar o script. Mantenha a chave fora de arquivos de código‑fonte, notebooks que você compartilha e logs de resposta.

A variável de ambiente local é uma convenção escolhida para este script. O cabeçalho de autenticação HTTP é x-api-token. Eles têm funções diferentes: o Python lê a variável e então envia seu valor no cabeçalho para o endpoint da API.

Salve o programa completo abaixo como google_search.py e execute‑o com python google_search.py. O programa cria serp.json no diretório de trabalho. Use um diretório separado para cada experimento se quiser preservar respostas anteriores.

Configure q, gl, and hl

O parâmetro q fornece a consulta de busca, gl seleciona o país da busca e hl seleciona o idioma da busca. Esses controles pertencem dentro de input, junto com o nome do actor no objeto de requisição que o envolve.

Field Example What to Check
actor scraper.google.search Mantenha o actor no nível superior
input.q coffee Preserve exatamente a consulta que você pretende comparar
input.gl us Registre o país solicitado junto com o resultado
input.hl en Registre o idioma solicitado separadamente

Comece com essa pequena entrada. Adicionar localização e filtros de busca imediatamente torna mais difícil identificar qual parâmetro alterou uma saída. Mantenha os parâmetros atuais do Google Search à mão quando você expandir a requisição.

Envie o corpo com o argumento json= do Requests. Ele serializa o objeto Python como JSON e define o tipo de conteúdo apropriado. Objetos e arrays JSON são estruturas distintas em o formato de dados JSON; uma resposta que é analisada com sucesso não é automaticamente o formato de objeto que sua aplicação espera.

Send a Request and Retrieve a Pending Task

O cliente envia uma tarefa de busca e, em seguida, verifica o endpoint de resultados somente se essa tarefa ainda estiver sendo processada. Uma resposta concluída é retornada ao chamador como um dicionário Python.

O Google Search quickstart usa POST /api/v1/scraper/request. Para esta API, HTTP 201 significa que o processamento está em andamento e inclui taskId. O workflow de resultados de tarefa recupera esse ID com GET /api/v1/scraper/result/{taskId}.
Esta é uma interpretação específica do aplicativo para o código de status. A especificação de semântica HTTP geral define classes de status, enquanto o contrato de serviço informa ao seu cliente como lidar com uma tarefa pendente.

O programa limita as verificações de resultado a dez, com um intervalo de dois segundos. Essas são configurações de cliente de exemplo, não limites do serviço nem um tempo de conclusão prometido. Timeouts de rede se aplicam separadamente a cada requisição. Se a tarefa continuar pendente, a exceção inclui seu ID para que um operador possa retê-la.

python Copy
import json
import os
import time
from pathlib import Path
from urllib.parse import quote

import requests

BASE = "https://api.scrapeless.com/api/v1/scraper"


def google_search(query):
    headers = {"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    response = requests.post(
        BASE + "/request", headers=headers,
        json={"actor": "scraper.google.search", "input": query},
        timeout=(10, 60), allow_redirects=False,
    )
    task_id = None
    for poll in range(11):
        response.raise_for_status()
        if response.status_code not in (200, 201):
            raise RuntimeError(f"Unexpected HTTP status: {response.status_code}")
        data = response.json()
        if not isinstance(data, dict):
            raise ValueError("Expected a JSON object")
        if response.status_code == 200:
            return data
        if task_id is None:
            task_id = data.get("taskId")
        if not isinstance(task_id, str) or not task_id:
            raise ValueError("Pending response has no taskId")
        if poll == 10:
            raise TimeoutError(f"Task still pending; retain taskId={task_id}")
        time.sleep(2)
        response = requests.get(
            BASE + "/result/" + quote(task_id, safe=""),
            headers=headers, timeout=(10, 30), allow_redirects=False,
        )


def organic_rows(data):
    rows = data.get("organic_results")
    if not isinstance(rows, list):
        raise ValueError("organic_results is missing or is not an array")
    if not all(isinstance(row, dict) for row in rows):
        raise ValueError("organic_results contains a non-object item")
    return rows


if __name__ == "__main__":
    query = {"q": "coffee", "gl": "us", "hl": "en"}
    try:
        result = google_search(query)
        Path("serp.json").write_text(
            json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        rows = organic_rows(result)
        print(f"Saved serp.json; organic rows: {len(rows)}")
        for row in rows:
            print(row.get("position"), row.get("title"), row.get("link"))
    except requests.HTTPError as exc:
        raise SystemExit(f"HTTP request failed: {exc.response.status_code}")
    except requests.RequestException:
        raise SystemExit("Network request did not complete")
    except (ValueError, RuntimeError, TimeoutError, KeyError) as exc:
        raise SystemExit(str(exc))

O primeiro raise_for_status() captura respostas de erro HTTP. A verificação explícita de status também rejeita códigos de status inesperados que não sejam erro. A análise do JSON vem depois dessas verificações, e o validador de resultados é executado depois que a API informa que a tarefa foi concluída. Cada etapa responde a uma pergunta diferente.

Comece a Fazer Scraping com o Scrapeless

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

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

Ler organic_results Sem Perder a Resposta Original

O array organic_results contém os registros de resultados orgânicos na resposta concluída. Leia campos como position, title, snippet e link de cada registro, enquanto mantém o objeto original para inspeção.

A requisição coffee de referência usada ao preparar este tutorial retornou HTTP 200 e oito registros orgânicos com gl=us e hl=en. Essa contagem descreve uma resposta. Uma requisição posterior para a mesma consulta pode conter um número diferente de linhas ou uma disposição diferente de recursos de pesquisa.

O programa salva o JSON antes de validar o array de resultados orgânicos. Isso é importante quando uma resposta concluída tem um formato inesperado: você pode inspecionar o que chegou em vez de perdê-lo quando a validação lança uma exceção. A interface de codificação e decodificação JSON do Python permite manter texto não ASCII legível por meio de ensure_ascii=False.

Trate três casos separadamente. Um array vazio é uma coleção observada sem itens orgânicos. Uma chave ausente não tem essa garantia. Um valor do tipo errado é um problema de esquema. O script aceita o primeiro caso e interrompe nos outros dois em vez de substituí-los silenciosamente por uma lista vazia.

Os links retornados também precisam de contexto. Uma URL que parece direta é uma candidata a destino; um intermediário do Google requer tratamento adicional antes que você o considere um site de destino. Este primeiro tutorial imprime o valor retornado sem afirmar que o destino final foi verificado.

Trate Falhas na Camada Correta

Uma exceção deve identificar a etapa que falhou sem expor o cabeçalho de autenticação ou transformar uma requisição com falha em um resultado vazio com aparência de válido.

Observação Significado para Este Cliente Próxima Verificação
Variável de ambiente ausente A autenticação não foi configurada localmente Verifique o ambiente do processo
HTTP 400 A API rejeitou a requisição Verifique nomes, tipos e combinações de entrada
HTTP 429 O serviço informa um limite de requisições Verifique a frequência de requisições e a cota da conta
Outro erro HTTP Nenhum resultado concluído foi aceito Mantenha o status e o contexto da requisição para investigação
JSON inválido O corpo não pôde ser analisado Inspecione a resposta em um log de diagnóstico controlado
Array orgânico ausente O payload não corresponde a este consumidor Inspecione o JSON salvo e o modo de pesquisa solicitado
Limite de tarefas pendentes atingido A conclusão não foi observada por este cliente Retenha o ID da tarefa e marque o job como incompleto

O exemplo evita deliberadamente imprimir cabeçalhos de requisição completos ou corpos de erro do servidor. Em um serviço maior, escreva diagnósticos estruturados com a configuração da consulta, o status e o ID da tarefa quando disponíveis. Registre uma execução com falha separadamente das observações concluídas para que relatórios posteriores não confundam falha com ausência.

Conclusão: Mantenha o Primeiro Cliente Pequeno

Um cliente Python útil para a Google Search API segue um caminho claro: enviar uma consulta, recuperar a tarefa existente se necessário, preservar a resposta e validar os campos que o seu aplicativo consome. Quando esse caminho funcionar, adicione uma dimensão de entrada por vez.
Use os detalhes do produto Google Search API para escolher o serviço e o preço atual para planejar a coleta recorrente. Mantenha a configuração de requisição ao lado de cada resposta salva antes de construir um conjunto de dados maior.

Construa Seu Workflow 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: O Python pode chamar o Google Search API sem um SDK?

Sim. O exemplo usa Requests e o endpoint HTTP documentado. Não requer um agente de IA ou um SDK específico de framework.

P: O HTTP 201 contém o resultado final da busca?

Para esta API, HTTP 201 indica uma tarefa pendente. Preserve taskId e recupere essa tarefa por meio do endpoint de resultado.

P: gl=us prova que todo resultado é americano?

Não. O país é um input de busca, não um rótulo de nacionalidade para cada página retornada. A precisão local precisa de um método de validação separado.

P: Uma chave organic_results ausente deve se tornar uma lista vazia?

Não. Uma chave ausente e um array explicitamente vazio são observações diferentes. Verifique o formato da resposta antes de informar que nenhum registro orgânico foi retornado.

P: Você precisa configurar um proxy separado?

Esta requisição básica não precisa de configuração de proxy separada. A API lida com a recuperação; consulte o contrato de parâmetros antes de adicionar configurações de transporte ou localização.

P: O script verifica o conteúdo por trás de cada link de resultado?

Não. Ele coleta um instantâneo da busca. Verificação de destino e validação do conteúdo da página são etapas separadas.

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