Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Exemples

Rechercher sur le web et enregistrer les sources

Lancez une recherche Google. Enregistrez les liens uniques dans l’ordre des résultats, ainsi que la requête et la consommation.

Sur cette page

Avant de commencer

Utilisez une clé autorisant google_search et un compte disposant de crédits. Choisissez Python 3.10+ avec requests, ou Bash avec cURL 7.76+ et jq. Sous Windows, utilisez Git Bash pour la version Bash.

1. Préparer la requête

Créez un dossier web-search. Enregistrez-y request.json, puis ouvrez un terminal dans ce dossier. Cet exemple demande au maximum cinq résultats naturels ; chaque nouvelle exécution soumet une requête facturable.

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

2. Enregistrer et exécuter le script

Choisissez une version et enregistrez son script à côté de request.json. Il lit FLASHDATA_API_KEY ou vous demande la clé sans l’afficher. Un agent doit fournir cette variable d’environnement depuis son gestionnaire de secrets.

Utilisez search-001 comme dossier de sortie. Le script enregistre la requête exacte avant de l’envoyer. Si vous réutilisez ce dossier, il lit la réponse enregistrée sans appeler l’API.

Installer dans votre environnement 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")
Exécuter depuis web-search/
python search.py search-001

3. Lire les sources enregistrées

En cas de succès, le script affiche Saved N sources to search-001/sources.json. Le tableau conserve la première occurrence de chaque lien exact, dans l’ordre renvoyé par Google. Les lignes sans lien utilisable sont omises ; un titre ou un extrait manquant reste null.

record.json contient la requête soumise, sa date et sa consommation déclarée. Conservez result.json pour la réponse complète. Ces fichiers se lisent localement ; un tableau sources vide est un résultat valide.

Lire les deux fichiers
python -m json.tool search-001/sources.json
python -m json.tool search-001/record.json

Exemple de sortie

Exemple de sources.json. Les titres, liens, extraits et nombres de résultats réels varient. Lisez les pages liées avant d’utiliser leurs extraits pour étayer une réponse.

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

Affiner la recherche

Pour cibler un domaine, remplacez query dans request.json par l’exemple ci-dessous. Choisissez un nouveau dossier de sortie pour cette requête ; search-001 reste associé à sa requête d’origine.

web-search/request.json
{
  "source": "google_search",
  "query": "site:energy.gov battery recycling research",
  "params": {
    "num": 5
  }
}
Nouvelle recherche · nouvelle requête facturable
python search.py search-002

Résoudre les problèmes de recherche

ProblèmeSolution
401 / 403 / 402Vérifiez respectivement la clé, l’autorisation google_search et le solde. Conservez cette tentative ; utilisez un nouveau dossier de sortie uniquement lorsque vous êtes prêt à soumettre à nouveau la requête.
429Lisez Retry-After dans response-headers.txt et attendez. Les scripts ne réessaient pas automatiquement.
Délai dépassé, erreur 5xx ou dossier incompletConservez les fichiers enregistrés et consultez History avant de créer une nouvelle tentative. Réutiliser le même dossier n’envoie aucune nouvelle requête.
JSON invalide, état d’échec ou champs inattendusInspectez result.json avant d’extraire les sources. Une réponse invalide ne doit pas être traitée comme une recherche réussie sans résultat.
Aucune source utileRelisez la requête enregistrée. Précisez-la ou retirez un filtre trop restrictif, puis choisissez un nouveau dossier pour lancer une autre recherche.

Enregistrez inspect_search.py dans web-search/ avant de l’exécuter.

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")
Inspecter localement
python inspect_search.py