Michael JohnsonAprès le lancement d’une campagne, une équipe peut vouloir vérifier quelles vidéos publiques apparaissent dans les résultats de recherche pour certains mots. Une recherche manuelle est difficile à reproduire et à comparer quelques jours plus tard. Un petit collecteur peut exécuter les mêmes requêtes selon un calendrier et archiver les réponses avec la date et l’expression recherchée, afin qu’un analyste puisse examiner les entrées et préparer son propre récapitulatif.
Ce guide présente un pipeline d’archivage en Python pour conserver les résultats de recherche associés à des expressions fixes. Contrairement au suivi de hashtags ou de comptes individuels, la clé de la comparaison consiste ici à répéter les mêmes expressions de recherche et à conserver un instantané distinct de chaque réponse. La page de l’API TikTok Scraper de jsonscraper indique l’adresse de base et la route GET /searchVideo ; dans la documentation de cette route, l’expression de recherche est transmise dans le paramètre obligatoire keyword.
Objectif et limites de la mesure
Imaginons qu’un spécialiste du marketing souhaite collecter chaque jour les résultats pour plusieurs expressions fixes : le nom d’un produit, une catégorie et la formulation d’un problème client. Pour chaque requête, le système conserve l’heure de collecte et la réponse de l’API. Après vérification d’un exemple de réponse, il est possible d’ajouter la normalisation des champs réellement présents dans le JSON, comme l’identifiant d’une vidéo ou des compteurs publics, s’ils y figurent.
L’archive répond à une question précise : quelles entrées la recherche associée à l’expression enregistrée a-t-elle renvoyées lors de cette exécution ? Si la réponse contient des métriques, des observations répétées peuvent montrer l’écart entre les valeurs relevées à différents moments. Cet écart concerne les instantanés observés et l’intervalle qui les sépare ; pour les comparer, conservez les deux heures de collecte et le même champ.
Conservez la requête avec la réponse. La composition des résultats dépend d’une expression de recherche donnée et du moment de la collecte. L’archive est donc utile pour suivre les résultats associés aux requêtes choisies, et non pour obtenir un aperçu complet de l’ensemble du contenu TikTok. Les identifiants, les réponses brutes et les horodatages aident à vérifier l’origine de chaque ligne du tableau qui sera créé par la suite.
Vérifiez la route et ses paramètres
La carte des routes de l’API TikTok indique l’adresse de base https://tiktok.evelode.com et la route GET /searchVideo. La spécification actuelle de l’API désigne keyword comme paramètre de recherche obligatoire ; les paramètres facultatifs comprennent cursor, count, cache_timeout, date_posted, sort_by et region. L’authentification utilise license_key. La route est également décrite dans la documentation du SDK Python.
Les paramètres count et date_posted permettent de définir la taille de la réponse et un filtre temporel ; sort_by accepte les valeurs documentées most-liked, relevance ou date-posted. Si vous utilisez la pagination, transmettez la valeur de cursor reçue dans la réponse précédente comme une valeur opaque, sans essayer de la calculer vous-même. Pour obtenir une archive quotidienne comparable, conservez les paramètres de la requête et la version de votre code à côté des données.
L’exemple ci-dessous utilise une valeur faible pour count lors d’un test et fixe la région à US. Avant la collecte quotidienne, vérifiez une requête, son statut HTTP et la structure du JSON. Le schéma de réponse peut contenir les vidéos trouvées dans tiktok.aweme_list ou dans tiktok.search_item_list, où l’objet vidéo se trouve dans aweme_info ; le code prend en charge ces deux formes observées.
Préparez le projet
Créez un environnement virtuel et installez requests :
python -m venv .venv
source .venv/bin/activate
pip install requestsDans PowerShell, activez l’environnement avec la commande .venv\Scripts\Activate.ps1. Définissez la clé et la liste des expressions de recherche au moyen de variables d’environnement. Pour l’API TikTok, utilisez le nom de variable documenté JSONSCRAPER_TIKTOK_LICENSE_KEY :
export JSONSCRAPER_TIKTOK_LICENSE_KEY="votre_clé"
export TIKTOK_QUERIES="nom du produit,catégorie de produit,problème du client"Collectez et enregistrez les instantanés
L’exemple envoie une requête pour chaque expression à la route documentée, puis enregistre le JSON brut, l’heure de collecte et les paramètres utilisés. Le nom du fichier comprend la date et l’expression recherchée. La clé est stockée dans l’environnement et n’est pas incluse dans l’archive.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("L’API a renvoyé un statut autre que ok")
return payload
def extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Réponse enregistrée pour la requête : {query}")
time.sleep(1)
print(f"Nombre de réponses enregistrées : {len(QUERIES)}")Ce collecteur minimal envoie une requête par expression avec count=10. Pour une collecte plus large, ajoutez la pagination au moyen de cursor : poursuivez les requêtes en transmettant la valeur du curseur reçue dans la réponse, tant que l’API indique qu’il existe d’autres résultats, et enregistrez chaque réponse séparément. Le curseur et le nombre de résultats définissent un passage donné ; le JSON enregistré permet ensuite de vérifier exactement ce que chaque requête a renvoyé.
L’exemple vérifie le status de premier niveau, puis lit l’objet tiktok. Il rassemble les éléments de aweme_list, ainsi que ceux de search_item_list[].aweme_info si cette forme est présente. Les champs disponibles pour une vidéo peuvent inclure un identifiant, une description, un auteur, un lien et des statistiques ; certains champs peuvent être absents. Conservez donc la réponse complète et, lors de la normalisation, vérifiez la présence de chaque champ.
L’intervalle d’une seconde est une pause entre les requêtes du script, et ne constitue pas une affirmation concernant les limites du service. Configurez la fréquence et les nouvelles tentatives en fonction des conditions d’accès et de la documentation. Le paramètre cache_timeout est documenté pour la recherche ; il permet de définir une durée de mise en cache en secondes, et la spécification précise que la valeur 0 désactive la mise en cache. Ajoutez-le à la requête lorsque ce comportement convient à votre cas d’usage.
Ajoutez une normalisation fondée sur la réponse réelle
Après la première exécution, ouvrez le fichier enregistré et examinez la structure de payload. La fonction extract_videos de l’exemple rassemble les éléments provenant de deux emplacements documentés dans les formes de réponse de recherche. Repérez les clés exactes des champs nécessaires à l’analyse. Si un champ est absent d’une entrée donnée, conservez-le comme valeur manquante au lieu d’y substituer un nombre supposé.
Pour la suite du traitement, il est pratique de créer une ligne par objet trouvé et d’y ajouter collected_at et query. Les champs confirmés peuvent être enregistrés dans un fichier CSV ou une base de données, tandis que le JSON brut reste dans l’archive. Cette combinaison facilite la création de tableaux tout en permettant de vérifier l’origine de chaque entrée.
Si l’API renvoie un identifiant de vidéo, utilisez-le pour relier les observations d’une même vidéo entre plusieurs exécutions. Conservez chaque observation séparément, sans écraser les précédentes. En l’absence d’identifiant stable, vérifiez d’abord quels attributs permettent de rapprocher les entrées et ne considérez pas une correspondance du texte de la description comme garantie.
Comparez les instantanés et préparez un rapport
Après la normalisation, regroupez les entrées par identifiant vérifié et triez-les par heure de collecte. Vous pouvez calculer en code ordinaire l’écart entre deux valeurs consécutives pour les champs de type compteur. Par exemple, passer de 12 400 à 18 900 signifie que la valeur du compteur a changé de 6 500 entre ces instantanés. Indiquez les dates des observations et le champ d’origine dans le rapport, afin que le lecteur puisse vérifier le calcul.
Un tableau final utile comprend l’expression de recherche, l’identifiant de publication, l’heure de collecte et les champs choisis dans la réponse. Le récapitulatif peut être regroupé par requête et trié selon un compteur confirmé. L’équipe disposera ainsi d’une liste vérifiable des entrées renvoyées à examiner ; créez le tableau ou le message dans une étape distincte, après avoir étudié le schéma réel.
Commencez par conserver les fichiers JSON en local. Lorsque la collecte devient régulière, transférez les lignes normalisées vers PostgreSQL ou un entrepôt analytique, et les réponses brutes vers un stockage objet, en incluant la date et la requête dans le nom. La conservation des données brutes est particulièrement utile lorsque vous affinez l’analyseur : vous pouvez le réexécuter sur les données historiques sans interroger de nouveau l’API.
Planifiez la collecte
Pour une archive quotidienne, exécutez le script avec cron ou un autre planificateur disponible dans votre environnement. Par exemple, une tâche peut lancer un fichier Python une fois par jour, en lui transmettant la clé et les expressions de recherche par des variables d’environnement. Avant de l’utiliser régulièrement, vérifiez une requête, puis la liste complète, et ne configurez le calendrier qu’ensuite.
Pour assurer la fiabilité de l’exécution, enregistrez le statut de chaque requête, limitez le nombre de nouvelles tentatives en cas d’erreur temporaire et signalez que la collecte est incomplète si une expression échoue. N’incluez pas la clé dans les messages d’erreur. Il est également utile de séparer les fichiers par date et par nom de requête afin qu’une nouvelle exécution n’écrase pas l’instantané précédent.
Choisissez la fréquence en fonction de l’objectif et du volume de requêtes. Pour un aperçu quotidien, une exécution par jour suffit ; une collecte plus fréquente se justifie lorsque l’équipe s’intéresse aux changements au cours de la journée. Commencez par une courte liste d’expressions, vérifiez l’utilité des résultats renvoyés, puis élargissez la collecte dans le respect des conditions d’accès et des règles d’utilisation des données.
Utilisez l’IA pour regrouper les thèmes
Une fois le schéma de réponse confirmé, les champs textuels sélectionnés peuvent être transmis à un modèle afin de regrouper les descriptions selon des thèmes définis à l’avance ou de préparer une première ébauche de récapitulatif. À côté de chaque classification, conservez l’identifiant de publication d’origine, l’expression de recherche et l’extrait de texte qui a servi de base à la catégorie. L’analyste pourra ainsi remonter de la sortie du modèle à l’entrée d’origine.
Calculez les écarts numériques, le tri et la déduplication avec du code ordinaire. Un modèle peut servir au traitement du texte et à la rédaction du rapport, tandis que les compteurs et les horodatages proviennent des réponses enregistrées. Cette séparation permet de comprendre l’origine de chaque conclusion.
Vérifiez manuellement une partie des catégories automatisées et conservez les corrections comme exemples de test. Si des types de publications différents se retrouvent régulièrement dans le même groupe, précisez les définitions des catégories et recommencez la vérification. Ce processus aide à évaluer la qualité de la classification au regard des données de votre tâche.
En résumé : une archive reproductible et un récapitulatif vérifiable
Après avoir exécuté la requête documentée avec le paramètre keyword, l’équipe dispose d’une archive indiquant quelles expressions ont été utilisées, à quel moment et quelles données l’API a renvoyées pour chacune. Cette archive permet de créer un tableau de résultats, de comparer les champs confirmés entre les instantanés et de préparer une liste de publications trouvées pour une analyse manuelle.
Commencez par une requête de test, puis configurez la liste d’expressions et le calendrier. La présentation de l’API TikTok Scraper fournit l’adresse de base et la carte des routes ; les paramètres de /searchVideo et la forme de la réponse sont décrits dans la spécification de l’API. L’archivage des réponses vérifiées constitue une base pour une analyse reproductible à partir d’expressions de recherche fixes.