Michael JohnsonUne équipe marketing remarque l’apparition sur TikTok de vidéos consacrées à un nouveau produit, mais vérifier plusieurs hashtags chaque jour manuellement est fastidieux. Pour comparer les publications et leurs indicateurs visibles au fil du temps, il faut une collecte reproductible, avec horodatage, archivage des réponses d’origine et contrôle des modifications.
Pour ce prototype, l’API TikTok Scraper de jsonscraper convient : sa page produit répertorie des routes pour les hashtags, les utilisateurs, les vidéos et la recherche. La première étape consiste à vérifier la route souhaitée et le format de la réponse dans Postman, puis à transposer la configuration confirmée en Python. On peut ainsi mettre en place un processus reproductible qui n’extrait que les champs réellement présents dans la réponse.
Objectif : observer l’évolution, pas une seule vidéo populaire
Une publication qui cumule beaucoup de vues peut attirer l’attention, mais pour planifier une campagne, il est plus utile de savoir combien de nouvelles vidéos sont trouvées sur un sujet et comment évoluent les indicateurs publics des publications déjà repérées. Par exemple, un magasin en ligne d’articles de sport peut vouloir évaluer le flux de vidéos consacrées à un type d’entraînement précis avant de préparer des créations publicitaires à ce sujet.
Les vérifications manuelles compliquent les comparaisons : les résultats varient, les indicateurs augmentent et les employés peuvent les noter dans des formats différents. En enregistrant un instantané à chaque exécution, accompagné de l’heure de collecte et du JSON d’origine, l’équipe constitue un historique de ses observations et peut retraiter les données si le schéma d’analyse évolue.
L’automatisation comprend plusieurs étapes : vérifier la route et les paramètres, demander les données selon un calendrier, enregistrer la réponse, en confirmer la structure, puis extraire les champs nécessaires. Le tableau obtenu peut servir à produire des graphiques, à classer les sujets ou à rédiger un rapport.
Ce que confirme la documentation de l’API
La page de l’API TikTok Scraper indique l’adresse de base https://tiktok.evelode.com et répertorie les routes de la catégorie Hashtag : GET /getHashtagInfo, GET /getHashtagFeed et GET /getHashtagFeedByID. La page montre également un exemple de requête vers une autre route avec le paramètre license_key et explique comment configurer la clé dans une collection Postman.
Pour GET /getHashtagFeed, la spécification officielle des routes indique le paramètre obligatoire query (URL du hashtag ou nom du tag), ainsi que les paramètres facultatifs cursor, count, region et cache_timeout. La réponse du fil doit contenir un tableau tiktok.aweme_list ; les champs répertoriés pour un élément comprennent aweme_id, desc, create_time, share_url, des données sur l’auteur et statistics. Certains champs peuvent être absents : vérifiez donc le JSON réellement renvoyé avant de le traiter.
La collection jsonscraper dans Postman permet d’effectuer facilement une requête de test, de vérifier la réponse réelle et d’obtenir un exemple de test pour la vérification ultérieure du code. L’autorisation s’effectue au moyen de license_key ; stockez la clé dans une variable d’environnement et ne l’affichez pas dans les journaux.
Commencez par vérifier la requête dans Postman
Commencez par un hashtag de test. Dans la collection, sélectionnez la route du fil de hashtags, définissez license_key de la manière indiquée dans la documentation et transmettez le nom du tag dans query. Au besoin, ajoutez count et le code pays dans region. Exécutez la requête et vérifiez le statut HTTP, le champ de premier niveau status et le contenu de tiktok.aweme_list.
Enregistrez la réponse réussie dans un fichier JSON de test. Utilisez-le pour vérifier la présence de l’identifiant de publication, de la description, de la date de publication, du lien et des statistiques. N’intégrez un champ au schéma d’analyse qu’après avoir confirmé qu’il est renvoyé avec le type attendu.
Stockez la clé API dans une variable d’environnement, et non dans le fichier source. Si la clé est transmise dans l’URL, masquez-la lors de la journalisation des requêtes afin que l’adresse complète ne figure pas dans les journaux.
Client Python pour envoyer la requête et archiver les réponses
La route et les noms des paramètres ci-dessous correspondent à la spécification publiée : pour un hashtag, on utilise query, et l’autorisation est transmise par license_key. Cet exemple est compatible avec Python 3.8+ et enregistre la réponse d’origine avec les métadonnées de l’exécution.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("L’API a renvoyé un statut différent de ok")
return payload
def archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#exemplethème"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"Archive enregistrée : {saved_path}")
Avant de lancer le script, définissez la variable d’environnement JSONSCRAPER_TIKTOK_LICENSE_KEY. La requête utilise le paramètre confirmé query et limite le nombre d’éléments demandés avec count. La réponse fait l’objet d’une vérification du statut HTTP et du statut JSON ; l’archive conserve les données réelles en vue de leur traitement ultérieur. Testez l’exécution avec un seul hashtag avant d’ajouter un calendrier et des analyses.
Ajouter une normalisation sans hypothèses fragiles
La documentation indique que la réponse du fil contient le tableau tiktok.aweme_list. Avant la transformation, vérifiez que tiktok est un objet et que aweme_list est une liste. Pour chaque élément, extrayez uniquement les champs confirmés, par exemple aweme_id, desc, create_time, share_url et les valeurs de statistics, si elles sont présentes.
Le tableau interne peut contenir le hashtag de la requête, l’heure de collecte, l’identifiant vidéo et les métriques choisies. Pour une métrique facultative ou absente, conservez une valeur vide : une métrique manquante n’équivaut pas à une valeur mesurée égale à zéro. Stockez les réponses d’origine séparément afin de pouvoir reconstruire le tableau sans effectuer une nouvelle requête.
Si le format de la réponse évolue, la validation des types doit interrompre le traitement incorrect et générer un message de diagnostic. Conservez le JSON de test à côté du test de l’analyseur : il permettra de vérifier que la nouvelle version du code traite toujours correctement le schéma connu.
Métriques fondées sur des observations répétées
Si la réponse fournit des compteurs, enregistrez chaque observation avec un horodatage. Pour une même publication, comparez les valeurs de deux exécutions et calculez l’évolution observée pendant l’intervalle. Pour les faire correspondre, utilisez aweme_id, indiqué dans la spécification, et vérifiez sa présence dans chaque élément.
Vous pouvez compter chaque jour les publications détectées pour la première fois à partir des résultats de vos exécutions. Cette métrique décrit le flux renvoyé par des requêtes précises, avec des paramètres et un calendrier définis. Elle permet de comparer vos propres instantanés si la méthode de collecte reste cohérente.
Un rapport minimal peut présenter le nombre de nouvelles publications détectées par jour, la répartition des compteurs disponibles et l’évolution des valeurs pour les vidéos retrouvées. Ajoutez l’heure de la requête et le nom du fichier d’origine afin que l’analyste puisse vérifier la provenance de chaque enregistrement.
Planification et gestion des erreurs
Une fois la requête et l’analyse vérifiées, exécutez le script selon un calendrier, par exemple avec cron, GitHub Actions ou un orchestrateur de données. Placez la liste des hashtags dans une configuration distincte afin de pouvoir ajouter ou supprimer des sujets sans modifier la logique du client.
Pour les exécutions automatisées, définissez un délai d’attente, un nombre limité de nouvelles tentatives en cas d’erreurs réseau temporaires et consignez le statut HTTP ainsi que la durée de la requête. N’inscrivez pas la clé dans les journaux. En cas d’échec de l’analyse, conservez des informations de diagnostic sans données sensibles et avertissez la personne responsable.
La spécification prend en charge la pagination de la route du fil de hashtags au moyen du paramètre cursor. Si vous en avez besoin, conservez le curseur renvoyé par la réponse et transmettez-le sans le modifier à la requête suivante ; ne traitez que les résultats renvoyés et surveillez has_more, si ce champ est présent. Si les requêtes portant sur plusieurs hashtags renvoient la même publication, choisissez une clé de déduplication adaptée à l’objectif : compter la publication séparément pour chaque hashtag ou ne compter que les vidéos uniques.
Classification et automatisation des rapports
Une fois les lignes vérifiées obtenues, vous pouvez classer les descriptions des vidéos par thème : le champ desc figure dans le schéma des éléments. Un modèle peut regrouper les publications par format, par exemple les tutoriels, les critiques ou les retours d’expérience. Conservez le texte d’origine, l’étiquette, la version de l’instruction et le résultat, et soumettez les cas incertains à une vérification humaine.
Calculez les indicateurs numériques avec du code classique afin que les exécutions répétées produisent des résultats arithmétiques reproductibles. Un classificateur est utile pour traiter le texte ; le rapport final doit relier ses conclusions à des lignes et à des dates d’observation précises.
Dans un scénario sans code, vous pouvez relier les mêmes étapes dans un outil d’automatisation : planification, requête HTTP fondée sur une configuration vérifiée, validation de la réponse, enregistrement du JSON, transformation des champs confirmés et notification des erreurs. Vérifiez d’abord le contrat dans Postman, puis transposez-le en Python, dans n8n ou dans Make.
Résultat attendu et prochaine étape
Une fois le système configuré, l’équipe disposera d’une archive des réponses de l’API et d’un tableau d’observations pour les hashtags choisis. Ils permettront de repérer de nouvelles publications, de comparer les indicateurs disponibles au fil du temps et de sélectionner des contenus à analyser plus en détail. Pour obtenir des résultats comparables, conservez un calendrier, des paramètres de requête et des règles de normalisation uniformes.
Commencez par une seule route et une réponse réelle : exécutez la requête /getHashtagFeed avec le paramètre query, enregistrez le JSON, puis ajoutez l’analyse des champs et la planification. La page de l’API TikTok Scraper présente l’adresse de base et la liste des routes, tandis que la spécification des routes fournit les noms des paramètres nécessaires à l’implémentation du client.