Aller au contenu
FR
Obtenir une clé API

Google Search / Python

API Google Search : pays, langue et pagination en Python

Utilisez gl, hl et location pour obtenir des résultats Google localisés, parcourir les pages et enregistrer les paramètres de recherche renvoyés, avec Python.

FlashData · Publié

Résultats de recherche localisés autour d'un globe avec plusieurs pages de résultats

Les mots recherchés ne sont qu’une partie d’une requête Google. Pour les mêmes mots, une personne qui étudie Londres et une autre qui étudie Singapour peuvent avoir besoin de résultats différents. Ce guide montre comment préciser le pays, la langue de l’interface et la ville, puis collecter quelques pages de résultats sans compter deux fois les mêmes URL.

Vous allez créer un script Python 3 qui enregistre les résultats et les paramètres de recherche renvoyés par l’API. Pour une première requête, commencez par le tutoriel Exporter les résultats Google en CSV.

À quoi servent gl, hl et location ?

  • gl est le code pays à deux lettres, par exemple gb, us ou sg.

  • hl sélectionne la langue de l’interface Google, par exemple en ou de. Cela ne signifie pas que toutes les pages renvoyées seront rédigées dans cette langue.

  • location précise le lieu de recherche. Utilisez un nom de ville explicite, par exemple London, England, United Kingdom, lorsque le contexte local compte.

Combinez ces paramètres pour définir explicitement votre recherche. Le lieu est transmis à la source de recherche ; il ne garantit pas des résultats identiques à ceux du navigateur d’une personne donnée. Le type de recherche, les mots recherchés, le moment de la requête et les données disponibles peuvent modifier la réponse. Consultez results[0].searchParameters pour vérifier les valeurs appliquées par le service.

Préparer la clé API et le budget de requêtes

Créez une clé API et vérifiez que le compte dispose de crédits. Conservez la clé dans une variable d’environnement, jamais dans le dépôt de code ni dans du JavaScript exécuté par le navigateur. Le code utilise uniquement la bibliothèque standard de Python.

bash
export FLASHDATA_API_KEY='your-api-key'
export SEARCH_QUERY='coworking spaces'
export SEARCH_COUNTRY='gb'
export SEARCH_LANGUAGE='en'
export SEARCH_LOCATION='London, England, United Kingdom'
export SEARCH_MAX_PAGES='3'

num permet de demander entre 1 et 100 résultats et page accepte les valeurs de 1 à 100. Le nombre de résultats renvoyés peut être inférieur au nombre demandé. Chaque page correspond à une requête facturée séparément. Cet exemple demande jusqu’à trois pages, s’arrête sur une page vide et ne relance pas automatiquement les envois qui ont échoué.

Collecter les résultats localisés avec leur contexte

Enregistrez ce code dans localized-search.py. Le script associe chaque résultat à la page demandée, conserve la valeur d’origine de position lorsqu’elle est présente et supprime uniquement les URL strictement identiques. Il ne calcule pas de classement global à partir de (page - 1) × num : le nombre de résultats renvoyés peut varier.

python
import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

key = os.environ["FLASHDATA_API_KEY"]
max_pages = int(os.getenv("SEARCH_MAX_PAGES", "3"))
if not 1 <= max_pages <= 100:
    raise ValueError("SEARCH_MAX_PAGES must be between 1 and 100")

query = os.getenv("SEARCH_QUERY", "coworking spaces")
settings = {
    "gl": os.getenv("SEARCH_COUNTRY", "gb"),
    "hl": os.getenv("SEARCH_LANGUAGE", "en"),
    "location": os.getenv("SEARCH_LOCATION", "London, England, United Kingdom"),
    "num": 10,
}
rows, pages, seen = [], [], set()
for page in range(1, max_pages + 1):
    payload = {"source": "google_search", "query": query,
               "params": {**settings, "page": page}}
    request = Request(
        "https://data.flashdata.dev/v1/queries/realtime",
        data=json.dumps(payload).encode(), method="POST",
        headers={"Content-Type": "application/json", "X-API-Key": key},
    )
    try:
        with urlopen(request, timeout=60) as response:
            body = json.load(response)
    except HTTPError as error:
        raise RuntimeError(f"Search failed: HTTP {error.code}. Check the request and account before resubmitting.") from error
    if body.get("error") or body.get("status") != "done":
        raise RuntimeError("Search did not complete. Check Request History before resubmitting.")
    if not isinstance(body.get("results"), list) or not body["results"]:
        raise RuntimeError("Expected a search result object")
    result = body["results"][0]
    organic = result.get("organic", [])
    pages.append({"requestedPage": page, "requestedParams": payload["params"],
                  "reportedParams": result.get("searchParameters"),
                  "returnedCount": len(organic), "usage": body.get("usage")})
    for item in organic:
        link = item.get("link")
        if link and link not in seen:
            seen.add(link)
            rows.append({"requestedPage": page, **item})
    if not organic:
        break

Path("localized-results.json").write_text(
    json.dumps({"query": query, "pages": pages, "organic": rows}, indent=2),
    encoding="utf-8",
)
print(f"Saved {len(rows)} unique URLs from {len(pages)} pages")
bash
python3 localized-search.py

Examiner les résultats avant de comparer les marchés

Le fichier JSON contient, dans pages, une entrée par requête terminée, ainsi qu’un tableau organic de liens uniques. Conservez requestedParams et reportedParams avec vos données. Un champ absent doit rester absent ou null ; n’inventez pas de valeur de pays ou de lieu lorsque la réponse n’en fournit pas.

Pour comparer deux marchés, gardez les mêmes mots recherchés et le même nombre maximal de pages, puis modifiez délibérément le pays, la langue et le lieu. Enregistrez la date de collecte dans votre application pour établir des comparaisons historiques. Les différences entre les résultats décrivent ces requêtes ; elles ne prouvent pas un changement durable de classement.

Pourquoi une page contient-elle moins de résultats ?

La recherche peut renvoyer des résultats enrichis en plus des liens organiques, et la source peut fournir moins de liens organiques que demandé. Comptez les éléments du tableau renvoyé. Une page sans liens organiques suffit à arrêter ce petit script ; elle ne signifie pas que Google n’a plus aucune page pertinente.

Pour une erreur 401 ou 403, vérifiez la clé API et ses permissions. Pour une erreur de crédits ou de limite de débit, résolvez d’abord le problème de solde ou de fréquence des requêtes. Un délai réseau dépassé ne prouve pas qu’une requête payante n’a pas été exécutée ; consultez Request History avant de la soumettre à nouveau.

Pour la suite, consultez la référence des paramètres de l’API Google Search, le guide async et Batch, ou la présentation de Google Search.