Démarrage rapide de l'API SERP : votre première recherche en curl, Python et Node.js

Comment lancer ma première recherche avec curl ?

Exportez la clé une fois, puis envoyez une seule requête GET. L'option -G avec --data-urlencode construit la query string et encode les espaces et les accents pour vous. La réponse est un seul document JSON, et jq le garde lisible dans un terminal.

L'exemple interroge Google, le moteur par défaut, pour des résultats US en anglais. Modifiez q, gl ou hl et relancez : chaque exécution réussie utilise un crédit.

export SERPCRYPTO_API_KEY="paste-your-key-here"

curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=best espresso grinder" \
  -d gl=us -d hl=en | jq '.organic_results[:3]'

Comment lancer la même recherche en Python ?

Utilisez n'importe quel client HTTP. Avec requests, passez les paramètres sous forme de dictionnaire et la clé dans l'en-tête. raise_for_status() transforme une réponse d'erreur, comme 401 pour une mauvaise clé, en exception que vous pouvez intercepter.

import os

import requests

API_URL = "https://serpcrypto.com/api/v1/search"
API_KEY = os.environ["SERPCRYPTO_API_KEY"]

response = requests.get(
    API_URL,
    params={"q": "best espresso grinder", "gl": "us", "hl": "en"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

print("credits used:", data["search_metadata"]["credits_used"])
for result in data.get("organic_results", [])[:3]:
    print(result["position"], result["title"], result["link"])

Et en Node.js ?

Node.js 18 et les versions suivantes embarquent fetch, aucun paquet n'est donc nécessaire. Enregistrez le fichier avec l'extension .mjs pour utiliser await au niveau supérieur, puis lancez node first-search.mjs.

// first-search.mjs (Node.js 18 or later: fetch and top-level await are built in)
const API_URL = "https://serpcrypto.com/api/v1/search";
const params = new URLSearchParams({ q: "best espresso grinder", gl: "us", hl: "en" });

const response = await fetch(`${API_URL}?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SERPCRYPTO_API_KEY}` },
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const data = await response.json();

console.log("credits used:", data.search_metadata.credits_used);
for (const result of (data.organic_results ?? []).slice(0, 3)) {
  console.log(result.position, result.title, result.link);
}

Comment puis-je vérifier combien de crédits il me reste ?

Appelez GET https://serpcrypto.com/api/v1/credits avec la même clé. C'est gratuit et renvoie trois nombres : les crédits restants, les crédits utilisés aujourd'hui et le nombre de requêtes que votre compte peut exécuter en même temps. Chaque compte peut lancer un nombre défini de recherches en même temps ; la limite est indiquée dans votre tableau de bord et augmentée sur demande.

curl -s "https://serpcrypto.com/api/v1/credits" -H "Authorization: Bearer $SERPCRYPTO_API_KEY"

{
  "credits_remaining": 84210,
  "credits_used_today": 1290,
  "concurrency_limit": 10
}

Que renvoie une requête ?

Chaque réponse a la même structure sur tous les moteurs. search_metadata indique si la recherche a réussi et combien de crédits elle a consommés. search_parameters reprend les paramètres appliqués, valeurs par défaut comprises. Viennent ensuite un tableau ou un objet par bloc de la page de résultats, comme organic_results ou people_also_ask.

Un bloc n'est présent que si la page l'affiche : lisez-le donc avec une valeur par défaut. La page format de réponse décrit chaque bloc et chaque champ.

{
  "search_metadata": { "id": "srch_7f3a9c2e41b8", "status": "success", "engine": "google", "credits_used": 1 },
  "search_parameters": { "engine": "google", "q": "best espresso grinder", "gl": "us", "hl": "en", "page": 1 },
  "search_information": { "total_results": 18600000, "query_displayed": "best espresso grinder" },
  "organic_results": [ { "position": 1, "title": "…", "link": "https://www.example.com/…", "snippet": "…" } ],
  "people_also_ask": [ { "question": "…", "snippet": "…", "link": "https://www.example.org/…" } ],
  "related_searches": [ { "query": "best espresso grinder under 300" } ],
  "pagination": { "current": 1, "next_page": 2 }
}

Combien coûte une requête, et quand est-elle gratuite ?

1 crédit = 1 requête réussie, qui renvoie une page de résultats sur n'importe quel moteur pris en charge. Une requête qui échoue n'est pas facturée. Environ 10 résultats organiques par page, comme Google les sert depuis qu'il n'honore plus num=100 en septembre 2025 ; chaque page supplémentaire coûte un crédit de plus. Une requête rejetée pour un paramètre invalide, une mauvaise clé, un solde vide ou un compte occupé est aussi gratuite, tout comme chaque appel à l'endpoint des crédits.

Les prix vont de 7,50 $US pour 10 000 recherches à 0,30 $US/1K requêtes sur le plus gros pack, en octobre 2026. Les crédits de recherche prépayés n'expirent jamais : les requêtes inutilisées restent sur votre compte jusqu'à ce que vous les utilisiez. La page des erreurs liste chaque code d'erreur et la bonne façon de réessayer.