Saltar al contenido
ES
Obtener clave API
Explorar documentación

Ejemplos

Busca en la web y guarda los enlaces a las fuentes

Haz una búsqueda en Google. Guarda los enlaces sin duplicados en el orden de los resultados, junto con la consulta y el consumo.

En esta página

Antes de empezar

Use una llave con google_search permiso y créditos disponibles. Elija Python 3.10+ con solicitudes, o Bash con cURL 7.76+ y jq. On Windows, uso Git Bash para el Bash camino.

1. Prepara la consulta

Crear una carpeta de búsqueda web. Guardar request.json allí, luego abrir un terminal en esa carpeta. Este ejemplo solicita hasta cinco resultados orgánicos; una nueva ejecución presenta una consulta facturable.

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

2. Guardar y ejecutar el script

Elija una versión y guarde su script junto a request.json. Lee FLASHDATA_API_KEY, o los avisos para su clave sin mostrarla. Un agente debe suministrar la variable de entorno de su tienda secreta.

Corre con search-001 como la carpeta de salida. El script guarda la solicitud exacta antes de enviarla. Correr de nuevo con la misma carpeta lee la respuesta guardada sin llamar al API.

Instalar en su entorno 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")
Ejecutar desde la Web-search/
python search.py search-001

3. Lea las fuentes salvas

Si se completa correctamente, se muestra Saved N sources to search-001/sources.json. El array conserva la primera aparición de cada enlace exacto en el orden devuelto por Google. Se omiten las filas sin un enlace utilizable; los valores de título o fragmento ausentes permanecen como null.

record.json contiene la consulta presentada, el tiempo de solicitud y el uso devuelto. Mantenga result.json como la respuesta completa. Leer estos archivos es local; un array de fuentes vacías es un resultado válido.

Lea ambos archivos
python -m json.tool search-001/sources.json
python -m json.tool search-001/record.json

Producto de ejemplo

Ilustrativo sources.json; los títulos en vivo, los enlaces, los fragmentos y los conteos varían. Lea las páginas enlazadas antes de usar sus fragmentos como evidencia para una respuesta.

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

Prueba una consulta más enfocada

Para centrarse en un dominio, cambie la consulta en request.json al ejemplo a continuación. Elija una nueva carpeta de salida para la nueva consulta; search-001 siempre se refiere a su solicitud guardada original.

web-search/request.json
{
  "source": "google_search",
  "query": "site:energy.gov battery recycling research",
  "params": {
    "num": 5
  }
}
Nueva consulta · otra solicitud facturable
python search.py search-002

Si la búsqueda necesita atención

Qué pasó.Qué hacer
401 / 403 / 402Compruebe la clave, permiso y equilibrio google_search, respectivamente. Mantenga este intento; utilice una nueva carpeta de salida sólo cuando esté listo para enviar de nuevo.
429Lea Retry-After en response-headers.txt y espere. Los scripts no reingresan automáticamente.
Timeout, 5xx o una carpeta incompletaMantener los archivos guardados y comprobar la historia antes de crear otro intento. Recorrer la misma carpeta no hace nueva solicitud.
JSON inválido, estado fallido o campos inesperadosInspeccione result.json antes de extraer fuentes. Una respuesta inválida no debe ser tratada como una búsqueda con éxito vacío.
No son fuentes útilesRevise la consulta guardada. Haga que sea más específico o eliminar un filtro demasiado estrecho, a continuación, elegir una nueva carpeta para otra consulta.

Guardar inspect_search.py en la búsqueda web/ antes de ejecutarlo.

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")
Inspeccionar localmente
python inspect_search.py