API

L’API est incluse dans tous les comptes, sans supplément. Tout ce que fait l’interface sur vos projets, vos mots-clés et vos positions se fait aussi par appel HTTP.

Obtenir une clé

1. 1Ouvrez Paramètres puis l’onglet CompteLa section Clé API est en bas de l’onglet.
2. 2Cliquez sur GénérerLa clé commence par pt_live_. Copiez-la tout de suite : elle n’est affichée qu’une fois, car nous n’en conservons qu’une empreinte et son début. Elle vaut mot de passe.
3. 3Révoquez ou régénérez à tout momentRégénérer remplace la clé existante, Révoquer la supprime. Dans les deux cas l’ancienne clé cesse immédiatement de fonctionner.

Authentification

Chaque requête porte la clé dans l’en-tête X-API-Key. L’URL de base est https://tool.positiontiger.com/api.

curl https://tool.positiontiger.com/api/projects \
  -H "X-API-Key: pt_live_votre_cle"

Sans clé valide, la réponse est un 401 avec {"error":"Unauthorized"}.

Les ressources

Lire des positions

GET /api/positions est la ressource la plus riche. Seul le projet est obligatoire : son nom (project) ou son identifiant (projectId, donné par GET /api/projects). Partout où l’API attend project, vous pouvez donner projectId à la place.

Un nom de projet est unique dans votre compte. Si d’anciens projets portent le même nom, project désigne toujours le plus ancien en lecture, et la réponse le signale dans meta (sameName liste les autres identifiants, note l’explique). Une écriture (ajout, suppression, actualisation, tags, concurrents) avec un tel nom est refusée (409, avec les identifiants) : utilisez alors projectId.

curl "https://tool.positiontiger.com/api/positions?project=Acme%20Shop&days=30&device=desktop&include=all" \
  -H "X-API-Key: pt_live_votre_cle"

Chaque ligne renvoie le mot-clé, la position, la position précédente, l’évolution, l’URL classée, la date, l’appareil, la localisation, le site suivi et les tags. meta.filtered donne le total, à utiliser pour paginer avec offset.

Votre site compte avec tous ses sous-domaines (fr.exemple.com, blog.exemple.com), comme dans le tableau de bord : la position est la meilleure d’entre eux, et url dit laquelle.

La position et la date sont celles du dernier relevé, comme dans le tableau de bord et les rapports : un mot-clé vérifié où votre site n’apparaît pas dans les résultats renvoie "position": null à la date de ce relevé. lastRankedPosition et lastRankedDate donnent la dernière fois où votre site était classé (null s’il ne l’a jamais été). previousPosition est la position au relevé précédent. Avec une endDate passée, la position et la date sont celles du dernier relevé jusqu’à cette date incluse.

{
  "keywords": [
    {
      "term": "acme shop",
      "position": 1,
      "previousPosition": 2,
      "evolution": 1,
      "url": "https://acme-shop.com/",
      "date": "2026-09-22T00:00:00Z",
      "lastRankedPosition": 1,
      "lastRankedDate": "2026-09-22T00:00:00Z",
      "device": "desktop",
      "location": "FR",
      "site": "https://acme-shop.com",
      "tags": ["brand"]
    }
  ],
  "meta": { "project": "Acme Shop", "projectId": 4746, "filtered": 381, "returned": 100, "limit": 100, "offset": 0 }
}

Les dates sont au format AAAA-MM-JJT00:00:00Z (le jour du relevé, en UTC). Si les positions ne peuvent pas être lues à ce moment-là, la réponse est un 503 avec un en-tête Retry-After : réessayez quelques minutes plus tard (aucune position n’est renvoyée vide à tort).

Ajouter un mot-clé

curl -X POST https://tool.positiontiger.com/api/keywords \
  -H "X-API-Key: pt_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"project":"Acme Shop","term":"perceuse sans fil","location":"FR","lang":"fr","device":"desktop"}'

Un mot-clé déjà suivi dans le projet (même terme, pays, langue et appareil) renvoie un 409, sans rien débiter. Le même terme dans un autre pays ou sur l’autre appareil est un autre mot-clé. Un mot-clé déjà suivi dans un autre de vos projets (même terme, pays, langue et appareil) n’est gratuit que si vous l’avez déjà payé aujourd’hui (jour UTC) : il reprend ce relevé. Sinon, il coûte 6 pages et il est relevé tout de suite. Si votre solde est vide, la réponse est un 403 avec le code INSUFFICIENT_CREDITS.

location est le code du pays (FR par défaut). Un pays où nous ne relevons pas les positions est refusé : 400, avec la liste de tous les pays et de leur code dans countries, et rien n’est débité.

lang est la langue de la recherche, par défaut celle du pays. Toute langue est acceptée avec tout pays, comme dans le tableau de bord : les positions sont demandées à Google dans ce pays (gl) avec cette langue (hl), soit ce que voit une personne dans ce pays dont Google est réglé dans cette langue. Quand Google Ads n’a pas de volume pour cette langue dans ce pays, c’est le volume des langues du pays qui est affiché.

Projets

DELETE /api/projects/sites reconnaît un site à son domaine, avec ou sans https://, quel que soit le chemin (www.exemple.com et https://www.exemple.com/fr sont le même site). Il ne retire jamais le dernier de vos sites du projet : la demande est alors refusée (409) et rien n’est retiré ; ajoutez d’abord un autre site. Les mots-clés du projet et leur historique restent. La réponse donne le nombre de sites retirés (deleted) et ceux qui restent (trackedSites).

Sites

Dans /api/sites, un « site » est un projet : siteId est l’identifiant d’un projet. Pour ajouter ou retirer un des sites suivis dans un projet, voir PUT /api/projects et DELETE /api/projects/sites ci-dessus.

Mots-clés

Chaque mot-clé porte deux identifiants distincts, et ils ne sont pas interchangeables. id est votre ligne de suivi : propre à votre compte, c’est lui que prennent GET et DELETE /api/keywords/{id}. keywordId désigne le mot-clé lui-même — le couple terme + langue + pays — et il est partagé par tous les comptes qui suivent ce terme. Les deux suites de numéros avancent séparément, donc l’un passé à la place de l’autre désigne un mot-clé sans rapport. GET /api/keywords renvoie les deux, à titre indicatif. Pour lire des positions, aucun identifiant n’est nécessaire : GET /api/positions travaille sur le nom du projet et les termes.

Une suppression, par terme ou par id, ne retire que vos lignes de suivi. Un relevé déjà lancé au moment de la suppression est fait, et décompté ; un relevé encore en attente est retiré de la file, sauf si le mot-clé reste suivi sur cet appareil.

POST /api/keywords/refresh doit toujours dire quoi rafraîchir : un projet (project ou projectId), une liste non vide de termes (keywords, dans tous vos projets si aucun n’est donné), ou "mode": "all" pour tous les mots-clés du compte, envoyé seul : le corps est exactement {"mode": "all"}, et tout autre champ à côté est refusé (400). Un corps vide, {} ou un champ mal orthographié est refusé (400), sans rien rafraîchir ni débiter. Chaque relevé est décompté, 6 pages par mot-clé et par appareil, même si le mot-clé a déjà été relevé aujourd’hui.

Positions

Une seule ressource, GET /api/positions, dont les paramètres font tout le travail. Les combinaisons les plus utiles :

Concurrents

Tags

Essayer sans risque

Le Playground API du tableau de bord liste les endpoints, génère le code dans une douzaine de langages et montre une réponse d’exemple. Les requêtes lancées depuis le playground ne modifient pas vos projets.

Reports

381mots-clés

100%

227 008pages de résultat

API

N

PositionTiger API

Projets

GETListe tous vos projetsGETRécupérer un projet par idPOSTCréer un projetPUTRenommer un projetDELETESupprimer un projet

Sites

GETListe tous vos sitesGETRécupérer un site par idPOSTCréer un siteDELETESupprimer un site

Mots-clés

GETListe tous vos mots-clésPOSTAjouter un mot-cléPOSTRafraîchir des mots-clés

Requête

GET/api/projects

Afficher la cléExécuter

ccURLJJavaScriptPPythonPPHPRRubyGGoNNode.jsPPowerShellCC#JJavaSSwiftRR

curl -X GET "https://tool.positiontiger.com/api/projects" \
  -H "X-API-Key: pt_••••••••••••••••••••a4f2" \
  -H "Content-Type: application/json"

Réponse

200 OK

Données d’exemple. Exécuter une requête ici ne modifie pas vos projets.

{
  "projects": [
    {
      "id": 1,
      "name": "Jardin & Terrasse",
      "keywordCount": 203,
      "trackedSites": ["https://jardin-terrasse.fr"],
      "competitors": ["https://gamm-vert.fr", "https://truffaut.com"]
    },
    {
      "id": 2,
      "name": "Mobilier intérieur",
      "keywordCount": 84,
      "trackedSites": ["https://mobilier-inte.fr"],
      "competitors": ["https://conforama.fr"]
    }
  ],
  "total": 2
}

Une question qui n’a pas sa réponse ici ? Écrivez-nous.