Michael JohnsonQuand une équipe cherche un thème pour sa prochaine campagne, parcourir manuellement des dizaines de profils se transforme vite en une série de notes sans méthode commune. Un analyste consigne les vues, un autre les légendes des vidéos, et des publications aux formulations similaires se retrouvent dans des tableaux différents. Une semaine plus tard, il est difficile de savoir ce qui revient le plus souvent : un thème, un format de présentation ou simplement une vidéo qui a bien marché.
Une approche pratique consiste à tenir une courte liste de comptes publics, à récupérer régulièrement des informations structurées sur leurs vidéos et à conserver chaque collecte comme un instantané distinct. Il devient alors possible de comparer les publications et les métriques disponibles au fil du temps, en utilisant un modèle de langage pour regrouper les légendes à titre préliminaire. Voici le schéma d’un tel pipeline de recherche en Python avec TikTok Scraper API de jsonscraper.
Formulez la question avant de collecter les données
Imaginons l’équipe marketing d’une petite marque de nutrition sportive. Elle veut savoir quels thèmes reviennent régulièrement chez les créateurs TikTok publics qu’elle a sélectionnés et quelles vidéos méritent un examen manuel. L’objectif est de comparer les publications de comptes choisis à l’avance pendant une période d’observation, et non d’établir un classement universel de la popularité sur TikTok.
Cette question définit le périmètre de l’analyse. Collecter le flux des profils sélectionnés permet d’étudier le contenu et la fréquence de publication de ces comptes. Les compteurs publics disponibles peuvent être enregistrés au moment de la requête. Pour évaluer les résultats de vos propres publicités, il faudra des données distinctes, comme les dépenses et les conversions provenant de la plateforme publicitaire ou de l’outil d’analyse Web.
Avant de connecter l’API, consignez le protocole de recherche : liste des comptes, date de début, fréquence de collecte, champs à analyser et critères d’inclusion des publications. Notez l’heure de chaque requête. Vous pourrez ainsi distinguer l’évolution d’une métrique pour une vidéo donnée des différences entre deux ensembles d’observations.
Que collecter et que mesurer
Un petit projet nécessite trois couches de données. La première contient l’identifiant du compte et l’heure de lancement de la collecte. La deuxième conserve la réponse brute de l’API pour vérification ultérieure. La troisième regroupe les champs normalisés utiles aux requêtes et aux rapports : identifiant de la vidéo, légende, date de publication et compteurs d’interactions disponibles.
Les noms des champs et la structure imbriquée doivent être déterminés à partir d’un exemple concret de la route utilisée. Ne partez pas du principe que la liste s’appelle toujours videos ou que le compteur de vues porte le nom views. Commencez par exécuter une requête documentée et examiner le JSON effectivement renvoyé, puis configurez la conversion vers votre propre schéma.
Parmi les indicateurs utiles : le nombre de nouvelles publications par intervalle, la répartition des publications par thème et l’évolution des compteurs publics entre les instantanés d’une même vidéo. Pour ce dernier indicateur, comparez les enregistrements ayant le même identifiant vidéo. L’évolution d’une vidéo déjà publiée reste ainsi distincte des métriques des nouvelles publications.
Connecter TikTok Scraper API
La présentation de TikTok Scraper API indique l’adresse de base https:\/\/tiktok.evelode.com, et la documentation des routes confirme GET \/getUserFeed ainsi que les paramètres query, max_cursor, count, region, with_pinned_posts, sort_type et cache_timeout. Pour la première requête, il suffit de renseigner le profil dans query et, par exemple, le nombre d’éléments avec count. La clé license_key est transmise dans la chaîne de requête ; son paramétrage est également décrit dans la documentation de l’API. La collection Postman permet de vérifier le point de terminaison et d’examiner la réponse avant l’intégration.
Conservez la clé dans une variable d’environnement. Ne l’ajoutez ni au code source, ni au dépôt, ni à un tableur, ni à une application cliente. Exécutez la requête, enregistrez un exemple JSON réussi avec la date et le nom de la route, puis utilisez-le comme base pour l’adaptateur de normalisation et les tests.
Une requête Python minimale opérationnelle
La documentation indique que la réponse du flux utilisateur contient un statut externe et un objet tiktok, avec la liste des publications dans aweme_list. Les enregistrements peuvent contenir un identifiant, une légende, une date de publication, un auteur et des statistiques. Vérifiez les champs et les valeurs concrets dans la réponse reçue : certaines données peuvent être absentes.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
ENDPOINT_URL = "https:\/\/tiktok.evelode.com\/getUserFeed"
def fetch_user_feed(handle: str, count: int = 20) -> dict:
response = requests.get(
ENDPOINT_URL,
params={
"license_key": API_KEY,
"query": handle,
"count": count,
"region": "US",
},
timeout=45,
)
response.raise_for_status()
payload = response.json()
if not isinstance(payload, dict):
raise ValueError("Un objet JSON était attendu")
if payload.get("status") != "ok":
raise RuntimeError(f"Statut renvoyé par l’API : {payload.get('status')!r}")
tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
raise ValueError("L’objet tiktok est absent de la réponse")
return payload
def save_raw(payload: dict, account: str, output_dir: str = "data\/raw") -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_account = "".join(c for c in account if c.isalnum() or c in "-_@")
path = Path(output_dir) \/ f"{safe_account}_{collected_at.replace(':', '-')}.json"
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(
json.dumps(
{"collected_at": collected_at, "account": account, "payload": payload},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return path
def normalize_items(payload: dict, account: str, collected_at: str) -> list:
items = payload["tiktok"].get("aweme_list", [])
if not isinstance(items, list):
raise ValueError("Le champ tiktok.aweme_list n’est pas une liste")
observations = []
for item in items:
if not isinstance(item, dict):
continue
stats = item.get("statistics")
stats = stats if isinstance(stats, dict) else {}
author = item.get("author")
author = author if isinstance(author, dict) else {}
observations.append({
"account_handle": account,
"collected_at": collected_at,
"video_id": item.get("aweme_id"),
"caption": item.get("desc"),
"published_at_epoch": item.get("create_time"),
"author_handle": author.get("unique_id"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
})
return observations
if __name__ == "__main__":
account = "creator_handle"
payload = fetch_user_feed(account, count=20)
collected_at = datetime.now(timezone.utc).isoformat()
raw_path = save_raw(payload, account)
observations = normalize_items(payload, account, collected_at)
print(f"Enregistré : {raw_path} ; enregistrements : {len(observations)}")Avant de lancer le script, définissez JSONSCRAPER_TIKTOK_LICENSE_KEY dans l’environnement et installez la bibliothèque requests. Le code vérifie la réponse HTTP, le statut externe et la présence de l’objet tiktok, puis lit aweme_list. Il conserve le JSON brut et extrait les champs confirmés par la documentation, en laissant vides les valeurs manquantes. Le flux obtenu correspond à l’ensemble de résultats renvoyé par l’API ; le rapport doit donc être associé à l’heure de la requête et au profil sélectionné.
Conservez des instantanés et comparez les publications
SQLite ou PostgreSQL conviennent à un petit projet. Conservez la réponse brute séparément des enregistrements normalisés. Voici un schéma possible pour la table d’observations :
CREATE TABLE IF NOT EXISTS video_observations (
account_handle TEXT NOT NULL,
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
published_at_epoch INTEGER,
caption TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
raw_file TEXT,
PRIMARY KEY (account_handle, video_id, collected_at)
);Chaque exécution ajoute un nouvel instantané sans écraser les précédents. Lors de la comparaison des compteurs, calculez l’écart uniquement lorsque les deux valeurs existent pour une même vidéo. Indiquez dans le rapport l’intervalle entre les requêtes et l’heure d’observation : ils précisent sur quelle période l’évolution s’est produite.
Pour regrouper les thèmes, commencez par un petit vocabulaire de catégories, puis ajoutez au besoin un classificateur ou un modèle de langage. Fournissez au modèle des légendes nettoyées, les identifiants des publications et des catégories définies à l’avance. Un résultat structuré comprenant une catégorie et une brève justification est plus facile à comparer entre exécutions qu’une synthèse libre.
Ajoutez un modèle de langage avec une annotation vérifiable
Un modèle peut répartir à titre préliminaire les légendes entre des thèmes comme « recettes », « entraînements », « avis sur des produits » et « histoires personnelles ». Pour commencer, annotez manuellement quelques dizaines de publications. Comparez les étiquettes automatiques à ces exemples, précisez les définitions des catégories et recommencez l’évaluation après toute modification de l’invite ou du modèle.
Il est plus fiable de calculer en code ordinaire le nombre de nouvelles publications, la médiane des compteurs et l’écart entre les instantanés. Utilisez le modèle pour classer les textes et préparer de brèves explications. Gardez les légendes d’origine et les observations numériques accessibles pour vérification.
Avec chaque étiquette, conservez l’identifiant de la publication, la version de l’invite, la date de traitement et le modèle utilisé. En cas d’erreur de classification, l’analyste pourra retrouver la légende et corriger la règle. Il est utile de conserver séparément l’étiquette initiale et la correction manuelle.
Automatisez l’exécution
Une fois l’exécution manuelle vérifiée, déplacez le script vers cron, GitHub Actions, n8n ou Make. Le planificateur lance la collecte selon un calendrier, transmet la liste des comptes, consigne le résultat et envoie le rapport vers le stockage choisi. Conservez la clé dans les secrets de l’environnement d’exécution. Testez d’abord le processus sur un compte, puis élargissez la liste.
Divisez l’automatisation en étapes : file d’attente des comptes, appel à l’API, conservation de la réponse brute, normalisation, enregistrement de l’instantané et préparation du rapport. Une erreur sur un compte ne doit pas effacer les résultats des autres. L’identifiant d’exécution et les contraintes d’unicité de la base permettent de rendre les relances idempotentes.
Consignez l’heure, le compte, la route, le statut HTTP, la durée, le nombre d’éléments traités et la description de l’erreur. N’inscrivez pas la clé API dans les journaux. Le paramètre cache_timeout est indiqué pour \/getUserFeed ; ajoutez-le à la requête si vous avez besoin d’une durée de mise en cache définie. La documentation de l’API indique une valeur par défaut de 3 600 secondes.
Vérifiez la qualité avant de publier le rapport
Comparez plusieurs enregistrements normalisés avec le JSON d’origine. Vérifiez qu’une collecte répétée reconnaît la même vidéo grâce à son identifiant, que les dates sont interprétées comme prévu, que les champs numériques ont le type adéquat et que la proportion de valeurs manquantes est connue. Relancez ensuite le processus et assurez-vous que la base a conservé les anciennes observations et ajouté les nouvelles.
Ne mélangez pas les comptes ni les périodes de collecte. Pour comparer les thèmes, utilisez des périodes de même durée ou indiquez clairement leur durée dans le rapport. Pour suivre l’évolution des compteurs, consignez l’intervalle entre les instantanés afin que le lecteur comprenne l’échelle des périodes comparées.
Conservez le texte d’origine de la légende et créez une version nettoyée distincte. Les émojis, hashtags, liens et particularités linguistiques peuvent influer sur la classification ; des champs distincts aideront à vérifier l’effet du nettoyage et à recalculer les catégories sans nouvelle requête à l’API.
Quels résultats attendre du pipeline
Après plusieurs cycles, l’équipe disposera d’un tableau de publications et d’instantanés, d’un regroupement préliminaire des légendes par thème et d’un rapport sur les nouvelles vidéos de la période choisie. Cela aide à sélectionner des vidéos pour un examen par des spécialistes, à repérer les thèmes récurrents dans les comptes sélectionnés et à vérifier l’évolution des compteurs publics entre les dates d’observation.
Ces données permettent de formuler des hypothèses pour le calendrier éditorial : comparer différentes manières de présenter une même question ou dégager des thèmes à tester dans votre propre contenu. Pour évaluer l’effet commercial, mettez ces observations en regard des données internes des campagnes.
Pour commencer, choisissez une courte liste de comptes publics et testez GET \/getUserFeed dans la collection de requêtes Postman. N’intégrez au code que les paramètres et chemins de champs confirmés par la documentation de la route et par sa réponse réelle.
Collecte responsable de données publiques
Limitez la liste des comptes à l’objectif de recherche, collectez uniquement les champs nécessaires et définissez une durée de conservation des réponses brutes. Avant toute utilisation commerciale des données, vérifiez les conditions applicables de la plateforme et les exigences relatives aux données personnelles dans votre juridiction. Le contrôle des accès et la suppression des instantanés obsolètes contribuent à maintenir le processus dans les limites de l’objectif.
Avant d’envoyer des données à un service d’IA, supprimez les champs dont le modèle n’a pas besoin. Dans le rapport, indiquez l’identifiant de la publication et la date d’observation afin qu’un membre de l’équipe puisse retrouver l’enregistrement et vérifier le fondement de la conclusion.
Liste de contrôle pour le lancement
- Définissez la niche, la liste des comptes, la période et les questions d’analyse.
- Vérifiez les paramètres de
GET \/getUserFeeddans la documentation et la réponse réelle dans Postman. - Enregistrez un exemple JSON et configurez le normaliseur à partir des champs confirmés.
- Conservez la réponse brute et des instantanés distincts horodatés.
- Calculez les indicateurs numériques en code ; utilisez l’IA pour regrouper les textes à titre préliminaire.
- Ajoutez un calendrier, la journalisation, la gestion des nouvelles tentatives et une durée de conservation.
Le suivi devient ainsi une étude reproductible : chaque conclusion est liée à une publication et à une heure d’observation, et le code s’appuie sur le schéma réel de la route choisie.