NAV

Utilisation de l'API

Bienvenue sur l'API ranxplorer.

Cet guide d'utilisation décrit les différentes méthodes accessibles via l'API. L'API a été conçue pour faciliter l'accès à notre base de plus de 3 milliards de résultats et 100 millions de mots-clés.

Fonctionnement de l'API

L'utilisation de l'API est réservé aux comptes Premium. Pour accéder à l'API, vous devez utiliser votre token API disponible dans votre interface client sur le site ranxplorer.com.

Coût d'utilisation de l'API

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "www.ranks.fr",
    "path": "host",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119500
  },
   "data": [
  {...},
  {...}
  ]
}

Chaque requête adressée à l'API est facturée sur la base d'un montant de 1 crédit par ligne de résultats renvoyés. Néanmoins pour prendre en compte la charge consommée à chaque requête, le coût minimum par requête est de 25 crédits.

Par exemple, le côut pour la récupération des 100 premières positions d'un site sera de 100 crédits tandis que le coût pour la récupération de la première position sera de 25 crédits (seuil minimum). Pour que vous puissiez maitrisez au mieux votre budget, vous pouvez choisir la limite de résultats que vous souhaitez obtenir pour chaque requête. Par ailleurs, chaque réponse renvoyée par l'API contient un élément méta qui récapitule:

SEO

Historique SEO

Récupérez une synthèse historisée des principaux indicateurs clés de la visibilité d'un site dans les résultats de recherche naturelle. La recherche peut porter sur un domaine, un sous-domaine, un répertoire ou une url. Si la recherche porte sur un répertoire ou une url, seul le dernier mois est disponible.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/seo" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="www.ranks.fr" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "www.ranks.fr",
    "path": "host",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119500
  },
  "data": [
    {
      "Date": "2015-11",
      "Est": 4884,
      "Nbkw": 2726,
      "kw10": 113,
      "kw3": 13,
      "kw1": 7,
      "Nburl": 701
    },
    {
      "Date": "2015-12",
      "Est": 4964,
      "Nbkw": 2845,
      "kw10": 124,
      "kw3": 21,
      "kw1": 7,
      "Nburl": 707
    }
  ]
}

HTTP Request

GET v1/seo

Paramètres

Paramètre Type Status Description
search string requis Longeur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats
forcepath string optionnel domaine, host, dir or url

Réponse

Champ Description
Date Date de la dernière mise à jour des résultats (seul le mois et l'année varient)
Est Estimation du trafic seo (nombre de visiteurs par mois)
Nbkw Nombre total de mots-clés identifiés dans les résultats de recherche (top 50 minimum)
kw10 Nombre de mots-clés positionnés dans les 10 premières positions
kw3 Nombre de mots-clés positionnés dans les 3 premières positions
kw1 Nombre de mots-clés positionnés en première position
Nburl Nombre d'urls positionnées

Mots-clés positionnés

Récupérez la liste des expressions sur lesquelles un site apparait dans les 50 premiers résultats naturels au minimum (jusqu'à 100 en fonction du mot-clé). La recherche peut porter sur un domaine, un sous-domaine, un répertoire ou une url.

Exemple de requête:


curl -G "http://api.ranxplorer.com/v1/seo/keywords" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="www.ranks.fr" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "www.ranks.fr",
    "path": "host",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119825
  },
  "data": [
    {
      "Kw": "ranks",
      "Url": "www.ranks.fr/",
      "Rx": 1,
      "Vol": 1600,
      "Est": 1440,
      "Nb": 139000000,
      "Cpc": "0.00",
      "Date": "2016-09-03"
    },
    {
      "Kw": "serpometre",
      "Url": "www.ranks.fr/fr/serpometre",
      "Rx": 1,
      "Vol": 320,
      "Est": 288,
      "Nb": 618,
      "Cpc": "0.00",
      "Date": "2016-09-11"
    }
  ]
}

HTTP Request

GET v1/seo/keywords

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats
forcepath string optional domaine, host, dir ou url
RxGt integer optional Filter sur les positions du sites supérieures à un rang (>) entre 0 et 99
RxEq integer optional Filter sur les positions du sites égales à un rang (=) entre 1 et 100
RxLs integer optional Filter sur les positions du sites inférieures à un rang (<) entre 2 et 100
VolGt integer optional Filter sur les mots clés dont le volume de recherche est supérieur à une valeur
VolEq integer optional Filter sur les mots clés dont le volume de recherche est égal à une valeur
VolLs integer optional Filter sur les mots clés dont le volume de recherche est inférieur à une valeur
IsAd boolean optional Filtrer sur les mots clés avec des Adwords (valeur 1 ou 0)
IsSh boolean optional Filtrer sur les mots clés avec des annonces Shopping/PLA (valeur 1 ou 0)
IsAb boolean optional Filtrer sur les mots clés avec des AnswerBox (valeur 1 ou 0)
IsIm boolean optional Filtrer sur les mots clés avec des images (valeur 1 ou 0)
IsBd boolean optional Filtrer sur les mots clés liés à des marques (valeur 1 ou 0)
IsSp boolean optional Filtrer sur les mots clés avec des fautes d'orthographes(valeur 1 ou 0)
IsNs boolean optional Filtrer sur les mots clés avec des actualités (valeur 1 ou 0)
IsMp boolean optional Filtrer sur les mots clés avec des maps(valeur 1 ou 0)
IsKg boolean optional Filtrer sur les mots clés avec des knowledges graphs(valeur 1 ou 0)

Réponse

Champ Description
Kw Mot-clé positionné
Url Url exacte sur laquelle le site est positionné pour le mot-clé
Rx Position dans les résultats de recherche naturelle (50 premiers résultats au minimum)
Vol Volume de recherche mensuel pour ce mot-clé (estimation en provenance du générateur de mots-clés google adwords)
Est Estimation du trafic seo (nombre de visiteurs par mois)
Nb Nombre de résultats pour le mot-clé (donnée affichée dans une recherche google)
Cpc Cout par clic adwords maximum en euros
Date Date de la dernière mise à jour des résultats pour ce mot-clé

Urls positionnées

Récupérez la liste des urls sur lesquelles un site apparait dans les 50 premiers résultats naturels au minimum. La recherche peut porter sur un domaine, un sous-domaine, un répertoire ou une url.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/seo/urls" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="www.ranks.fr" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "www.ranks.fr",
    "path": "host",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119800
  },
  "data": [
    {
      "Url": "www.ranks.fr/",
      "Est": 1876,
      "Nbkw": 186,
      "Date": "2016-09-01"
    },
    {
      "Url": "www.ranks.fr/fr/serpometre",
      "Est": 291,
      "Nbkw": 4,
      "Date": "2016-09-01"
    }
  ]
}

HTTP Request

GET v1/seo/urls

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats
forcepath string optional domaine, host, dir or url

Réponse

Champ Description
Url Url exacte sur laquelle le site est positionné pour le mot-clé
Est Estimation du trafic seo (nombre de visiteurs par mois)
Nbkw Nombre de mots-clés positionnés pour cette url
Date Date de la dernière mise à jour des résultats pour ce mot-clé (seul le mois et l'année varient)

Résultats de recherche

Récupérez la liste des résultats affichés dans les résultats naturels pour un mot-clé donné. Pour un mot-clé présent dans notre base de données, nous collectons au minimum les 50 premiers résultats, jusqu'à 100 en fonction du mot clé.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/seo/serps" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="design" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "design",
    "path": "serps",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119775
  },
  "data": [
    {
      "Url": "fr.wikipedia.org/wiki/Design",
      "Rx": 1,
      "Ssl": 1,
      "Date": "2016-09-03"
    },
    {
      "Url": "www.madeindesign.com/",
      "Rx": 2,
      "Ssl": 0,
      "Date": "2016-09-03"
    }
  ]
}

HTTP Request

GET v1/seo/serps

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats

Réponse

Champ Description
Url Url exacte sur laquelle le site est positionné pour le mot-clé
Rx Position dans les résultats de recherche naturelle (50 premiers résultats au minimum)
Ssl Indique si l'url est disponible via HTTP ou HTTPS
Date Date de la dernière mise à jour des résultats pour ce mot-clé

SEA

Historique SEA

Récupérez une synthèse historisée des principaux indicateurs clés de la visibiltié d'un site dans les résultats de recherche payants. La recherche peut porter sur un domaine, un sous-domaine, un répertoire ou une url. Si la recherche porte sur un répertoire ou une url, seul le dernier mois est disponible.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/sea" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="madeindesign.com" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "madeindesign.com",
    "path": "domaine",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 115950
  },
  "data": [
    {
      "Date": "2016-08",
      "Est": 17393,
      "Cost": 5450,
      "Nbkw": 5602,
      "Nburl": 1121
    },
    {
      "Date": "2016-09",
      "Est": 21845,
      "Cost": 6497,
      "Nbkw": 9268,
      "Nburl": 1311
    }
  ]
}

HTTP Request

GET v1/sea

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats
forcepath string optional domaine, host, dir or url

Réponse

Champ Description
Date Date de la dernière mise à jour des résultats (seul le mois et l'année varient)
Est Estimation du trafic seo (nombre de visiteurs par mois)
Cost Budget adwords estimé en euros à partir du nombre de mots-clés, de leur positions adwords et du CPC max
Nbkw Nombre total de mots-clés identifiés dans les résultats de recherche (top50 minimum)
Nburl Nombre d'urls positionnées

Mots-clés positionnés

Récupérez la liste des expressions sur lesquelles un site apparait dans les résultats sponsorisés (Ads, Shopping). La recherche peut porter sur un domaine, un sous-domaine, un répertoire ou une url.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/sea/keywords" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="www.madeindesign.com" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "www.madeindesign.com",
    "path": "host",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119350
  },
  "data": [
    {
      "Kw": "made in design",
      "Url": "www.madeindesign.com/",
      "Typ": "Adwords haut",
      "Rx": 1,
      "Vol": 60500,
      "Est": 4302,
      "Nb": 316000000,
      "Cpc": "0.13",
      "Date": "2016-09-01"
    },
    {
      "Kw": "fermob",
      "Url": "www.madeindesign.com/b-fermob.html",
      "Typ": "Adwords haut",
      "Rx": 1,
      "Vol": 33100,
      "Est": 2354,
      "Nb": 1740000,
      "Cpc": "0.44",
      "Date": "2016-09-01"
    }
  ]
}

HTTP Request

GET v1/sea/keywords

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats
forcepath string optional domaine, host, dir or url

Réponse

Champ Description
Kw Mot-clé positionné
Url Url exacte sur laquelle le site est positionné pour le mot-clé
Typ  Type d'annonce (Adwords haut, Adwords bas ou Shopping)
Rx Position dans les résultats de recherche payante
Vol Volume de recherche mensuel pour ce mot-clé (estimation en provenance du générateur de mots-clés google adwords)
Est Estimation du trafic sea (nombre de visiteurs par mois)
Nb Nombre de résultats pour le mot-clé (donnée affichée dans une recherche google)
Cpc Cout par clic adwords maximum en euros
Date Date de la dernière mise à jour des résultats pour ce mot-clé

Urls positionnées

Récupérez la liste des urls sur lesquelles un site apparait dans les résultats payants. La recherche peut porter sur un domaine, un sous-domaine, un répertoire ou une url.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/sea/urls" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="www.madeindesign.com" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "www.madeindesign.com",
    "path": "host",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119325
  },
  "data": [
    {
      "Url": "www.madeindesign.com/",
      "Est": 12228,
      "Nbkw": 5960,
      "Date": "2016-09-01"
    },
    {
      "Url": "www.madeindesign.com/b-fermob.html",
      "Est": 2471,
      "Nbkw": 19,
      "Date": "2016-09-01"
    }
  ]
}

HTTP Request

GET v1/sea/urls

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats
forcepath string optional domaine, host, dir or url

Réponse

Champ Description
Url Url exacte sur laquelle le site est positionné pour le mot-clé
Est Estimation du trafic seo (nombre de visiteurs par mois)
Nbkw Nombre de mots-clés positionnés pour cette url
Date Date de la dernière mise à jour des résultats pour ce mot-clé (seul le mois et l'année varient)

Résultats de recherche

Récupérez la liste des résultats affichés dans les résultats payants pour un mot-clé donné. Pour un mot-clé présent dans notre base de données, nous collectons la présence sur les emplacements adwords haut, adwords bas et google shopping.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/sea/serps" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="credit" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "credit",
    "path": "serps",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 119300
  },
  "data": [
    {
      "Url": "www.carrefour-banque.fr/credit/pret-personnel/simulation-pret",
      "Typ": "Adwords haut",
      "Rx": 1,
      "Ssl": 0,
      "Date": "2016-09-10"
    },
    {
      "Url": "www.cofidis.fr/fr/credit_en_ligne/simulateur-credits.html",
      "Typ": "Adwords haut",
      "Rx": 2,
      "Ssl": 1,
      "Date": "2016-09-10"
    }
  ]
}

HTTP Request

GET v1/sea/serps

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats

Réponse

Champ Description
Url Url exacte sur laquelle le site est positionné pour le mot-clé
Typ  Type d'annonce (Adwords haut, Adwords bas ou Shopping)
Rx Position dans les résultats de recherche payants
Ssl Indique si l'url est disponible via HTTP ou HTTPS
Date Date de la dernière mise à jour des résultats pour ce mot-clé

Mots-clés

Détail mot-clé

Récupérez les informations liées à un mot-clé tels que le volume de recherche ou la typologie du mot-clé.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/kwd" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="fnac" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "fnac",
    "path": "serps",
    "results": 1,
    "used-credits": 25,
    "remaining-credits": 114900
  },
  "data": {
    "Vol": 4090000,
    "M1": 4090000,
    "M2": 4090000,
    "M3": 4090000,
    "M4": 3350000,
    "M5": 3350000,
    "M6": 4090000,
    "M7": 4090000,
    "M8": 3350000,
    "M9": 4090000,
    "M10": 4090000,
    "M11": 6120000,
    "M12": 7480000,
    "Cpc": "0.01",
    "Comp": "0.11",
    "Nb": 27900000,
    "IsAd": 1,
    "IsSh": 0,
    "IsIm": 0,
    "IsBd": 1,
    "IsSp": 0,
    "IsNs": 1,
    "IsMp": 0,
    "IsKg": 1,
    "IsAb": 0
  }
}

HTTP Request

GET v1/kwd

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères

Réponse

Champ Description
Vol volume de recherche mensuel pour le mot-clé (moyenne annuelle)
M1  volume de recherche mensuel pour ce mot-clé en Janvier
M2  volume de recherche mensuel pour ce mot-clé en Février
M3  volume de recherche mensuel pour ce mot-clé en Mars
M4  volume de recherche mensuel pour ce mot-clé en Avril
M5  volume de recherche mensuel pour ce mot-clé en Mai
M6  volume de recherche mensuel pour ce mot-clé en Juin
M7  volume de recherche mensuel pour ce mot-clé en Juillet
M8  volume de recherche mensuel pour ce mot-clé en Aout
M9  volume de recherche mensuel pour ce mot-clé en Septembre
M10  volume de recherche mensuel pour ce mot-clé en Octobre
M11  volume de recherche mensuel pour ce mot-clé en Novembre
M12  volume de recherche mensuel pour ce mot-clé en Décembre
Cpc Cout par clic adwords maximum en euros
Comp indice de niveau de concurrence moyen pour le mot-clé, en adwords (indice compris entre 0 et 1)
Nb Nombre de résultats pour le mot-clé (donnée affichée dans une recherche google)
IsAd Déclenche l'affichage d'un snippet google adwords
IsSh Déclenche l'affichage d'un snippet google shopping
IsIm Déclenche l'affichage d'un snippet google images
IsBd Considéré comme une marque
IsSp Comporte une faute d'orthographe
IsNs Déclenche l'affichage d'un snippet google Actualités
IsMp Déclenche l'affichage d'un snippet google Map
IsKg Déclenche l'affichage d'un snippet knowledge graph
IsAb Déclenche l'affichage d'un snippet Answer box

Mots-clés liés (version stricte)

Récupérez une liste de mots-clés liés à un mot-clé initial. Version stricte: les expressions renvoyées contiennent tous les mots présents dans l'expression recherchée.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/kwd/similars" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="fnac" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "fnac",
    "path": "keyword",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 113725
  },
  "data": [
    {
      "Kw": "fnac",
      "Vol": 4090000,
      "Cpc": "0.01",
      "Comp": "0.11"
    },
    {
      "Kw": "la fnac",
      "Vol": 165000,
      "Cpc": "0.02",
      "Comp": "0.15"
    }
  ]
}

HTTP Request

GET v1/kwd/similars

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats

Réponse

Champ Description
Kw Mot-clé lié
Vol volume de recherche mensuel pour le mot-clé (moyenne annuelle)
Cpc Cout par clic adwords maximum en euros
Comp indice de niveau de concurrence moyen pour le mot-clé, en adwords (indice compris entre 0 et 1)

Mots-clés liés (version large, cocon sémantique)

Récupérez une liste de mots-clés liés à un mot-clé initial. Version large: les expressions renvoyées sont liés au champ sématique recherché mais ne contiennent pas forcément les mots de l'expression recherchée.

Exemple de requête:

curl -G "http://api.ranxplorer.com/v1/kwd/broadmatch" \
-H "Accept: application/json" \
-H "X-Ranxplorer-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -d "search"="bonnet" \
    -d "limit"="2" \

Exemple de réponse:

{
  "errors": false,
  "metas": {
    "search": "bonnet",
    "path": "serps",
    "results": 2,
    "used-credits": 25,
    "remaining-credits": 90150
  },
  "data": [
    {
      "Mot": "bonnet homme",
      "Vol": 9900,
      "Cpc": "0.47",
      "Comp": "1.00"
    },
    {
      "Mot": "bonnet femme",
      "Vol": 8100,
      "Cpc": "0.48",
      "Comp": "1.00"
    }
  ]
}

HTTP Request

GET v1/kwd/broadmatch

Paramètres

Paramètre Type Status Description
search string requis Longueur maximum: 200 caractères
limit numeric optionnel Par défaut: 50 résultats

Réponse

Champ Description
Kw Mot-clé lié
Vol volume de recherche mensuel pour le mot-clé (moyenne annuelle)
Cpc Cout par clic adwords maximum en euros
Comp indice de niveau de concurrence moyen pour le mot-clé, en adwords (indice compris entre 0 et 1)

Erreurs

Liste des erreurs et des messages liés

Exemple d'erreur

{
  "errors": true,
  "message": "Invalid token"
}
Code réponse HTTP Message  Détail
400  Bad request  Un problème est survenu dans le traitement de la requête
403 Invalid token Votre token d'identification n'est pas reconnu comme valable
403 Not enough credits Votre crédit API n'est pas suffisant pour effectuer cette requête
404  Record not found  L'adresse demandée n'existe pas