Creación de consultas en las SERPs de búsqueda de Google
Los datos deben enviarse en una matriz JSON. Cada elemento debe contener los siguientes campos.
Límite
La matriz JSON puede contener 100 elementos, por lo que puede crear 100 SERPs scrapes en una sola llamada.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorizaciones : Bearer {api_key}
Parámetros
search_engine
Requerido
string
Elección del motor de búsqueda :
Búsqueda en Google (valor: google_search)
keyword
Requerido
string
Palabras clave para buscar en el motor de búsqueda
device
Requerido
string
Elección del sustrato :
Ordenador (valor: de sobremesa)
Móvil (valor: móvil)
depth
Requerido
integer
Profundidad de página, recuperamos las SERPs de Google con paginación. Este parámetro debe estar entre 1 (aproximadamente 10 resultados) y 10 (aproximadamente 100 resultados).
location
Requerido
string
Código de localización del motor de búsqueda
language
Requerido
string
Lenguaje del motor de búsqueda
geolocation
string
Permite geolocalizar una SERP de Google. Por ejemplo, puede indicar la ciudad, el departamento o el país, separados por una coma.
priority
integer
Se utiliza para dar prioridad a sus solicitudes, que se procesan en orden descendente de prioridad. Valor entre 1 (bajo) y 10 (alto).
callback_url
string
Le permite especificar una URL a la que le enviaremos los resultados de la palabra clave una vez procesados.
Los datos deben enviarse en una matriz JSON. Cada elemento debe contener los siguientes campos.
Límite
La matriz JSON puede contener 100 elementos, por lo que puede crear 100 SERPs scrapes en una sola llamada.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorizaciones : Bearer {api_key}
Parámetros
search_engine
Requerido
string
Elección del motor de búsqueda :
Google Maps (valor: google_maps)
keyword
Requerido
string
Palabras clave para buscar en el motor de búsqueda
depth
Requerido
integer
Profundidad de página, recuperamos las SERPs de Google con paginación. Este parámetro debe estar entre 1 (aproximadamente 10 resultados) y 10 (aproximadamente 100 resultados).
location
Requerido
string
Código de localización del motor de búsqueda
language
Requerido
string
Lenguaje del motor de búsqueda
geolocation
string
Permite geolocalizar una SERP de Google. Por ejemplo, puede indicar la ciudad, el departamento o el país, separados por una coma.
priority
integer
Se utiliza para dar prioridad a sus solicitudes, que se procesan en orden descendente de prioridad. Valor entre 1 (bajo) y 10 (alto).
callback_url
string
Le permite especificar una URL a la que le enviaremos los resultados de la palabra clave una vez procesados.
Lista de identificadores (ID) de SERPs completados que aún no ha recuperado.
Este método le permite obtener los IDs de todos los SERPs que ya han sido procesados pero que aún no han sido recuperados. A continuación, puede llamar al método de recuperación de SERP utilizando estos ID.
Recuperación de las SERP mediante una URL de devolución de llamada
Puede recibir el resultado de una SERP directamente en una URL que nos proporcione al crear una consulta. Todo lo que tiene que hacer es recuperar la clave HMAC vinculada a la clave API utilizada.
Código
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
};
Ver el número de SERPs según su estado:
Completado y resultados recuperados por el usuario (status=done, fetched=true)
Completado y resultados no recuperados por el usuario (status=done, fetched=false)
En proceso (estado=procesando)
En espera (status=pending)
