Storelift

Storelift › Guides › L'API Storelift

Couche IA

L'API Storelift

Tout ce que montre le tableau de bord existe aussi en JSON. 27 endpoints GET lisent vos apps suivies et le marché, et POST /v1/actions prévisualise un changement que POST /v1/actions/confirm applique : un script, un tableur ou une étape de CI lit les mêmes chiffres et agit dessus. La référence complète est sur /docs/api/ et la spécification lisible par machine sur /openapi.json (OpenAPI 3.1) ; pour un assistant, le serveur MCP, inclus dès Pro.

Commencer gratuitement →Offre gratuite : 1 app, 10 mots-clés dans chacun des 2 storefronts, 14 jours d'historique, sans carte ni date de fin. Pro coûte 29 $/mois.

Par Mis à jour : 10 min de lecture

Suivi des mots-clés · historique des rangs, mouvements de la semaine et mots-clés suivis

Adresse de base et authentification

La base est https://storelift.net/v1. Créez une clé dans Settings → API ; elle n'est affichée qu'une fois et stockée uniquement sous forme de hash : une clé perdue se remplace, elle ne se récupère pas.

Envoyez-la dans x-api-key, ou comme jeton bearer si votre client ne gère que les en-têtes Authorization :

Terminal
curl -s https://storelift.net/v1/apps \
  -H "x-api-key: sl_live_..."
L'accès à l'API est inclus dans les plans Pro et Studio : à partir de 29 $ par mois, 99 $ pour Studio. La clé est conservée si vous changez pour un plan inférieur : repasser au plan supérieur réactive la même intégration.

Les 27 endpoints

EndpointCe qu'il renvoie
GET /v1/appsLes apps suivies par ce compte ; l'id des autres appels vient d'ici.
GET /v1/apps/{id}Une app et l'instantané de la dernière exécution.
GET /v1/apps/{id}/keywordsLe classement actuel de chaque mot-clé suivi dans un storefront, avec l'état de la mesure et la profondeur de recherche.
GET /v1/apps/{id}/rivalsLes apps placées au-dessus de vous, chacune avec les termes sur lesquels elle vous devance et les deux positions.
GET /v1/apps/{id}/aiSi un assistant cite votre app pour votre catégorie, avec la série enregistrée. Pro, Studio ou Enterprise requis.
GET /v1/apps/{id}/historyLa série de classement par mot-clé, tronquée à la fenêtre d'historique du plan.
GET /v1/apps/{id}/pageVotre propre fiche telle que le store la sert, sur les deux plateformes, avec les changements datés qui y ont été détectés.
GET /v1/apps/{id}/reviewsLes avis récents avec le résumé des étoiles, le nombre de nouveaux avis dans cette exécution, et le côté Play quand il est mesuré. /reviews/search cherche dans toute l'archive par texte, étoiles, version et dates ; /reviews/stats donne la répartition, la courbe quotidienne et la ventilation par version.
GET /v1/apps/{id}/timelineLes changements datés de la fiche — version, captures, événements, mises en avant, modifications du champ de mots-clés — chacun avec le mouvement de rangs des mots-clés autour.
GET /v1/apps/{id}/featuringCartes éditoriales, In-App Events et le rayon « Vous aimerez aussi » d'Apple par pays, avec l'historique daté des mises en avant et des nouveaux événements.
GET /v1/apps/{id}/chartsLa position dans le top pour la catégorie et le storefront de l'app, avec la série.
GET /v1/apps/{id}/revenueRevenus et téléchargements de l'app issus des sources connectées : unités App Store Connect, installations Google Play, MRR, abonnements et essais RevenueCat. connected:false si rien n'est connecté. Scope revenue:read.
GET /v1/apps/{id}/subscriptionsLe nombre d'événements d'abonnement reçus par le webhook RevenueCat / Adapty, par jour, par pays et par cohorte mensuelle. Scope revenue:read.
GET /v1/apps/{id}/funnelImpressions App Store → vues de la page produit → téléchargements : le point du jour et l'historique jour par jour issus des analytics App Store Connect. Scope revenue:read.
GET /v1/apps/{id}/pricingPrix en vigueur par produit et par pays, chaque période à prix fixe avec ses essais, ses premiers paiements et ses revenus, plus les codes d'offre, depuis le webhook RevenueCat / Adapty. Scope revenue:read.
GET /v1/apps/{id}/campaignsLes campagnes Apple Ads qui font la promotion de l'app (rapprochées par identifiant App Store) : dépenses, taps, installations, budget et statut, plus les principaux mots-clés et termes de recherche. Scope ads:read.

Les endpoints sous /apps/{id} acceptent country (un code de storefront comme us, par défaut le premier de l'app) et, quand les deux stores sont mesurés, platform=ios|android.

Les trois états de mesure passent la frontière intacts

Un champ de classement peut contenir un nombre, mais l'absence de nombre recouvre deux choses différentes, et l'API les garde séparées :

  • measured: true, rank: 7 : l'app a été trouvée en position 7.
  • measured: true, rank: null : la recherche a tourné et l'app n'était pas dans les résultats jusqu'à searchDepth.
  • measured: false : la recherche n'a pas pu être lancée ce jour-là. On ne sait rien de la position.
JSON
{
  "country": "de",
  "platform": "ios",
  "live": true,
  "measuredAt": "2026-09-19T02:14:08.921Z",
  "keywords": [
    { "term": "traumdeutung", "measured": true,  "rank": 7,    "demand": 6, "searchDepth": 200 },
    { "term": "traumsymbole", "measured": true,  "rank": null, "demand": 3, "searchDepth": 200 },
    { "term": "traumtagebuch", "measured": false, "rank": null, "demand": null, "searchDepth": null }
  ]
}

Fondre les deux derniers en zéro décrirait un effondrement qui n'a jamais eu lieu, et toute moyenne construite dessus serait fausse. Si votre code a besoin d'un seul nombre, traitez measured: false comme un trou dans la série, pas comme une valeur.

Compte, consommation et recherche

Quatre endpoints portent sur la clé elle-même et sur les données propres au compte. Les deux premiers ne coûtent rien. search et fetch suivent la forme qu'attend ChatGPT d'un connecteur deep research : une requête renvoie des identifiants, un identifiant renvoie l'enregistrement.

EndpointCe qu'il renvoie
GET /v1/accountÀ qui appartient la clé : plan, méthode d'authentification, scopes, apps lisibles, solde de crédits.
GET /v1/usageChaque quota avec utilisé / limite / remise à zéro, l'allocation Hive du jour et le débit par seconde.
GET /v1/search?q=Recherche dans vos apps, vos mots-clés suivis et vos concurrents ; renvoie des identifiants pour /v1/fetch.
GET /v1/fetch?id=L'enregistrement complet derrière un identifiant de recherche : fiche d'app, un mot-clé avec son historique, ou un concurrent avec les termes sur lesquels il vous devance.

Hive : n'importe quelle app, n'importe quel marché

Les endpoints ci-dessus lisent vos propres apps suivies. Les endpoints Hive lisent ce que mesure l'ensemble du réseau : tops, mesure quotidienne de n'importe quelle app, listes de résultats par mot-clé, mots-clés d'un concurrent, revenus et téléchargements de n'importe quelle app. Ils demandent leur propre scope sur la clé et coûtent plus de crédits par appel ; chaque plan a aussi une allocation Hive quotidienne, pour qu'un mois de crédits dure un mois.

EndpointCe qu'il renvoieScope
GET /v1/hive/charts?country=&kind=&genre=Le Top Free, le Top Grossing ou le classement iPad d'un storefront (100 places) au jour le plus récent.hive:read
GET /v1/hive/apps/{storeId}?country=La dernière mesure quotidienne de n'importe quelle app : nombre de notes, note, version, prix, répartition des étoiles, badge de catégorie, plus langues prises en charge, événements dans l'app à venir, texte promotionnel et achats intégrés mis en avant.hive:read
GET /v1/hive/keywords/{term}/ranks?country=&days=&top=Qui s'est classé sur un mot-clé, jour par jour (1 000 lignes par appel).hive:read
GET /v1/hive/spy/{storeId}?country=Les mots-clés sur lesquels un concurrent se classe, avec la même allocation mensuelle d'espionnage que dans le tableau de bord.hive:spy
GET /v1/hive/estimate/{storeId}?country=Revenus et téléchargements mensuels de n'importe quelle app de l'App Store, dans le monde entier (202 pendant la première lecture).hive:estimate
GET /v1/hive/movers?country=&kind=&genre=&days=&limit=Qui est monté, qui a chuté, qui est entré et qui est sorti d'un top, par rapport au même top N jours plus tôt. Chaque écart est calculé entre deux jours mesurés, et la réponse indique les deux.hive:read
GET /v1/hive/new?days=&country=&limit=Les apps vues pour la première fois dans un top, les plus récentes d'abord. La réponse indique combien de ces jours l'index couvre.hive:read
GET /v1/hive/find?genre=&country=&kind=&released=&rankMin=&rankMax=&text=&publisher=&page=Trouvez des apps dans les tops que nous mesurons : filtre par catégorie, storefront, top (Top Grossing, Top Free, Top Paid, Top iPad), tranche de rang, date de première apparition, nom ou éditeur. Chaque ligne porte les revenus et les téléchargements de l'app.hive:read
GET /v1/hive/gap?ids=&country=&platform=L'écart de mots-clés entre jusqu'à cinq apps côte à côte : sur quels termes chacune se classe et lesquels lui manquent. Hive Explorer. Chaque app porte son propre état de mesure.hive:spy
GET /v1/hive/publisher/{publisherId}Toutes les apps d'un éditeur que Hive a vues, avec le jour de leur première entrée dans un top.hive:read
GET /v1/hive/resolve?q=&country=&limit=L'identifiant de n'importe quelle app à partir d'un nom, d'un développeur, d'un lien de store, d'un id App Store ou d'un nom de paquet. Les noms passent par la recherche App Store de ce store.hive:read
GET /v1/hive/similar/{storeId}?country=Le rayon d'apps similaires du store pour n'importe quelle app, dans l'ordre du rayon, avec la catégorie et le nom de chacune et le jour de lecture.hive:read
GET /v1/hive/reviews/{storeId}?country=&limit=Les avis récents de n'importe quelle app dans un store avec la répartition des étoiles ; sans nom d'auteur.hive:read

Rien de personnel ne franchit cette ligne : les auteurs d'avis n'apparaissent jamais, et un mot-clé d'un concurrent ne s'affiche que si au moins deux autres comptes le suivent, ou si vous le suivez vous-même.

L'essayer sans clé

Chaque chemin existe aussi sous /v1/sandbox/, sans aucune clé : les mêmes formats, un jeu de données fixe de deux apps, des dates qui suivent la veille. Les réponses portent x-sandbox: true. Pour la CI, vous pouvez créer une clé de test (sl_test_) dans Settings : elle répond uniquement depuis le bac à sable, ne consomme aucun crédit et fonctionne sur tous les plans.

Terminal
curl -s https://storelift.net/v1/sandbox/apps
curl -s 'https://storelift.net/v1/sandbox/hive/keywords/sleep%20sounds/ranks?country=us&days=3&top=10'

Comment fonctionnent les écritures et les scopes

  • Chaque écriture est d'abord prévisualisée. POST /v1/actions renvoie le diff avant/après, le coût en crédits et un jeton à usage unique, sans rien modifier ; POST /v1/actions/confirm l'applique. Le jeton est lié à l'action, aux arguments et à l'état de la cible au moment de la prévisualisation : si la cible a changé entre-temps, la confirmation renvoie confirm_token_mismatch et n'écrit rien. Les actions couvrent les mots-clés, les concurrents, les apps, les liens de partage et les réponses aux avis (dès Pro) et, sur Studio, le texte de la fiche sur une version App Store modifiable, ainsi que la pause, la reprise et le budget quotidien Apple Ads. La liste complète se trouve dans la référence.
  • Les scopes d'écriture s'activent un par un. Chaque écriture demande son scope (track:write, reports:write, reviews:write, ads:write, listing:write) ; ils sont décochés à la création d'une clé. La facturation reste dans les réglages de votre compte.
  • Vérifiez la date et l’état de l’observation. Une réponse peut contenir une mesure conservée, une absence de données vérifiée, un traitement en attente ou une erreur. Répéter la requête ne rend pas une ancienne observation plus récente.
  • La couche revenus a ses propres scopes. Les dix endpoints de croissance (revenue, subscriptions, funnel, pricing, change-impact, campaigns, ads-keywords, ads-search-terms, ads-commands, search-popularity) répondent à une clé créée avec les scopes sensibles revenue:read / ads:read : une clé n'ouvre les données de revenus que si vous le choisissez. GA4 se trouve dans le tableau de bord.
  • L'historique suit le plan. history et charts utilisent tous deux la fenêtre du plan.

Erreurs

StatuterrorQuand
401missing_api_keyAucune clé dans la requête.
401invalid_api_keyLa clé est inconnue ou a été révoquée.
401account_deletedLe compte associé à la clé n'existe plus.
403plan_requiredLe plan n'inclut pas l'accès à l'API.
405method_not_allowedLes lectures sont en GET ; POST est accepté sur /v1/actions, /v1/actions/confirm et /v1/apps/{id}/validate-listing (le brouillon passe dans le corps).
400unknown_actionCe nom d'action ne figure pas au catalogue ; la réponse liste ceux qui y figurent.
400invalid_argumentsUn argument manque ou est mal formé ; la réponse nomme le champ.
409confirm_token_expiredLe jeton a plus de 10 minutes. Relancez la prévisualisation.
409confirm_token_mismatchLa cible a changé après la prévisualisation ; la réponse porte le nouveau diff.
403write_limit_reachedL'écriture sort des garde-fous (pas de budget, nombre d'actions par jour).
403test_key_read_onlyLes clés de test n'écrivent jamais.
404job_not_foundAucun job avec cet id dans cet espace de travail.
403workspace_suspendedL'espace de travail est suspendu ; le support peut en donner la raison.
403ip_list_requiredCet espace de travail exige une liste d'IP autorisées sur chaque clé.
404not_foundCet id d'app n'appartient pas à ce compte.
404unknown_endpointCe chemin n'existe pas sous /v1.
402credits_exhaustedLes crédits du mois sont épuisés ; la réponse renvoie vers le pack de crédits.
429rate_limitedTrop de requêtes pour cette clé ; attendez le nombre de secondes indiqué par Retry-After.
429daily_hive_limitL'allocation Hive du jour pour ce plan est épuisée ; remise à zéro à 00:00 UTC.
404not_measuredAucune observation vérifiée n’est disponible pour l’application, le mot-clé ou le périmètre demandé. Une donnée absente ne vaut pas zéro. Vérifiez les paramètres et la documentation liée pour connaître les actions disponibles.
400bad_query/v1/search attend un q de 1 à 120 caractères.
400bad_id/v1/fetch attend un id exactement tel que /v1/search l'a renvoyé.
403asc_requiredupdate_listing demande une clé App Store Connect connectée.
403asc_roleLa clé App Store Connect doit avoir le rôle Admin ou App Manager pour modifier les métadonnées.
409no_editable_versionAucune version App Store n'est modifiable ; la réponse liste les états des versions actuelles.
404locale_not_foundCette langue de storefront n'est pas sur la version ; la réponse liste celles qui y sont.
409changed_since_previewLa fiche a changé dans App Store Connect après la prévisualisation ; rien n'a été écrit.
422asc_rejectedApp Store Connect a refusé le changement ; son propre message se trouve dans detail.
409in_progressUne écriture sur la même cible est encore en cours.
403ip_not_allowedLa clé a une liste d'IP autorisées et cette requête vient d'ailleurs.
401key_leakedLa clé a été trouvée dans un dépôt public et révoquée automatiquement ; créez-en une nouvelle.

Chaque erreur est un JSON avec un champ error. plan_required renvoie aussi plan, pour qu'un client puisse dire sur quel plan est la clé au lieu de deviner.

Questions fréquentes

Y a-t-il une limite de débit ?

Oui, par clé : un nombre de requêtes par seconde selon le plan (429 avec Retry-After), une allocation mensuelle de crédits visible dans les en-têtes x-credits-*, et une allocation Hive quotidienne. Chaque appel met aussi à jour un compteur d'utilisation sur la clé : vous voyez dans les réglages si une ancienne clé sert encore.

Puis-je l'utiliser avec le plan gratuit ?

Les clés live pour l'API commencent avec Pro. Le bac à sable sans clé et les clés de test fonctionnent sur tous les plans, le serveur MCP distant commence avec Pro, les outils gratuits de ce site ne demandent aucun compte, et le plan gratuit mesure une app chaque jour.

API ou serveur MCP ?

Un script veut l'API : formats fixes, un appel, aucun modèle dans la boucle. Un assistant veut le serveur MCP, parce que les outils portent leurs propres descriptions et qu'il peut choisir le bon appel sans que vous écriviez l'intégration. Les deux travaillent sur les mêmes mesures, et les deux écrivent via la même étape de prévisualisation puis confirmation.

Vérifiez-le pour votre propre app

Collez le lien de votre app et ajoutez vos mots-clés. Position, apps au-dessus de vous et demande sont mesurées chaque jour.

Offre gratuite : 1 app, 10 mots-clés dans chacun des 2 storefronts, 14 jours d'historique, sans carte ni date de fin. Pro coûte 29 $/mois.

Commencer gratuitement →
Groupes de concurrents · les termes que vous partagez avec un concurrent et ceux qu'il est seul à avoir

À lire ensuite