API de Pesquisa do Google: De Consultas de Pesquisa a JSON Estruturado

TL;DR:

• A API de Pesquisa do Google Scrapeless retorna resultados de pesquisa como JSON estruturado. Use campos de resultados orgânicos em ferramentas de pesquisa, relatórios de SEO e fluxos de trabalho de descoberta de fonte.
• O contexto da pesquisa pertence ao resultado. Mantenha a consulta, país, idioma e tempo de observação juntos para que comparações posteriores tenham um significado claro.
• Uma tarefa pendente é diferente de um conjunto de resultados vazio. Lide com o HTTP 201 separadamente antes de tentar ler organic_results ou criar um CSV.

Os dados de pesquisa do Google se tornam úteis quando uma equipe pode conectar cada resultado à pergunta e ao mercado que o produziram. Um título e URL copiados para uma planilha perdem muito desse contexto. Uma resposta estruturada permite que uma aplicação preserve isso desde o início.

A API de Pesquisa do Google Scrapeless atualizada fornece uma rota gerenciada de uma consulta de pesquisa para JSON. Sua aplicação envia a solicitação e decide como usar os dados retornados. O gerenciamento de proxy e CAPTCHA é executado no lado do serviço, reduzindo a infraestrutura de coleta que sua equipe precisa manter.

Este guia segue essa entrega: escolha um contexto de pesquisa, envie uma solicitação, leia a resposta e salve um conjunto de dados que outra pessoa possa entender.

O que a API de Pesquisa do Google Retorna

A API de Pesquisa do Google retorna dados de pesquisa estruturados, com resultados orgânicos disponíveis no array de nível superior organic_results quando presentes. Um resultado natural pode incluir position, title, link e snippet. A resposta também pode conter informações de paginação e outros módulos de pesquisa, dependendo da consulta e dos resultados retornados.

Mantenha a resposta original antes de extrair um subconjunto. Uma tabela plana é conveniente para análise, mas não pode representar todos os objetos aninhados sem um mapeamento deliberado. O modelo de dados JSON distingue arrays, objetos, strings, números, booleanos e null; preservar essas distinções torna o processamento posterior mais fácil.

Um snippet é um trecho de resultado de pesquisa. Ele não fornece o conteúdo completo da página de destino. Se uma aplicação de pesquisa precisar da evidência de um artigo, a aplicação deve obter e revisar essa página separadamente.

Prepare uma Pequena Primeira Solicitação

Uma primeira solicitação precisa de uma chave de API Scrapeless, uma consulta e um cliente que possa enviar JSON via HTTP. Use uma conta com acesso à API de Pesquisa do Google e mantenha a chave na variável de ambiente SCRAPELESS_API_KEY.

Para o exemplo em Python abaixo, instale o pacote requests no seu ambiente de projeto. Os módulos restantes vêm da biblioteca padrão do Python. Salve o script como google_search_export.py, depois execute-o com python3 google_search_export.py após definir a variável de ambiente através do seu shell local ou gerente de segredos.

O exemplo usa a consulta neutra coffee, país us e idioma en. Comece com essa pequena entrada antes de introduzir uma lista de palavras-chave ou um trabalho agendado. Inspecione a forma da resposta primeiro; o modelo de dados a montante depende disso.

A solicitação autenticada é um pré-requisito que requer sua própria chave de conta. A forma da solicitação do exemplo segue a referência atual da API; não é apresentada como uma execução ao vivo capturada de uma conta.

Escolha País, Idioma e Modo de Entrada

País, idioma e localização descrevem diferentes partes de uma solicitação de pesquisa. gl seleciona o país de pesquisa, hl seleciona o idioma de pesquisa e location especifica de onde a pesquisa deve se originar. google_domain seleciona o domínio do Google. A opção do dispositivo atual suporta desktop.

O modelo de parâmetros da API de Pesquisa do Google também possui duas regras de entrada que afetam como você constrói solicitações:

• Use q para uma consulta expressa através de parâmetros individuais. Alternativamente, forneça uma url completa da Pesquisa do Google; quando url é fornecido, outros parâmetros de entrada são ignorados.
• Escolha entre location ou uule. Eles não podem ser usados ​​juntos.

Para uma comparação entre mercados, salve o objeto de entrada completo com cada resposta. Definir o mesmo país e idioma torna o contexto pretendido explícito, mas não garante resultados idênticos entre as observações ou reproduz o histórico de pesquisa assinado de uma pessoa específica.
Consultas podem incluir operadores como site:, inurl: e intitle:. Use-os para restringir uma questão de pesquisa. Uma pesquisa restrita ao site não é um inventário completo de páginas indexadas, portanto, seus resultados não devem se tornar uma contagem exata de cobertura de índice.

Solicitar JSON e Exportar Resultados Orgânicos

A solicitação utiliza POST https://api.scrapeless.com/api/v1/scraper/request, o ator scraper.google.search e um cabeçalho x-api-token. O script salva a resposta com seu tempo de entrada e recebimento, e depois exporta os resultados orgânicos para CSV após HTTP 200.

Nota: A solicitação de rede requer sua chave API Scrapeless e não foi executada com uma conta ativa para este artigo. O script preserva uma resposta de tarefa HTTP 201 para inspeção; ele não implementa a recuperação de resultado de tarefa.

import csv
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests


def spreadsheet_text(value):
    text = "" if value is None else str(value)
    if text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r")):
        return "'" + text
    return text


def export_results(payload, context, received_at, output_path):
    results = payload.get("organic_results")
    if not isinstance(results, list):
        print("No usable organic_results array; inspect the saved JSON.")
        return
    fields = ["q", "gl", "hl", "received_at", "position", "title", "link", "snippet"]
    with output_path.open("w", encoding="utf-8", newline="") as stream:
        writer = csv.DictWriter(stream, fieldnames=fields)
        writer.writeheader()
        for item in results:
            if not isinstance(item, dict):
                raise ValueError("Unexpected organic result item; inspect the saved JSON.")
            row = {name: item.get(name) for name in ("position", "title", "link", "snippet")}
            row.update(context, received_at=received_at)
            writer.writerow({name: spreadsheet_text(row.get(name)) for name in fields})
    print(f"Exported {len(results)} organic results to {output_path}")


def main():
    context = {"q": "coffee", "gl": "us", "hl": "en"}
    response = requests.post(
        "https://api.scrapeless.com/api/v1/scraper/request",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        json={"actor": "scraper.google.search", "input": context},
        timeout=120,
    )
    response.raise_for_status()
    received_at = datetime.now(timezone.utc).isoformat()
    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    payload = response.json()
    record = {"input": context, "received_at": received_at,
              "http_status": response.status_code, "response": payload}
    output = Path(f"google-search-{run_id}.json")
    output.write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
    if response.status_code == 201:
        print(f"Task pending. Inspect taskId in {output}; no CSV was created.")
        return
    if response.status_code != 200 or not isinstance(payload, dict):
        raise ValueError(f"Unexpected response; inspect {output}")
    export_results(payload, context, received_at, output.with_suffix(".csv"))


if __name__ == "__main__":
    main()

O tempo limite 120 é uma configuração do cliente neste exemplo, não uma promessa de tempo de resposta do serviço. O tempo de recebimento é registrado pelo cliente após a chegada da resposta; não é um timestamp fornecido pelo Google.

O escritor CSV do Python lida com delimitadores e campos entre aspas. O auxiliar também prefixa marcadores de fórmula comuns de planilha no texto exportado. Preserve o JSON como o registro original, porque o CSV é uma visualização transformada destinada à inspeção. Revise as configurações de importação de texto antes de abrir valores provenientes de fontes externas em uma planilha.

O exemplo exporta apenas q, gl e hl de sua entrada. Se você adicionar uma localização, domínio ou deslocamento de paginação, estenda as colunas CSV para manter essas dimensões também. O JSON salvo já contém o objeto completo de entrada.

Interpretar a Resposta Antes de Construir um Relatório

Uma resposta HTTP 200 contém os dados da tarefa, enquanto HTTP 201 indica processamento e fornece um taskId. Uma tarefa pendente não deve criar uma observação de resultados vazios. O script mantém seu registro JSON e pula a exportação CSV nesse caso.

Para respostas de dados bem-sucedidas, distingue-se um array vazio de um campo organic_results ausente ou inutilizável. Outros módulos ainda podem estar presentes. O script preserva a resposta e pede que você a inspecione quando não existir um array utilizável.

Leia position como a posição fornecida para aquele resultado retornado. Antes de combinar páginas em uma classificação global, verifique como o endpoint numera posições para suas solicitações. start controla o deslocamento de resultados, e informações de paginação podem guiar solicitações subsequentes; nenhum dos dois estabelece que todos os resultados do Google podem ser recuperados.

Aproveitar Dados de Pesquisa Estruturados

Resultados de pesquisa estruturada fornecem entradas para fluxos de trabalho que sua aplicação constrói em torno da API. A unidade útil é um resultado mais seu contexto de solicitação e hora da observação.

• Snapshots de SEO: salve observações para uma lista fixa de palavras-chave e depois compare contextos correspondentes ao longo do tempo. Agendamento, armazenamento e detecção de mudanças pertencem ao seu pipeline.
• Pesquisa de marca e concorrentes: revise quais domínios e títulos de páginas aparecem para suas consultas selecionadas. O exemplo descreve essas pesquisas, ao invés de todas as menções na web ou o tráfego de um site.
• Descoberta de fontes de IA: passe títulos, links e trechos candidatos para uma etapa de seleção de fontes. Busque páginas completas separadamente quando evidências forem necessárias e verifique se as alegações geradas correspondem às suas fontes.

Para uma equipe de conteúdo, a primeira saída pode ser uma lista de leitura curta com a consulta e o mercado anexados. Para um desenvolvedor, pode ser uma exportação repetível usada por um relatório existente. Ambos começam com um registro de dados que torna seu escopo visível.

Use estes exemplos para informações públicas que você está autorizado a coletar e usar. Mantenha os campos necessários para a tarefa, proteja credenciais e revise as condições que se aplicam ao reuso subsequente.

Conclusão

A Google Search API oferece a uma aplicação dados estruturados de pesquisa para trabalhar. Uma integração útil também preserva a entrada, verifica o estado da tarefa e separa a descoberta de fontes da análise posterior. Comece com uma única consulta e inspecione o JSON salvo antes de expandir o fluxo de trabalho.

O fluxo de trabalho atualizado da Google Search API fornece os detalhes de conexão para adaptar este exemplo ao seu próprio projeto.

FAQ

Q: Este é um API fornecido pelo Google?

Este artigo descreve a Scrapeless Google Search API, um serviço da Scrapeless para recuperar dados de pesquisa do Google. Não reivindica uma parceria oficial com o Google.

Q: Você precisa gerenciar um navegador ou proxy?

A API gerenciada lida com a infraestrutura de coleta do lado do serviço. Seu cliente envia solicitações HTTP e processa os dados retornados.

Q: A API inclui dados de classificação histórica?
O fluxo de trabalho descrito aqui cria história ao salvar suas próprias observações. Ele não recupera um histórico de classificação pré-existente.

Q: O mesmo API pode buscar imagens?

O produto suporta buscas de imagem do Google, com tbm=isch identificado na referência de parâmetros. Inspecione a resposta da imagem separadamente; o mapeamento CSV deste artigo é para resultados da web orgânica.

Q: Um snippet de busca contém a página completa?

Um snippet é um excerto associado a um resultado de busca. Um fluxo de trabalho que precisa da evidência completa da página deve obter e revisar o conteúdo de destino separadamente.

Q: O que deve acontecer quando a solicitação retorna HTTP 201?

Preserve o taskId e trate a tarefa como pendente. Complete o fluxo de trabalho de resultado da tarefa documentado antes de processá-lo como dados de busca finalizados.