Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Exemplos

Pesquise na web e salve os links de origem

Faça uma busca Google. Salvar links de origem únicos em ordem de resultado, juntamente com a consulta e uso.

Nesta página

Antes de começar

Use uma chave com permissão google_search e créditos disponíveis. Escolha Python 3.10+ com pedidos, ou Bash com cURL 7.76+ e jq. Em Windows, use Git Bash para o caminho Bash.

1. Prepare a consulta

Criar uma pasta de pesquisa na web. Salve o request.json lá, então abra um terminal nessa pasta. Este exemplo requer até cinco resultados orgânicos, uma nova execução submete uma consulta creditável.

web-search/request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}

2. Salve e execute o roteiro

Escolha uma versão e salve seu script ao lado de request.json. Ele lê FLASHDATA_API_KEY, ou pede sua chave sem exibi-la. Um agente deve fornecer a variável ambiental de sua loja secreta.

Corra com o Search-001 como a pasta de saída. O roteiro salva o pedido exato antes de enviá-lo. Correndo novamente com a mesma pasta lê a resposta salva sem chamar o API.

Instale em seu ambiente Python
python -m pip install requests
web-search/search.py
import argparse
import getpass
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved search")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if not isinstance(request, dict) or request.get("source") != "google_search" or not request.get("query"):
        raise SystemExit("request.json must contain google_search and a query")
    key = os.environ.get("FLASHDATA_API_KEY") or getpass.getpass("FlashData API key: ")
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()  # A concurrent run cannot submit into the same folder.
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")

data = json.loads((out / "result.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "google_search" or data.get("status") != "done":
    raise SystemExit("Search did not finish successfully; inspect result.json")
pages = data.get("results")
if not isinstance(pages, list) or any(
    not isinstance(page, dict) or not isinstance(page.get("organic"), list) for page in pages
):
    raise SystemExit("Expected results[].organic arrays; inspect result.json")

sources, seen = [], set()
for page in pages:
    for row in page["organic"]:
        if not isinstance(row, dict):
            raise SystemExit("Expected organic result objects; inspect result.json")
        url = row.get("link")
        if isinstance(url, str) and url.strip() and url not in seen:
            seen.add(url)
            sources.append({field: row.get(field) for field in ("title", "link", "snippet")})
record = {
    "request": json.loads((out / "request.json").read_bytes()),
    "requested_at": (out / "requested-at.txt").read_text().strip(),
    "usage": data.get("usage"), "source_count": len(sources), "result_file": "result.json",
}
for filename, value in (("sources.json", sources), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {len(sources)} sources to {out}/sources.json")
Fuja da pesquisa na web
python search.py search-001

3. Leia as fontes salvas

Impressões de sucesso salvas de fontes para search-001/sources.json. A matriz mantém a primeira ocorrência de cada link exato na ordem de retorno do Google. Linhas sem uma ligação utilizável são omitidas, falta o título ou os valores do trecho permanecem null.

record.json contém a consulta submetida, tempo de solicitação e uso devolvido. Mantenha result.json como resposta completa. Ler esses arquivos é local, uma matriz de fontes vazia é um resultado válido.

Leia os dois arquivos
python -m json.tool search-001/sources.json
python -m json.tool search-001/record.json

Exemplo de saída

Ilustrativo sources.json, títulos ao vivo, links, trechos e contagens variam. Leia as páginas ligadas antes de usar seus trechos como evidência para uma resposta.

web-search/search-001/sources.json
[
  {
    "title": "Battery recycling research",
    "link": "https://example.org/recycling",
    "snippet": "An example search excerpt."
  }
]

Tente uma consulta mais focada

Para focar em um domínio, mude a consulta em request.json para o exemplo abaixo. Escolha uma nova pasta de saída para a nova consulta; search-001 sempre se refere ao seu pedido original salvo.

web-search/request.json
{
  "source": "google_search",
  "query": "site:energy.gov battery recycling research",
  "params": {
    "num": 5
  }
}
Nova consulta. Outro pedido de cobrança
python search.py search-002

Se a busca precisa de atenção

O que aconteceu?O que fazer
401 / 403 / 402Verifique a chave, permissão google_search e equilíbrio, respectivamente. Mantenha essa tentativa, use uma nova pasta de saída apenas quando estiver pronto para enviar novamente.
429Leia Retry-After em response-headers.txt e espere. Os scripts não tentam automaticamente.
Tempo, 5xx ou uma pasta incompletaMantenha os arquivos salvos e verifique History antes de criar outra tentativa. Repetir a mesma pasta não faz nenhum pedido novo.
JSON inválido, status falhado ou campos inesperadosInspecione result.json antes de extrair fontes. Uma resposta inválida não deve ser tratada como uma busca de sucesso vazia.
Nenhuma fonte útilReveja a consulta salva. Faça-o mais específico ou remova um filtro muito estreito, e então escolha uma nova pasta para outra consulta.

Salve inspect_search.py na pesquisa na web/ antes de executá-lo.

web-search/inspect_search.py
from pathlib import Path

for name in ("http-status.txt", "response-headers.txt", "result.json"):
    path = Path("search-001") / name
    print(f"--- {name} ---")
    print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")
Inspecione localmente
python inspect_search.py