Iniciar sesión Pruébelo gratis
Deutsch English Español Français Italiano Português 日本語
Pruébelo gratis Iniciar sesión
  • Primeros pasos
  • Inicio rápido
  • Información
  • Límites de llamadas
  • Versiones de Google
  • Lista de versiones
  • SERPS
  • Consultas de búsqueda en Google
  • Consultas de Google Maps
  • ID de consulta
  • Recuperar las SERP
  • URL de devolución de llamada
  • Estado de tramitación de los SERP
  • Historial de consultas
  • Facturación
  • Crédito restante
  • Formas de pago

Documentación sobre la API de Semscraper

Inicio rápido

Tres pasos para obtener tu primera SERP de Google en JSON.

  1. Crea tu cuenta: 1.000 SERPs gratis, sin tarjeta de crédito. Después copia tu clave en el menú Claves API de tu cuenta. Se envía en la cabecera Authorization: Bearer de cada llamada. Crear una cuenta gratis
  2. Envía tus palabras clave con POST /v1/serp, hasta 1.000 por llamada. La respuesta devuelve el identificador y el coste de cada SERP: es el único momento en que se factura.
    Enviar una palabra clave
    curl -X POST https://api.semscraper.com/v1/serp \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '[{"search_engine": "google_search", "keyword": "receta de crepes", "device": "desktop", "location": "es", "language": "es", "depth": 1}]'
  3. Recupera el resultado con GET /v1/serp y el identificador recibido: sustituye SERP_ID por el valor del campo data[0].id devuelto en el paso anterior.La recopilación es asíncrona: mientras el estado sea pending o processing, vuelve a intentarlo un poco más tarde. La recuperación nunca se factura.
    Recuperar la SERP
    curl "https://api.semscraper.com/v1/serp?ids=SERP_ID&output=json" \
  -H "Authorization: Bearer TU_CLAVE_API"

Para recibir un aviso sin consultar la API, añade un callback_url a tus peticiones. Para cientos de miles de palabras clave, consulta la API Bulk SERP.

Información

Límites de llamadas

Limitación del número de llamadas a la API
GET : 500 llamadas por minuto
POST : 500 llamadas por minuto

Versiones de Google

Lista de versiones

Obtener los parámetros ubicación e idioma necesarios para recuperar las SERPs de Google.
get
https://api.semscraper.com/v1/serp/google/location
Autorizaciones : Bearer {api_key}
  • Solicitar
  • Respuesta satisfactoria
Status: 200 OK
{
    "status": "success",
    "request_ms": 17,
    "count": 372,
    "data": [
        {
            "location": "en",
            "language": "en",
            "host": "google.com",
            "name": "World Wide Web"
        },
        {
            "location": "fr",
            "language": "fr",
            "host": "google.fr",
            "name": "France"
        }
}

SERPs

Consultas de búsqueda en Google

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 1000 elementos, por lo que puede crear 1000 SERPs scrapes en una sola llamada.
post
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
Dispositivo:
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
Geolocaliza una SERP de Google. Indique la ciudad, la región y el país separados por comas (p. ej.: Nice, Alpes-Maritimes, France) o una posición GPS latitud,longitud en grados decimales (p. ej.: 43.7102,7.2620).
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.
Tipos de bloques de resultados
Valores posibles del campo type. Un bloque solo aparece en la respuesta si Google lo muestra para la palabra clave solicitada.
Resultados y anuncios
organic
Resultado orgánico
Resultado orgánico estándar de la búsqueda.
sitelinks
Enlaces de sitio
Enlace secundario asociado a un resultado orgánico.
paid_top
Anuncio superior
Anuncio de pago por encima de los resultados orgánicos.
paid_bottom
Anuncio inferior
Anuncio de pago por debajo de los resultados orgánicos.
Bloques enriquecidos
featured_snippet
Fragmento destacado
Fragmento destacado por encima de los resultados orgánicos.
knowledge_graph
Panel de conocimiento
Elemento del panel que se muestra a la derecha de la SERP.
images
Imágenes
Miniatura del bloque de imágenes.
videos
Vídeos
Vídeo del bloque de vídeos.
top_stories
Noticias destacadas
Artículo del bloque de noticias destacadas.
shopping
Shopping
Producto del carrusel de Google Shopping.
recipes
Recetas
Receta del bloque de recetas.
local_pack
Pack local
Establecimiento del pack local, procedente de Google Maps.
visual_digest
Resumen visual
Elemento del resumen visual generado por Google.
Sugerencias y búsquedas relacionadas
people_also_ask
Otras preguntas de los usuarios
Pregunta del bloque Otras preguntas de los usuarios.
related_searches
Búsquedas relacionadas
Búsqueda relacionada sugerida al final de la página.
find_results_on
Buscar resultados en
Enlace del bloque Buscar resultados en.
location_sites
Sitios de ubicación
Sitio incluido en un bloque relacionado con una ubicación.
AI Overview
ai_overview_citation
Cita
Marca citada en el texto generado por la IA.
ai_overview_citation_source
Fuente de la cita
Fuente de una cita, visible al pasar el cursor sobre ella.
ai_overview_panel
Panel de fuentes
Sitio incluido en el panel lateral de fuentes.
  • Solicitar
  • Respuesta satisfactoria
  • Respuesta de error
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

Consultas de Google Maps

Creación de consultas SERPs de Google Maps
Los datos deben enviarse en una matriz JSON. Cada elemento debe contener los siguientes campos.
Límite
La matriz JSON puede contener 1000 elementos, por lo que puede crear 1000 SERPs scrapes en una sola llamada.
post
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
Geolocaliza una SERP de Google. Indique la ciudad, la región y el país separados por comas (p. ej.: Nice, Alpes-Maritimes, France) o una posición GPS latitud,longitud en grados decimales (p. ej.: 43.7102,7.2620). Con una posición GPS, puede añadir un nivel de zoom opcional (p. ej.: 43.7102,7.2620,16z).
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.
  • Solicitar
  • Respuesta satisfactoria
  • Respuesta de error
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

ID de consulta

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.
get
https://api.semscraper.com/v1/serp
Autorizaciones : Bearer {api_key}
  • Solicitar
  • Respuesta satisfactoria
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 2,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}

Recuperar las SERP

Recuperar las SERPs de Google a través de sus IDs
Recupere varias SERPs en una sola llamada (en formato JSON o HTML) proporcionando varios ID separados por una coma.
Límite
Puede especificar un máximo de 100 ID, lo que le permite recuperar 100 SERPs en una sola llamada.
get
https://api.semscraper.com/v1/serp?ids=id1,id2&output=json
Autorizaciones : Bearer {api_key}
Parámetros
ids
Requerido
string
Lista de ID separada por comas.
output
Requerido
string
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
Marca citada o etiqueta de la fuente tal como la muestra Google. Solo en los bloques ai_overview_citation, ai_overview_citation_source y ai_overview_panel. En una cita, la URL suele estar vacía: la marca es entonces la única información del elemento.
visible
boolean
Indica si el elemento se muestra directamente en el AI Overview (true) o solo después de desplegarlo (false). Solo en los bloques AI Overview. Siempre false para ai_overview_citation_source, que aparece al pasar el cursor sobre una cita.
rating
float
Valoración media que muestra Google (p. ej.: 4.1). Solo en los bloques organic y local_pack; null si el resultado no muestra estrellas.
reviews
integer
Número de reseñas en las que se basa la valoración. Solo en los bloques organic y local_pack; null si el resultado no muestra estrellas.
price_range
string
Rango de precios del establecimiento tal como lo muestra Google (p. ej.: «20–30 €»). Solo en el bloque local_pack; null si no aparece.
details
array
Información que se muestra bajo el establecimiento, en el orden y el idioma de Google: precio, categoría, dirección, horario, servicios… Solo en el bloque local_pack. No se garantiza ni el orden ni la presencia de cada dato.
serp_info.ai_overview
object
AI Overview de la SERP, en el objeto serp_info (no en results). Contiene type, text y complete.
serp_info.ai_overview.type
string
Modo de visualización del AI Overview: sync (presente en la página desde que se carga), async (generado por Google sobre la marcha, una vez cargada la página) o none (sin AI Overview).
serp_info.ai_overview.text
string
Texto generado por la IA, en texto sin formato (sin estilos ni enlaces). null si la SERP no tiene AI Overview o si no se ha podido leer el texto.
serp_info.ai_overview.complete
boolean
True si el AI Overview había terminado de generarse en el momento de la captura. false si el texto falta o puede estar incompleto.
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.0003,
            "created_at": "2025-09-10T12:32:56Z",
            "scraped_at": "2025-09-10T12:33:02Z",
            "duration_ms": 5403,
            "serp_info": {
                "result_count": 1500000000,
                "ai_overview": {
                    "type": "async",
                    "text": "A keyword is a word or phrase that users type into a search engine to find information...",
                    "complete": true
                }
            },
            "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 ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "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",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "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 ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "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.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "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.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "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 ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "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.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "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 ...",
                            "rating": null,
                            "reviews": null
                        }
                    ]
                },
                {
                    "type": "local_pack",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 19,
                            "page": 1,
                            "pixel": 2520,
                            "domain": "lebistrotm.fr",
                            "url": "https://lebistrotm.fr/",
                            "title": "Le Bistrot M",
                            "description": "",
                            "rating": 4.6,
                            "reviews": 220,
                            "price_range": "20–30 €",
                            "details": [
                                "20–30 €",
                                "Restaurant",
                                "1 Pl. Xavier Taillade",
                                "Fermé",
                                "Ouvre à 18:30",
                                "Repas sur place",
                                "Aucun plat à emporter",
                                "Pas de livraison"
                            ]
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 20,
                            "page": 1,
                            "pixel": 2661,
                            "domain": "www.domainedesoliviers.fr",
                            "url": "http://www.domainedesoliviers.fr/",
                            "title": "Domaine des Oliviers",
                            "description": "",
                            "rating": 4.5,
                            "reviews": 1600,
                            "price_range": null,
                            "details": [
                                "Française",
                                "4 All. Paul Emile d'Allard",
                                "Fermé",
                                "Ouvre à 19:00",
                                "Hôtel discret avec piscine et restaurant"
                            ]
                        }
                    ]
                },
                {
                    "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: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

URL de devolución de llamada

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');

// 2) Retrieve the headers
$headers = function_exists('getallheaders') ? getallheaders() : [];
$signature = $headers['X-Signature'] ?? '';

// 3) (Optional) Verify the HMAC signature
$sharedSecret = 'HMAC_KEY';
$expected = hash_hmac('sha256', $raw, $sharedSecret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid signature';
    exit;
}

// 4) Decode the JSON
$data = json_decode($raw, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid JSON';
    exit;
}

// 5) Process the data: a list holding the finished SERP
foreach ($data as $serp) {
    // $serp['id'], $serp['keyword'], $serp['results']...
}

// 6) Respond in JSON (optional, we log these responses for tracking purposes)
http_response_code(200);
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'status' => 'ok',
    'received_at' => gmdate('c'),
    'echo' => array_column($data, 'id')
]);

Estado de tramitación de los SERP

Estado actual del tratamiento de las SERP
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)
get
https://api.semscraper.com/v1/serp/status
Autorizaciones : Bearer {api_key}
  • Solicitar
  • Respuesta satisfactoria
Status: 200 OK
{
    "status": "success",
    "request_ms": 54,
    "count": 4,
    "data": [
        {
            "status": "done",
            "fetched": true,
            "count": 5
        },
        {
            "status": "done",
            "fetched": false,
            "count": 1000
        },
        {
            "status": "processing",
            "count": 0
        },
        {
            "status": "pending",
            "count": 0
        }
    ]
}

Historial de consultas

Muestra sus consultas, de la más reciente a la más antigua, con su configuración (palabra clave, motor de búsqueda, dispositivo, ubicación, idioma, profundidad…) y su estado, sin el resultado de la SERP.
Se devuelven todas las consultas de la cuenta, sea cual sea su estado y tanto si ya se han recuperado como si no. Esta llamada no las marca como recuperadas.

Para paginar, vuelva a llamar al endpoint con el parámetro cursor igual al next_cursor de la respuesta anterior, mientras has_more sea true. El enlace _links.next contiene la URL lista para usar. Para obtener el resultado de una consulta, utilice su enlace _links.json o _links.html.
Límite
10.000 consultas por llamada
get
https://api.semscraper.com/v1/serp/list?date=2026-10-10&limit=1000
Autorizaciones : Bearer {api_key}
Parámetros
date
string
Día de creación de las consultas, en formato YYYY-MM-DD (p. ej.: 2026-10-04). Sin este parámetro, se devuelven todas las fechas.
status
string
Filtro por estado: pending, processing o done. Sin este parámetro, se devuelven todos los estados.
limit
integer
Número de consultas por página, de 1 a 10.000. 1.000 por defecto.
cursor
string
Cursor de paginación: el valor next_cursor de la respuesta anterior. Omítalo para la primera página.
  • Solicitar
  • Respuesta satisfactoria
  • Respuesta de error
Status: 200 OK
{
    "status": "success",
    "request_ms": 38,
    "count": 2,
    "has_more": true,
    "next_cursor": "MTI4NDU2Nzg5",
    "data": [
        {
            "id": "SERP_ID",
            "search_engine": "google_search",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": null,
            "priority": 1,
            "callback_url": null,
            "status": "done",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:45",
            "updated_at": "2026-10-04 09:12:58",
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "search_engine": "google_maps",
            "keyword": "example keyword",
            "device": null,
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": "Nice, Alpes-Maritimes, France",
            "priority": 1,
            "callback_url": "https://example.com/callback",
            "status": "pending",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:44",
            "updated_at": null,
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ],
    "_links": {
        "next": {
            "href": "/v1/serp/list?date=2026-10-04&limit=1000&cursor=MTI4NDU2Nzg5",
            "method": "GET",
            "type": "application/json"
        }
    }
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "Invalid format for parameter: date",
    "code": 400
}

Facturación

Crédito restante

Recupera el crédito restante
get
https://api.semscraper.com/v1/billing/credit
Autorizaciones : Bearer {api_key}
  • Solicitar
  • Respuesta satisfactoria
Status: 200 OK
{
    "status": "success",
    "request_ms": 21,
    "count": 1,
    "data": [
        {
            "balance": 100.50
        }
    ]
}

Formas de pago

Formas de pago disponibles
get
https://api.semscraper.com/v1/billing/payment_methods
Autorizaciones : Bearer {api_key}
  • Solicitar
  • Respuesta satisfactoria
Status: 200 OK
{
    "status": "success",
    "request_ms": 43,
    "count": 3,
    "data": [
        {
            "id": 1,
            "name": "Perso",
            "num": "-4242",
            "expiration": "1226",
            "type": "Visa",
            "master": false
        },
        {
            "id": 30,
            "name": "Pro",
            "num": "-4444",
            "expiration": "1227",
            "type": "Mastercard",
            "master": true
        }
    ]
}