Une API SERP exécute une requête de moteur de recherche pour vous et renvoie la page de résultats sous forme de JSON structuré : résultats organiques avec leurs positions, annonces, extraits optimisés, résultats locaux et plus encore. Plutôt que de construire des scrapers pour Google et de les maintenir fonctionnels, vous envoyez une requête et lisez les champs dont vous avez besoin.
Ce guide explique comment en configurer une de A à Z : obtenir et stocker une clé API, effectuer votre première recherche, obtenir des résultats pour le bon emplacement et le bon appareil, gérer les erreurs, et transformer les résultats en vérification de classement. Il utilise la SERP API de Shifter comme exemple ; la plupart des API SERP fonctionnent de la même manière.
Étape 1 : obtenir votre clé API
Chaque requête contient une clé API. Dans le panneau de Shifter, ouvrez SERP API, puis API Keys, et copiez une clé active.
Traitez la clé comme un mot de passe :
- Gardez-la hors du code et des dépôts. Stockez-la dans une variable d’environnement ou un gestionnaire de secrets.
- Utilisez des clés séparées pour le développement et la production lorsque c’est possible, afin qu’une clé de test divulguée ne puisse pas affecter la production.
- Faites tourner une clé si elle a pu être exposée, et mettez-la à jour partout où elle est utilisée.
export SHIFTER_SERP_KEY="your-key-here"Étape 2 : lancer votre première recherche
L’API est un point de terminaison unique, https://serp.shifter.io/v1. Choisissez le moteur de recherche avec engine et passez la requête comme q :
curl "https://serp.shifter.io/v1?engine=google&api_key=$SHIFTER_SERP_KEY&q=residential+proxies"La réponse est en JSON. Pour une recherche Google, organic_results contient les résultats ordinaires, chacun avec une position, un title, un link, un displayed_link et un snippet. D’autres sections, comme les annonces et les résultats locaux, apparaissent lorsque la page de résultats les contient.
Le même point de terminaison couvre d’autres moteurs de recherche et surfaces Google : changez engine en bing ou yandex pour ces moteurs de recherche, ou en google_maps, google_news ou google_shopping pour d’autres résultats Google. Le reste de ce guide s’applique à tous ; seuls les champs de la réponse changent.
Étape 3 : obtenir des résultats pour le bon lieu et le bon appareil
Les résultats de recherche diffèrent selon l’emplacement, la langue et l’appareil, souvent de manière importante. Une vérification de classement qui ne fixe pas tous ces paramètres mesure une page de résultats différente à chaque fois.
| Paramètre | Ce qu’il définit | Exemple |
|---|---|---|
location | D’où la recherche est effectuée | Austin,Texas,United States |
gl | Le pays des résultats | us |
hl | La langue de l’interface | en |
device | Résultats bureau, mobile ou tablette | mobile |
Indiquez l’emplacement de manière complète (ville, région, pays), car des noms courts comme « Springfield » sont ambigus. Notre guide sur les API SERP géociblées pour le SEO local explique pourquoi la précision de l’emplacement compte autant.
Étape 4 : gérer les erreurs
Les requêtes peuvent échouer pour des raisons passagères et des raisons qui ne le sont pas :
- Réessayez les limitations de débit et les erreurs serveur temporaires, avec une pause qui s’allonge à chaque fois.
- Arrêtez et corrigez les erreurs d’authentification et de requête malformée ; les réessayer ne fait que répéter l’échec.
- Définissez un délai d’expiration sur chaque requête, pour qu’une recherche lente ne bloque pas toute une exécution.
Assembler le tout
L’assistant ci-dessous lit la clé depuis l’environnement, envoie toujours l’emplacement, la langue et l’appareil, réessaie les erreurs qui méritent de l’être, et inclut une fonction qui trouve où un domaine se classe dans les résultats organiques :
import os
import time
from urllib.parse import urlparse
import requests
API = "https://serp.shifter.io/v1"
RETRY = {408, 429, 500, 502, 503}
def google_search(query, location, gl="us", hl="en", device="desktop", session=None, attempts=3):
"""One Google search as seen from `location`, returned as parsed JSON."""
session = session or requests.Session()
params = {"engine": "google", "api_key": os.environ["SHIFTER_SERP_KEY"], "q": query,
"location": location, "gl": gl, "hl": hl, "device": device}
for attempt in range(1, attempts + 1):
response = session.get(API, params=params, timeout=60)
if response.status_code == 200:
return response.json()
if response.status_code not in RETRY or attempt == attempts:
raise RuntimeError(f"{query!r}: HTTP {response.status_code} {response.text[:200]}")
time.sleep(2 * attempt)
def rank_of(serp, domain):
"""Position of the first organic result on `domain`, or None if it is not there."""
for result in serp.get("organic_results", []):
host = urlparse(result["link"]).netloc.lower()
if host == domain or host.endswith("." + domain):
return result["position"]
return NoneVérifier où un site se classe pour deux mots-clés, vu depuis un mobile à Austin :
from serp import google_search, rank_of
keywords = ["emergency plumber", "water heater repair"]
for keyword in keywords:
serp = google_search(keyword, location="Austin,Texas,United States", device="mobile")
print(keyword, rank_of(serp, "example-plumbing.com"))Nous avons testé les paramètres de requête de l’assistant, les tentatives de réessai, la gestion des erreurs et la recherche de classement face à des réponses simulées.
Étape 5 : en faire un suivi de classement
Une recherche est un instantané. Le suivi consiste à exécuter les mêmes recherches selon un calendrier et à stocker les résultats :
- Fixez la liste de mots-clés ainsi que l’emplacement, la langue et l’appareil pour chacun.
- Exécutez selon un calendrier, quotidien ou hebdomadaire selon l’ampleur des mouvements de classement sur votre marché.
- Stockez chaque réponse complète avec son horodatage et ses paramètres, pas seulement la position, afin de pouvoir revenir sur ce qui a changé.
- Alertez sur les changements qui comptent : une sortie du top trois, un concurrent apparaissant au-dessus de vous, un extrait optimisé perdu.
Notre guide sur l’automatisation du suivi quotidien des positions de mots-clés couvre plus en détail la planification et le stockage. Si le suivi de classement est un élément central de votre travail, notre page surveillance SEO couvre la configuration plus large.
Erreurs courantes de configuration
- Aucun emplacement défini. Les résultats proviennent alors d’un emplacement par défaut qui n’est probablement pas votre marché.
- Mélanger bureau et mobile entre les exécutions, ce qui fait sauter les classements sans raison réelle.
- Faire correspondre par URL exacte plutôt que par domaine, de sorte qu’une page classée dont le chemin a changé semble être un classement perdu.
- Ne stocker que les positions. Sans la réponse complète, vous ne pouvez pas savoir pourquoi une position a changé.
- Coder la clé en dur, ce qui finit tôt ou tard dans un dépôt.
FAQ
Qu’est-ce qu’une API SERP ?
Un service qui exécute des requêtes de moteur de recherche pour vous et renvoie la page de résultats sous forme de données structurées, telles que les résultats organiques avec positions, les annonces, les extraits optimisés et les résultats locaux, afin que vous n’ayez pas à scraper et analyser vous-même les pages de recherche.
Comment obtenir une clé API SERP ?
Inscrivez-vous auprès d’un fournisseur d’API SERP et créez une clé dans son tableau de bord. Dans le panneau de Shifter, les clés se trouvent sous SERP API, puis API Keys. Stockez la clé dans une variable d’environnement plutôt que dans votre code.
Pourquoi mes résultats d’API SERP diffèrent-ils de ce que je vois dans Google ?
Généralement parce que l’emplacement, la langue, l’appareil ou la personnalisation diffèrent. Vos propres recherches sont personnalisées et proviennent de votre emplacement ; définissez explicitement l’emplacement, la langue et l’appareil de l’API pour correspondre au marché que vous souhaitez mesurer.
À quelle fréquence dois-je vérifier les classements ?
Quotidiennement pour les mots-clés concurrentiels et les marchés à évolution rapide, hebdomadairement pour la plupart des autres. Gardez les paramètres identiques entre les exécutions afin que les changements reflètent les résultats, et non la mesure.
L’essentiel
Configurer une API SERP prend quelques étapes : stocker la clé en toute sécurité, envoyer la requête avec le moteur, l’emplacement, la langue et l’appareil fixés, réessayer seulement les erreurs susceptibles de passer, et lire les positions dans les résultats structurés. Exécutez les mêmes recherches selon un calendrier, conservez les réponses complètes, et vous disposez d’un traceur de classement qui mesure la même page de résultats à chaque fois.