Se connecter Testez gratuitement
Deutsch English Español Français Italiano Português 日本語
Testez gratuitement Se connecter
  • Pour commencer
  • Démarrage rapide
  • Informations
  • Limite d'appels
  • Versions de Google
  • Liste des versions
  • SERPS
  • Requêtes Google Recherche
  • Requêtes Google Maps
  • IDs des requêtes
  • Récupérer les SERPs
  • Callback URL
  • Etat du traitement des SERPs
  • Historique des requêtes
  • Facturation
  • Crédit restant
  • Moyens de paiements

Documentation de l'API Semscraper

Démarrage rapide

Trois étapes pour récupérer votre première SERP Google en JSON.

  1. Créez votre compte : 1 000 SERPs sont offertes, sans carte bancaire. Copiez ensuite votre clé dans le menu Clés API de votre compte. Elle s'envoie dans l'en-tête Authorization: Bearer de chaque appel. Créer un compte gratuit
  2. Envoyez vos mots-clés avec POST /v1/serp, jusqu'à 1 000 par appel. La réponse renvoie l'identifiant de chaque SERP et son coût : c'est le seul moment où vous êtes facturé.
    Envoyer un mot-clé
    curl -X POST https://api.semscraper.com/v1/serp \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '[{"search_engine": "google_search", "keyword": "pate a crepe", "device": "desktop", "location": "fr", "language": "fr", "depth": 1}]'
  3. Récupérez le résultat avec GET /v1/serp et l'identifiant reçu : remplacez SERP_ID par la valeur du champ data[0].id renvoyée à l'étape précédente.La collecte est asynchrone : tant que le statut est pending ou processing, réessayez un peu plus tard. La récupération n'est jamais facturée.
    Récupérer la SERP
    curl "https://api.semscraper.com/v1/serp?ids=SERP_ID&output=json" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Pour être prévenu sans interroger l'API, ajoutez un callback_url à vos requêtes. Pour des centaines de milliers de mots-clés, voyez l'API Bulk SERP.

Informations

Limite d'appels

Limite du nombre d’appels API
GET : 500 appels par minute
POST : 500 appels par minute

Versions de Google

Liste des versions

Permet d'obtenir les paramètres location et language requis pour récupérer des SERPs Google.
get
https://api.semscraper.com/v1/serp/google/location
Autorisations : Bearer {api_key}
  • Requête
  • Réponse réussie
Status: 200 OK
{
    "status": "success",
    "request_ms": 17,
    "count": 372,
    "data": [
        {
            "location": "us",
            "language": "en",
            "host": "google.com",
            "name": "United States"
        },
        {
            "location": "fr",
            "language": "fr",
            "host": "google.fr",
            "name": "France"
        }
}

SERPs

Requêtes Google Recherche

Créer des requêtes de SERPs Google Recherche
Les données doivent être envoyées dans un tableau JSON. Chaque élément doit contenir les champs suivants.
Limite
Le tableau JSON peut contenir 1000 éléments, vous pouvez donc créer 1000 scrapes de SERPs en un seul appel.
post
https://api.semscraper.com/v1/serp
Autorisations : Bearer {api_key}
Paramètres
search_engine
Requis
string
Choix du moteur de recherche :
Google Recherche (valeur : google_search)
keyword
Requis
string
Mots-clés à rechercher sur le moteur de recherche
device
Requis
string
Choix du support :
Ordinateur (valeur : desktop)
Mobile (valeur : mobile)
depth
Requis
integer
Profondeur de pages, nous récupérons les SERPs Google avec pagination. Ce paramètre doit être compris entre 1 (environ 10 résultats) et 10 (environ 100 résultats).
location
Requis
string
Code de localisation du moteur de recherche
language
Requis
string
Langue du moteur de recherche
geolocation
string
Permet de géolocaliser une SERP Google. Indiquez la ville, le département et le pays séparés par des virgules (ex. : Nice, Alpes-Maritimes, France), ou une position GPS latitude,longitude en décimal (ex. : 43.7102,7.2620).
priority
integer
Permet de prioriser vos demandes, elles sont traitées par priorité décroissante. Valeur entre 1 (low) et 10 (high).
callback_url
string
Permet d'indiquer une URL sur laquelle nous allons vous envoyer les résultats du mot-clé une fois celui-ci traité.
Types de blocs de résultats
Valeurs possibles du champ type. Un bloc n'est présent dans la réponse que si Google l'affiche pour le mot-clé demandé.
Résultats et annonces
organic
Résultat naturel
Résultat naturel de la recherche.
sitelinks
Liens de site
Lien secondaire rattaché à un résultat naturel.
paid_top
Annonce en haut
Annonce payante au-dessus des résultats naturels.
paid_bottom
Annonce en bas
Annonce payante sous les résultats naturels.
Blocs enrichis
featured_snippet
Position zéro
Extrait mis en avant au-dessus des résultats naturels.
knowledge_graph
Panneau de connaissance
Élément du panneau affiché à droite de la SERP.
images
Images
Vignette du bloc d'images.
videos
Vidéos
Vidéo du bloc vidéos.
top_stories
Actualités
Article du bloc actualités.
shopping
Shopping
Produit du carrousel Google Shopping.
recipes
Recettes
Recette du bloc recettes.
local_pack
Bloc local
Établissement du bloc local, issu de Google Maps.
visual_digest
Résumé visuel
Élément du résumé visuel généré par Google.
Suggestions et rebonds
people_also_ask
Autres questions posées
Question du bloc Autres questions posées.
related_searches
Recherches associées
Recherche associée proposée en bas de page.
find_results_on
Trouver des résultats sur
Lien du bloc Trouver des résultats sur.
location_sites
Sites de localisation
Site listé dans un bloc lié à une localisation.
AI Overview
ai_overview_citation
Citation
Marque citée dans le texte généré par l'IA.
ai_overview_citation_source
Source de citation
Source d'une citation, visible au survol de celle-ci.
ai_overview_panel
Panneau de sources
Site listé dans le panneau latéral de sources.
  • Requête
  • Réponse réussie
  • Réponse d’erreur
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
}

Requêtes Google Maps

Créer des requêtes de SERPs Google Maps
Les données doivent être envoyées dans un tableau JSON. Chaque élément doit contenir les champs suivants.
Limite
Le tableau JSON peut contenir 1000 éléments, vous pouvez donc créer 1000 scrapes de SERPs en un seul appel.
post
https://api.semscraper.com/v1/serp
Autorisations : Bearer {api_key}
Paramètres
search_engine
Requis
string
Choix du moteur de recherche :
Google Maps (valeur : google_maps)
keyword
Requis
string
Mots-clés à rechercher sur le moteur de recherche
depth
Requis
integer
Profondeur de pages, nous récupérons les SERPs Google avec pagination. Ce paramètre doit être compris entre 1 (environ 10 résultats) et 10 (environ 100 résultats).
location
Requis
string
Code de localisation du moteur de recherche
language
Requis
string
Langue du moteur de recherche
geolocation
string
Permet de géolocaliser une SERP Google. Indiquez la ville, le département et le pays séparés par des virgules (ex. : Nice, Alpes-Maritimes, France), ou une position GPS latitude,longitude en décimal (ex. : 43.7102,7.2620). Avec une position GPS, vous pouvez ajouter un niveau de zoom facultatif (ex. : 43.7102,7.2620,16z).
priority
integer
Permet de prioriser vos demandes, elles sont traitées par priorité décroissante. Valeur entre 1 (low) et 10 (high).
callback_url
string
Permet d'indiquer une URL sur laquelle nous allons vous envoyer les résultats du mot-clé une fois celui-ci traité.
  • Requête
  • Réponse réussie
  • Réponse d’erreur
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
}

IDs des requêtes

Liste des identifiants (ID) des SERP terminées que vous n'avez pas encore récupérés.
Cette méthode vous permet d’obtenir les IDs de toutes les SERP déjà traitées mais encore jamais récupérées. Vous pourrez ensuite appeler la méthode de récupération des SERP en utilisant ces IDs.
get
https://api.semscraper.com/v1/serp
Autorisations : Bearer {api_key}
  • Requête
  • Réponse réussie
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"
                }
            }
        }
    ]
}

Récupérer les SERPs

Récupérer des SERPs Google via leurs IDs
Récupérer plusieurs SERPs en un appel (au format JSON ou HTML) en fournissant plusieurs IDs séparés par une virgule.
Limite
Vous pouvez indiquer 100 IDs maximum, ce qui vous permet de récupérer 100 SERPs en un seul appel.
get
https://api.semscraper.com/v1/serp?ids=id1,id2&output=json
Autorisations : Bearer {api_key}
Paramètres
ids
Requis
string
Liste des IDs séparés par une virgule.
output
Requis
string
Choix du format de sortie :
JSON (valeur : json)
HTML (valeur : html)
Format de résultat
  • Google Search
  • Google Maps
type
string
Type de bloc de résultat (organic, videos, images, people_also_ask, local_pack...)
rank_type
integer
Position de l'élément au sein de son propre type de bloc (ex : 3ème résultat organique = 3)
rank_serp
integer
Position absolue dans la SERP complète, tous blocs confondus, selon la position verticale réelle sur la page (au pixel)
page
integer
Numéro de page de la SERP où apparaît l'élément
pixel
integer
Position verticale de l'élément sur la page, en pixels depuis le haut
domain
string
Domaine de l'URL
url
string
URL du résultat
title
string
Titre affiché du résultat
description
string
Description / extrait affiché du résultat
brand
string
Marque citée ou libellé de la source tel que Google l'affiche. Uniquement sur les blocs ai_overview_citation, ai_overview_citation_source et ai_overview_panel. Sur une citation, l'URL est souvent vide : la marque est alors la seule information de l'élément.
visible
boolean
Élément affiché d'emblée dans l'AI Overview (true) ou visible seulement après dépliage (false). Uniquement sur les blocs AI Overview. Toujours false pour ai_overview_citation_source, qui n'apparaît qu'au survol d'une citation.
rating
float
Note moyenne affichée par Google (par exemple 4.1). Uniquement sur les blocs organic et local_pack, null si le résultat n'affiche pas d'étoiles.
reviews
integer
Nombre d'avis associé à la note. Uniquement sur les blocs organic et local_pack, null si le résultat n'affiche pas d'étoiles.
price_range
string
Fourchette de prix de l'établissement telle que Google l'affiche (par exemple « 20–30 € »). Uniquement sur le bloc local_pack, null si absente.
details
array
Informations affichées sous l'établissement, dans l'ordre et la langue de Google : prix, catégorie, adresse, horaires, services… Uniquement sur le bloc local_pack. Ni l'ordre ni la présence de chaque information ne sont garantis.
serp_info.ai_overview
object
AI Overview de la SERP, dans l'objet serp_info (pas dans results). Contient type, text et complete.
serp_info.ai_overview.type
string
Mode d'affichage de l'AI Overview : sync (présent dans la page dès son chargement), async (généré par Google à la volée, après le chargement de la page) ou none (aucun AI Overview).
serp_info.ai_overview.text
string
Texte généré par l'IA, en texte brut (sans mise en forme ni liens). null si la SERP n'a pas d'AI Overview ou si le texte n'a pas pu être lu.
serp_info.ai_overview.complete
boolean
True si l'AI Overview avait fini de se générer au moment de la capture. false si le texte est absent ou peut être incomplet.
rank_type
integer
Position de l'élément au sein de son propre type de bloc (ex : 3ème résultat organique = 3)
rank_serp
integer
Position absolue dans la SERP complète, tous blocs confondus, selon la position verticale réelle sur la page (au pixel)
page
integer
Numéro de page de la SERP où apparaît l'élément
pixel
integer
Position verticale de l'élément sur la page, en pixels depuis le haut
title
string
Titre affiché du résultat
cid
string
Identifiant Google (CID) de la fiche établissement
reviews
integer
Nombre d'avis
rating
float
Note moyenne sur 5
website
string
Site web de l'établissement
type
string
Catégorie de l'établissement (ex : Restaurant)
address
string
Adresse postale
status_label
string
Statut d'ouverture (ex : Ouvert, Fermé)
status_detail
string
Détail du statut (ex : horaires)
comment
string
Commentaire / extrait affiché
images
array
Liste des images de la fiche
  • Requête
  • Réponse réussie
  • Réponse d’erreur
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
}

Callback URL

Récupérer les SERPs via une URL de callback
Vous pouvez recevoir le résultat d'un SERP directement sur une URL que vous nous fournissez lors de la création d'une requête, il vous suffit de récupérer la clé de HMAC liée à la clé API utilisée.
  • Code
  • 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')
]);

Etat du traitement des SERPs

Etat des lieux du traitement des SERPs
Permet de voir le nombre de SERPs en fonction de leurs statuts :
Terminées et résultats récupérés par l'utilisateur (status=done, fetched=true)
Terminées et résultats non récupérés par l'utilisateur (status=done, fetched=false)
En cours de traitement (status=processing)
En attente (status=pending)
get
https://api.semscraper.com/v1/serp/status
Autorisations : Bearer {api_key}
  • Requête
  • Réponse réussie
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
        }
    ]
}

Historique des requêtes

Liste vos requêtes, de la plus récente à la plus ancienne, avec leur configuration (mot-clé, moteur, device, location, langue, profondeur…) et leur statut, sans le résultat SERP.
Toutes les requêtes du compte sont renvoyées, quel que soit leur statut et qu'elles aient déjà été récupérées ou non. Cet appel ne les marque pas comme récupérées.

Pour paginer, rappelez l'endpoint avec le paramètre cursor égal au next_cursor de la réponse précédente, tant que has_more vaut true. Le lien _links.next contient l'URL toute prête. Pour obtenir le résultat d'une requête, utilisez son lien _links.json ou _links.html.
Limite
10 000 requêtes par appel
get
https://api.semscraper.com/v1/serp/list?date=2026-11-03&limit=1000
Autorisations : Bearer {api_key}
Paramètres
date
string
Jour de création des requêtes, au format AAAA-MM-JJ (par exemple 2026-10-04). Sans ce paramètre, toutes les dates sont renvoyées.
status
string
Filtre sur le statut : pending, processing ou done. Sans ce paramètre, tous les statuts sont renvoyés.
limit
integer
Nombre de requêtes par page, de 1 à 10 000. 1 000 par défaut.
cursor
string
Curseur de pagination : la valeur next_cursor de la réponse précédente. À omettre pour la première page.
  • Requête
  • Réponse réussie
  • Réponse d’erreur
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
}

Facturation

Crédit restant

Récupère le montant du crédit restant
get
https://api.semscraper.com/v1/billing/credit
Autorisations : Bearer {api_key}
  • Requête
  • Réponse réussie
Status: 200 OK
{
    "status": "success",
    "request_ms": 21,
    "count": 1,
    "data": [
        {
            "balance": 100.50
        }
    ]
}

Moyens de paiements

Moyens de paiements disponibles
get
https://api.semscraper.com/v1/billing/payment_methods
Autorisations : Bearer {api_key}
  • Requête
  • Réponse réussie
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
        }
    ]
}