Os dados devem ser enviados numa matriz JSON. Cada elemento deve conter os seguintes campos.
Limite
A matriz JSON pode conter 100 elementos, pelo que pode criar 100 SERPs scrapes numa única chamada.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorizações : Bearer {api_key}
Parâmetros
search_engine
Necessário
string
Escolha do motor de busca :
Pesquisa Google (valor: google_search)
keyword
Necessário
string
Palavras-chave a pesquisar no motor de busca
device
Necessário
string
Escolha do substrato :
Computador (valor: desktop)
Móvel (valor: móvel)
depth
Necessário
integer
Profundidade da página, recuperamos os SERPs do Google com paginação. Este parâmetro deve estar entre 1 (aproximadamente 10 resultados) e 10 (aproximadamente 100 resultados).
location
Necessário
string
Código de localização do motor de busca
language
Necessário
string
Língua do motor de busca
geolocation
string
Permite-lhe geolocalizar um SERP do Google. Por exemplo, pode indicar a cidade, o departamento ou o país, separados por uma vírgula.
priority
integer
Utilizado para dar prioridade aos seus pedidos, que são processados por ordem decrescente de prioridade. Valor entre 1 (baixo) e 10 (alto).
callback_url
string
Permite-lhe especificar um URL para o qual lhe enviaremos os resultados da palavra-chave depois de esta ter sido processada.
Os dados devem ser enviados numa matriz JSON. Cada elemento deve conter os seguintes campos.
Limite
A matriz JSON pode conter 100 elementos, pelo que pode criar 100 SERPs scrapes numa única chamada.
post
https://api.semscraper.com/v1/serp
https://api.semscraper.com/v1/serp
Autorizações : Bearer {api_key}
Parâmetros
search_engine
Necessário
string
Escolha do motor de busca :
Google Maps (valor: google_maps)
keyword
Necessário
string
Palavras-chave a pesquisar no motor de busca
depth
Necessário
integer
Profundidade da página, recuperamos os SERPs do Google com paginação. Este parâmetro deve estar entre 1 (aproximadamente 10 resultados) e 10 (aproximadamente 100 resultados).
location
Necessário
string
Código de localização do motor de busca
language
Necessário
string
Língua do motor de busca
geolocation
string
Permite-lhe geolocalizar um SERP do Google. Por exemplo, pode indicar a cidade, o departamento ou o país, separados por uma vírgula.
priority
integer
Utilizado para dar prioridade aos seus pedidos, que são processados por ordem decrescente de prioridade. Valor entre 1 (baixo) e 10 (alto).
callback_url
string
Permite-lhe especificar um URL para o qual lhe enviaremos os resultados da palavra-chave depois de esta ter sido processada.
Lista de identificadores (IDs) para SERPs concluídos que ainda não foram recuperados.
Este método permite-lhe obter os IDs de todos os SERPs que já foram processados mas ainda não recuperados. Pode então chamar o método de recuperação SERP utilizando estes IDs.
Recuperação de SERPs através de um URL de retorno de chamada
Pode receber o resultado de um SERP diretamente num URL que nos fornece quando cria uma consulta, bastando para isso recuperar a chave HMAC associada à chave 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 o número de SERPs de acordo com o seu estado:
Concluído e resultados recuperados pelo utilizador (status=done, fetched=true)
Concluído e resultados não recuperados pelo utilizador (status=done, fetched=false)
Em processamento (status=processamento)
Em espera (estado=pendente)
