I dati devono essere inviati in un array JSON. Ogni elemento deve contenere i seguenti campi.
Limite
L'array JSON può contenere 100 elementi, quindi è possibile creare 100 scrapes di SERP con una sola chiamata.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorizzazioni : Bearer {api_key}
Parametri
search_engine
Richiesto
string
Scelta del motore di ricerca :
Ricerca Google (valore: google_search)
keyword
Richiesto
string
Parole chiave da cercare sul motore di ricerca
device
Richiesto
string
Scelta del substrato :
Computer (valore: desktop)
Mobile (valore: mobile)
depth
Richiesto
integer
Profondità della pagina, recuperiamo le SERP di Google con paginazione. Questo parametro deve essere compreso tra 1 (circa 10 risultati) e 10 (circa 100 risultati).
location
Richiesto
string
Codice di localizzazione del motore di ricerca
language
Richiesto
string
Lingua dei motori di ricerca
geolocation
string
Consente di geolocalizzare una SERP di Google. Ad esempio, è possibile indicare la città, il dipartimento o il Paese, separati da una virgola.
priority
integer
Utilizzato per dare priorità alle richieste, che vengono elaborate in ordine decrescente di priorità. Valore compreso tra 1 (basso) e 10 (alto).
callback_url
string
Consente di specificare un URL a cui inviare i risultati per la parola chiave una volta elaborati.
I dati devono essere inviati in un array JSON. Ogni elemento deve contenere i seguenti campi.
Limite
L'array JSON può contenere 100 elementi, quindi è possibile creare 100 scrapes di SERP con una sola chiamata.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorizzazioni : Bearer {api_key}
Parametri
search_engine
Richiesto
string
Scelta del motore di ricerca :
Google Maps (valore: google_maps)
keyword
Richiesto
string
Parole chiave da cercare sul motore di ricerca
depth
Richiesto
integer
Profondità della pagina, recuperiamo le SERP di Google con paginazione. Questo parametro deve essere compreso tra 1 (circa 10 risultati) e 10 (circa 100 risultati).
location
Richiesto
string
Codice di localizzazione del motore di ricerca
language
Richiesto
string
Lingua dei motori di ricerca
geolocation
string
Consente di geolocalizzare una SERP di Google. Ad esempio, è possibile indicare la città, il dipartimento o il Paese, separati da una virgola.
priority
integer
Utilizzato per dare priorità alle richieste, che vengono elaborate in ordine decrescente di priorità. Valore compreso tra 1 (basso) e 10 (alto).
callback_url
string
Consente di specificare un URL a cui inviare i risultati per la parola chiave una volta elaborati.
Elenco di identificatori (ID) per le SERP completate che non sono ancora state recuperate.
Questo metodo consente di ottenere gli ID di tutte le SERP già elaborate ma non ancora recuperate. È quindi possibile richiamare il metodo di recupero delle SERP utilizzando questi ID.
È possibile ricevere il risultato di una SERP direttamente su un URL fornito al momento della creazione di una query. È sufficiente recuperare la chiave HMAC collegata alla chiave API utilizzata.
Codice
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
};
Visualizzare il numero di SERP in base al loro stato:
Completato e risultati recuperati dall'utente (status=done, fetched=true)
Completato e risultati non recuperati dall'utente (status=done, fetched=false)
In corso (stato=elaborazione)
In attesa (status=pending)
