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.
Result block types
Possible values of the type field. A block is only present in the response when Google displays it for the requested keyword.
Results and ads
organic
Organic result
Standard organic search result.
sitelinks
Sitelinks
Secondary link attached to an organic result.
paid_top
Top ad
Paid ad above the organic results.
paid_bottom
Bottom ad
Paid ad below the organic results.
Rich blocks
featured_snippet
Featured snippet
Highlighted snippet above the organic results.
knowledge_graph
Knowledge panel
Item from the panel shown on the right of the SERP.
images
Images
Thumbnail from the images block.
videos
Videos
Video from the videos block.
top_stories
Top stories
Article from the top stories block.
shopping
Shopping
Product from the Google Shopping carousel.
recipes
Recipes
Recipe from the recipes block.
local_pack
Local pack
Business from the local pack, sourced from Google Maps.
visual_digest
Visual digest
Item from the visual digest generated by Google.
Suggestions and follow-ups
people_also_ask
People also ask
Question from the People also ask block.
related_searches
Related searches
Related search suggested at the bottom of the page.
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.
Elección del formato de salida :
JSON (valor: json)
HTML (valor: html)
Formato de los resultados
Google Search
Google Maps
type
string
Tipo de bloque de resultados (orgánico, vídeos, imágenes, «people_also_ask», «local_pack», etc.)
rank_type
integer
Posición del elemento dentro de su propio tipo de bloque (p. ej.: tercer resultado orgánico = 3)
rank_serp
integer
Posición absoluta en la SERP completa, incluyendo todos los bloques, según la posición vertical real en la página (al píxel)
page
integer
Número de página de la SERP en la que aparece el elemento
pixel
integer
Posición vertical del elemento en la página, en píxeles desde la parte superior
domain
string
Dominio de la URL
url
string
URL del resultado
title
string
Título que se muestra del resultado
description
string
Descripción / extracto mostrado del resultado
brand
string
Cited brand, or the source label as displayed by Google. Only on ai_overview_citation, ai_overview_citation_source and ai_overview_panel blocks. On a citation the URL is often empty, making the brand the only information carried by the item.
visible
boolean
Whether the item is shown straight away in the AI Overview (true) or only after expanding it (false). Only on AI Overview blocks. Always false for ai_overview_citation_source, which appears on hover over a citation.
rank_type
integer
Posición del elemento dentro de su propio tipo de bloque (p. ej.: tercer resultado orgánico = 3)
rank_serp
integer
Posición absoluta en la SERP completa, incluyendo todos los bloques, según la posición vertical real en la página (al píxel)
page
integer
Número de página de la SERP en la que aparece el elemento
pixel
integer
Posición vertical del elemento en la página, en píxeles desde la parte superior
title
string
Título que se muestra del resultado
cid
string
Identificador de Google (CID) de la ficha del centro
reviews
integer
Número de opiniones
rating
float
Puntuación media sobre 5
website
string
Página web del centro
type
string
Tipo de establecimiento (p. ej., restaurante)
address
string
Dirección postal
status_label
string
Estado de apertura (p. ej.: Abierto, Cerrado)
status_detail
string
Detalles del estado (p. ej., horarios)
comment
string
Comentario / extracto mostrado
images
array
Lista de imágenes de la ficha
Solicitar
Respuesta satisfactoria
Respuesta de error
Status: 200 OK
{
"status": "success",
"request_ms": 41,
"count": 1,
"data": [
{
"id": "SERP_ID",
"status": "done",
"keyword": "example keyword",
"device": "desktop",
"location": "fr",
"language": "fr",
"depth": 1,
"geolocation": false,
"priority": 1,
"callback_url": "",
"cost": "0.00002",
"created_at": "2025-09-10T12:32:56Z",
"scraped_at": "2025-09-10T12:33:02Z",
"duration_ms": 5403,
"serp_info": {
"result_count": 1500000000
},
"results": [
{
"type": "people_also_ask",
"items": [
{
"rank_type": 1,
"rank_serp": 4,
"page": 1,
"pixel": 806,
"domain": "guides.lib.uh.edu",
"url": "https://guides.lib.uh.edu/c.php?g\\x3d1249281",
"title": "What is a keyword example?",
"description": ""
},
{
"rank_type": 2,
"rank_serp": 5,
"page": 1,
"pixel": 858,
"domain": "toolsqa.com",
"url": "https://toolsqa.com/cucumber/data-driven-testing-using-examples-keyword/",
"title": "What is the example keyword used for?",
"description": ""
},
{
"rank_type": 3,
"rank_serp": 6,
"page": 1,
"pixel": 911,
"domain": "www.editage.com",
"url": "https://www.editage.com/insights/how-to-create-keywords-for-a-research-paper",
"title": "How do you write keywords examples?",
"description": ""
},
{
"rank_type": 4,
"rank_serp": 7,
"page": 1,
"pixel": 964,
"domain": "libguides.lvc.edu",
"url": "https://libguides.lvc.edu/c.php?g\\x3d1152118\\x26ampp\\x3d8409030",
"title": "What is an example of a keyword search?",
"description": ""
}
]
},
{
"type": "videos",
"items": [
{
"rank_type": 1,
"rank_serp": 1,
"page": 1,
"pixel": 223,
"domain": "www.youtube.com",
"url": "https://www.youtube.com/watch?v=H-B5oFJjL8I",
"title": "What are Keywords and How to Choose Them? 1.1. SEO ...",
"description": ""
},
{
"rank_type": 2,
"rank_serp": 2,
"page": 1,
"pixel": 374,
"domain": "www.youtube.com",
"url": "https://www.youtube.com/watch?v=TTlEVVB75wo&pp=2AEAkAIB",
"title": "What Are Keywords? Everything You Need To Know (and more)",
"description": ""
},
{
"rank_type": 3,
"rank_serp": 3,
"page": 1,
"pixel": 526,
"domain": "www.youtube.com",
"url": "https://www.youtube.com/watch?v=OMJQPqG2Uas",
"title": "Keyword Research Tutorial: From Start to Finish",
"description": ""
}
]
},
{
"type": "organic",
"items": [
{
"rank_type": 1,
"rank_serp": 8,
"page": 1,
"pixel": 1077,
"domain": "www.seoquantum.com",
"url": "https://www.seoquantum.com/en/blog/6-types-keywords-organic-seo",
"title": "The 6 Types of Keywords in Organic SEO",
"description": "2 mars 2024 — I will introduce you to 6 types of keywords that you absolutely need to know. We will start with the most common ones such as long-tail keywords and then move ..."
},
{
"rank_type": 2,
"rank_serp": 9,
"page": 1,
"pixel": 1223,
"domain": "storychief.io",
"url": "https://storychief.io/blog/seo-keyword-research-examples",
"title": "10 Clever SEO Keyword Research Examples",
"description": "Let's say you run a food blog. Some potential SEO keywords could be: quick weeknight dinners easy dinner recipes 30 minute meals one pot dinners"
},
{
"rank_type": 3,
"rank_serp": 10,
"page": 1,
"pixel": 1369,
"domain": "www.indeed.com",
"url": "https://www.indeed.com/career-advice/career-development/types-of-keywords",
"title": "19 Types of Keywords",
"description": "6 juin 2025 — 19 types of keywords and how to use them for marketing · 1. Market segment keywords · 2. Customer-defining keywords · 3. Product-defining ..."
},
{
"rank_type": 4,
"rank_serp": 11,
"page": 1,
"pixel": 1515,
"domain": "www.usg.edu",
"url": "https://www.usg.edu/galileo/skills/unit04/primer04_07.phtml",
"title": "Keyword Search",
"description": "In this case, the phrase alternative fuels and automobiles are the significant keywords."
},
{
"rank_type": 5,
"rank_serp": 12,
"page": 1,
"pixel": 1639,
"domain": "guides.lib.uh.edu",
"url": "https://guides.lib.uh.edu/c.php?g=1249281",
"title": "What are keywords and why are they important? - Guides",
"description": "You probably used the title of the film and the word “showtimes” as your keywords to bring up the results you needed. Keywords in academic research are similar."
},
{
"rank_type": 6,
"rank_serp": 13,
"page": 1,
"pixel": 1785,
"domain": "www.tactee.fr",
"url": "https://www.tactee.fr/seo/strategie-seo/keyword-seo/",
"title": "Qu'est ce qu'un keyword SEO ? [Définition & conseil]",
"description": "13 juil. 2024 — Commerciale : l'utilisateur compare des produits ou des services, par exemple « meilleur smartphone 2024 ». Identifier l'intention de recherche ..."
},
{
"rank_type": 7,
"rank_serp": 14,
"page": 1,
"pixel": 1931,
"domain": "backlinko.com",
"url": "https://backlinko.com/types-of-keywords",
"title": "10 Types of Keywords with Examples (+ How to Find Them)",
"description": "15 mai 2025 — 10 Types of Keywords with Examples (+ How to Find Them) · 1. Seed Keywords · 2. Informational Keywords · 3. Commercial Keywords · 4."
},
{
"rank_type": 8,
"rank_serp": 15,
"page": 1,
"pixel": 2077,
"domain": "learn.microsoft.com",
"url": "https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/",
"title": "C# Keywords and contextual keywords - C# reference",
"description": "17 avr. 2025 — For example, @if is a valid identifier, but if isn't because if is a keyword. The first table in this article lists keywords that are ..."
}
]
},
{
"type": "images",
"items": [
{
"rank_type": 1,
"rank_serp": 16,
"page": 1,
"pixel": 2311,
"domain": "searchfacts.com",
"url": "https://searchfacts.com/what-are-keywords-in-seo/",
"title": "",
"description": ""
},
{
"rank_type": 2,
"rank_serp": 17,
"page": 1,
"pixel": 2311,
"domain": "backlinko.com",
"url": "https://backlinko.com/hub/seo/seo-keywords",
"title": "",
"description": ""
},
{
"rank_type": 3,
"rank_serp": 18,
"page": 1,
"pixel": 2311,
"domain": "ahrefs.com",
"url": "https://ahrefs.com/blog/what-are-keywords/",
"title": "",
"description": ""
}
]
}
]
}
]
}
{
"status": "success",
"request_ms": 41,
"count": 1,
"data": [
{
"id": "SERP_ID",
"status": "done",
"keyword": "example keyword",
"device": "desktop",
"location": "fr",
"language": "fr",
"depth": 1,
"geolocation": false,
"priority": 1,
"callback_url": "",
"cost": "0.00002",
"created_at": "2025-09-10T12:32:56Z",
"scraped_at": "2025-09-10T12:33:02Z",
"duration_ms": 5403,
"serp_info": {
"result_count": 1500000000
},
"results": [
{
"type": "people_also_ask",
"items": [
{
"rank_type": 1,
"rank_serp": 4,
"page": 1,
"pixel": 806,
"domain": "guides.lib.uh.edu",
"url": "https://guides.lib.uh.edu/c.php?g\\x3d1249281",
"title": "What is a keyword example?",
"description": ""
},
{
"rank_type": 2,
"rank_serp": 5,
"page": 1,
"pixel": 858,
"domain": "toolsqa.com",
"url": "https://toolsqa.com/cucumber/data-driven-testing-using-examples-keyword/",
"title": "What is the example keyword used for?",
"description": ""
},
{
"rank_type": 3,
"rank_serp": 6,
"page": 1,
"pixel": 911,
"domain": "www.editage.com",
"url": "https://www.editage.com/insights/how-to-create-keywords-for-a-research-paper",
"title": "How do you write keywords examples?",
"description": ""
},
{
"rank_type": 4,
"rank_serp": 7,
"page": 1,
"pixel": 964,
"domain": "libguides.lvc.edu",
"url": "https://libguides.lvc.edu/c.php?g\\x3d1152118\\x26ampp\\x3d8409030",
"title": "What is an example of a keyword search?",
"description": ""
}
]
},
{
"type": "videos",
"items": [
{
"rank_type": 1,
"rank_serp": 1,
"page": 1,
"pixel": 223,
"domain": "www.youtube.com",
"url": "https://www.youtube.com/watch?v=H-B5oFJjL8I",
"title": "What are Keywords and How to Choose Them? 1.1. SEO ...",
"description": ""
},
{
"rank_type": 2,
"rank_serp": 2,
"page": 1,
"pixel": 374,
"domain": "www.youtube.com",
"url": "https://www.youtube.com/watch?v=TTlEVVB75wo&pp=2AEAkAIB",
"title": "What Are Keywords? Everything You Need To Know (and more)",
"description": ""
},
{
"rank_type": 3,
"rank_serp": 3,
"page": 1,
"pixel": 526,
"domain": "www.youtube.com",
"url": "https://www.youtube.com/watch?v=OMJQPqG2Uas",
"title": "Keyword Research Tutorial: From Start to Finish",
"description": ""
}
]
},
{
"type": "organic",
"items": [
{
"rank_type": 1,
"rank_serp": 8,
"page": 1,
"pixel": 1077,
"domain": "www.seoquantum.com",
"url": "https://www.seoquantum.com/en/blog/6-types-keywords-organic-seo",
"title": "The 6 Types of Keywords in Organic SEO",
"description": "2 mars 2024 — I will introduce you to 6 types of keywords that you absolutely need to know. We will start with the most common ones such as long-tail keywords and then move ..."
},
{
"rank_type": 2,
"rank_serp": 9,
"page": 1,
"pixel": 1223,
"domain": "storychief.io",
"url": "https://storychief.io/blog/seo-keyword-research-examples",
"title": "10 Clever SEO Keyword Research Examples",
"description": "Let's say you run a food blog. Some potential SEO keywords could be: quick weeknight dinners easy dinner recipes 30 minute meals one pot dinners"
},
{
"rank_type": 3,
"rank_serp": 10,
"page": 1,
"pixel": 1369,
"domain": "www.indeed.com",
"url": "https://www.indeed.com/career-advice/career-development/types-of-keywords",
"title": "19 Types of Keywords",
"description": "6 juin 2025 — 19 types of keywords and how to use them for marketing · 1. Market segment keywords · 2. Customer-defining keywords · 3. Product-defining ..."
},
{
"rank_type": 4,
"rank_serp": 11,
"page": 1,
"pixel": 1515,
"domain": "www.usg.edu",
"url": "https://www.usg.edu/galileo/skills/unit04/primer04_07.phtml",
"title": "Keyword Search",
"description": "In this case, the phrase alternative fuels and automobiles are the significant keywords."
},
{
"rank_type": 5,
"rank_serp": 12,
"page": 1,
"pixel": 1639,
"domain": "guides.lib.uh.edu",
"url": "https://guides.lib.uh.edu/c.php?g=1249281",
"title": "What are keywords and why are they important? - Guides",
"description": "You probably used the title of the film and the word “showtimes” as your keywords to bring up the results you needed. Keywords in academic research are similar."
},
{
"rank_type": 6,
"rank_serp": 13,
"page": 1,
"pixel": 1785,
"domain": "www.tactee.fr",
"url": "https://www.tactee.fr/seo/strategie-seo/keyword-seo/",
"title": "Qu'est ce qu'un keyword SEO ? [Définition & conseil]",
"description": "13 juil. 2024 — Commerciale : l'utilisateur compare des produits ou des services, par exemple « meilleur smartphone 2024 ». Identifier l'intention de recherche ..."
},
{
"rank_type": 7,
"rank_serp": 14,
"page": 1,
"pixel": 1931,
"domain": "backlinko.com",
"url": "https://backlinko.com/types-of-keywords",
"title": "10 Types of Keywords with Examples (+ How to Find Them)",
"description": "15 mai 2025 — 10 Types of Keywords with Examples (+ How to Find Them) · 1. Seed Keywords · 2. Informational Keywords · 3. Commercial Keywords · 4."
},
{
"rank_type": 8,
"rank_serp": 15,
"page": 1,
"pixel": 2077,
"domain": "learn.microsoft.com",
"url": "https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/",
"title": "C# Keywords and contextual keywords - C# reference",
"description": "17 avr. 2025 — For example, @if is a valid identifier, but if isn't because if is a keyword. The first table in this article lists keywords that are ..."
}
]
},
{
"type": "images",
"items": [
{
"rank_type": 1,
"rank_serp": 16,
"page": 1,
"pixel": 2311,
"domain": "searchfacts.com",
"url": "https://searchfacts.com/what-are-keywords-in-seo/",
"title": "",
"description": ""
},
{
"rank_type": 2,
"rank_serp": 17,
"page": 1,
"pixel": 2311,
"domain": "backlinko.com",
"url": "https://backlinko.com/hub/seo/seo-keywords",
"title": "",
"description": ""
},
{
"rank_type": 3,
"rank_serp": 18,
"page": 1,
"pixel": 2311,
"domain": "ahrefs.com",
"url": "https://ahrefs.com/blog/what-are-keywords/",
"title": "",
"description": ""
}
]
}
]
}
]
}
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)
