Les données doivent être envoyées dans un tableau JSON. Chaque élément doit contenir les champs suivants.
Limite
Le tableau JSON peut contenir 100 éléments, vous pouvez donc créer 100 scrapes de SERPs en un seul appel.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorisations : Bearer {api_key}
Paramètres
search_engine
Requis
string
Choix du moteur de recherche :
Google Recherche (valeur : google_search)
keyword
Requis
string
Mots-clés à rechercher sur le moteur de recherche
device
Requis
string
Choix du support :
Ordinateur (valeur : desktop)
Mobile (valeur : mobile)
depth
Requis
integer
Profondeur de pages, nous récupérons les SERPs Google avec pagination. Ce paramètre doit être compris entre 1 (environ 10 résultats) et 10 (environ 100 résultats).
location
Requis
string
Code de localisation du moteur de recherche
language
Requis
string
Langue du moteur de recherche
geolocation
string
Permet de géolocaliser une SERP Google. Vous pouvez par exemple indiquer la ville, département, pays, séparer par une virgule.
priority
integer
Permet de prioriser vos demandes, elles sont traitées par priorité décroissante. Valeur entre 1 (low) et 10 (high).
callback_url
string
Permet d'indiquer une URL sur laquelle nous allons vous envoyer les résultats du mot-clé une fois celui-ci traité.
Les données doivent être envoyées dans un tableau JSON. Chaque élément doit contenir les champs suivants.
Limite
Le tableau JSON peut contenir 100 éléments, vous pouvez donc créer 100 scrapes de SERPs en un seul appel.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorisations : Bearer {api_key}
Paramètres
search_engine
Requis
string
Choix du moteur de recherche :
Google Maps (valeur : google_maps)
keyword
Requis
string
Mots-clés à rechercher sur le moteur de recherche
depth
Requis
integer
Profondeur de pages, nous récupérons les SERPs Google avec pagination. Ce paramètre doit être compris entre 1 (environ 10 résultats) et 10 (environ 100 résultats).
location
Requis
string
Code de localisation du moteur de recherche
language
Requis
string
Langue du moteur de recherche
geolocation
string
Permet de géolocaliser une SERP Google. Vous pouvez par exemple indiquer la ville, département, pays, séparer par une virgule.
priority
integer
Permet de prioriser vos demandes, elles sont traitées par priorité décroissante. Valeur entre 1 (low) et 10 (high).
callback_url
string
Permet d'indiquer une URL sur laquelle nous allons vous envoyer les résultats du mot-clé une fois celui-ci traité.
Liste des identifiants (ID) des SERP terminées que vous n'avez pas encore récupérés.
Cette méthode vous permet d’obtenir les IDs de toutes les SERP déjà traitées mais encore jamais récupérées. Vous pourrez ensuite appeler la méthode de récupération des SERP en utilisant ces IDs.
Vous pouvez recevoir le résultat d'un SERP directement sur une URL que vous nous fournissez lors de la création d'une requête, il vous suffit de récupérer la clé de HMAC liée à la clé API utilisée.
Code
PHP
Python
Javascript
Ruby
Java
C#
GO
// 1) Read the raw body (JSON)
$raw = file_get_contents('php://input');
// Middleware to parse JSON and keep raw body for HMAC verification
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf.toString(); // Save raw body for signature check
}
}));
app.post("/callback", (req, res) => {
// 1) Read the raw body (JSON)
const raw = req.rawBody;
// Use timing-safe comparison to avoid timing attacks
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
return res.status(401).type("text").send("Invalid signature");
}
// 4) Decode the JSON (Express already did it in req.body)
let data;
try {
data = req.body;
} catch (err) {
return res.status(400).type("text").send("Invalid JSON");
}
// 5) Process the data
// data contains what the client sent in the payload
// For example: data.id, data.results, etc.
// 6) Respond in JSON (optional, we log these responses for tracking purposes)
res.status(200).json({
status: "ok",
received_at: new Date().toISOString(),
echo: data.id || null
});
});
// 4) Decode the JSON
Map data;
try {
data = new com.fasterxml.jackson.databind.ObjectMapper().readValue(raw, Map.class);
} catch (Exception e) {
return ResponseEntity.status(HttpStatus.BAD_REQUEST)
.contentType(MediaType.TEXT_PLAIN)
.body("Invalid JSON");
}
// 5) Process the data
// data contains what the client sent in the payload
// For example: data.get("id"), data.get("results"), etc.
// 6) Respond in JSON (optional, we log these responses for tracking purposes)
Map response = new HashMap<>();
response.put("status", "ok");
response.put("received_at", Instant.now().toString());
response.put("echo", data.get("id"));
// Helper method: secure string comparison (to avoid timing attacks)
private boolean secureCompare(String a, String b) {
if (a == null || b == null || a.length() != b.length()) {
return false;
}
int result = 0;
for (int i = 0; i < a.length(); i++) {
result |= a.charAt(i) ^ b.charAt(i);
}
return result == 0;
}
// Helper method: convert bytes to hex string
private String bytesToHex(byte[] bytes) {
StringBuilder hexString = new StringBuilder(2 bytes.length);
for (byte b : bytes) {
String hex = Integer.toHexString(0xff & b);
if (hex.length() == 1) hexString.append('0');
hexString.append(hex);
}
return hexString.toString();
}
}
PHP
Python
Javascript
Ruby
Java
C#
GO
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
const string SHARED_SECRET = "HMAC_KEY";
app.MapPost("/callback", async (HttpRequest request, HttpResponse response) =>
{
// 1) Read the raw body (JSON)
using var reader = new StreamReader(request.Body);
var raw = await reader.ReadToEndAsync();
// 2) Retrieve the headers
var signature = request.Headers["X-Signature"].FirstOrDefault() ?? "";
// 3) (Optional) Verify the HMAC signature
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(SHARED_SECRET));
var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(raw));
var expected = Convert.ToHexString(hash).ToLowerInvariant();
// 5) Process the data
// data contains what the client sent in the payload
// For example: data["id"], data["results"], etc.
// 6) Respond in JSON (optional, we log these responses for tracking purposes)
var jsonResponse = new
{
status = "ok",
received_at = DateTime.UtcNow.ToString("o"), // ISO 8601
echo = data != null && data.ContainsKey("id") ? data["id"] : null
};
Permet de voir le nombre de SERPs en fonction de leurs statuts :
Terminées et résultats récupérés par l'utilisateur (status=done, fetched=true)
Terminées et résultats non récupérés par l'utilisateur (status=done, fetched=false)
En cours de traitement (status=processing)
En attente (status=pending)
