Mesures

Les mesures d’une marque sont les chiffres de sa page d’accueil Skoup, sur un marché et une période : sa visibilité dans les réponses IA (part de rayon, avec un intervalle de confiance à 95 %, la variation hebdo et la position moyenne), l’exactitude de ce que les assistants disent de ses prix et de ses stocks, son score de readiness et son score de perception. Elles sont lues avec le même code que les écrans : une valeur de l’API ne contredit jamais l’app.

Les mesures viennent des samplings hebdomadaires, chaque lundi à 02:00 UTC. La période (30d, 90d — par défaut — ou 12m) est la fenêtre de samplings sur laquelle les chiffres sont calculés.

Je veux…

Je veux…	Appel
Lire les chiffres d’une marque sur son marché principal	`GET /v1/brands/{brand}/metrics`
Les lire sur un autre marché, sur un an	`GET /v1/brands/{brand}/metrics?market=US&period=12m`
Voir comment les IA perçoivent un produit	`GET /v1/brands/{brand}/products/{product}/perception`
Savoir quand de nouveaux chiffres sont disponibles	Écouter `sampling.completed`

Scope : metrics:read.

Scénario : un dashboard Looker rafraîchi chaque lundi

Écoutez sampling.completed. Quand un sampling hebdo complet arrive (data.object.query vaut null — un re-sampling ciblé porte sa requête), récupérez les mesures et l’attribution du marché et écrivez-les dans votre entrepôt.


curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/metrics?market=FR&period=90d" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
 
curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/attribution?market=FR&period=90d" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Pièges

null n’est pas zéro. Un bloc vaut null tant que rien n’a été mesuré (aucun sampling sur le marché, aucun audit, aucune perception jugée). Une part de 0 est une vraie mesure : la marque n’a jamais été citée.
Comparez ce qui est comparable. Une part sur 30 jours et une part sur 12 mois portent sur des fenêtres différentes ; stockez la period avec le chiffre.
La perception suit les écarts ignorés. Quand l’équipe ignore un écart dans Skoup (un faux positif du juge), ses verdicts sortent du score de perception, dans l’app comme dans l’API ; le score peut donc bouger sans nouveau sampling.
Un market inconnu répond 422 parameter_invalid avec param: "market".