# Gardez comparables les recherches de mots-clés TikTok entre groupes de requêtes

Comparez équitablement les échantillons de recherche de mots-clés TikTok. Fixez des budgets de collecte, suivez la provenance des requêtes et enregistrez l'état d'arrêt de chaque terme. Un Actor est un programme hébergé de collecte de données. Une Task est un préréglage d'entrée enregistré. L'Actor collecte les lignes sources, et vous faites l'analyse.

## Préparez votre plan de collecte

L'entrée publique enregistrée de la Task utilise trois requêtes d'exemple, `expandQueries` réglé sur false, un plafond partagé `maxResults` de 150 vidéos distinctes, `resultsPerQuery` réglé sur 50, `maxPagesPerQuery` réglé sur 1 et `searchDistribution` réglé sur "balanced". Remplacez ces requêtes d'exemple par vos termes cibles avant de lancer un panel complet.

Pour vérifier votre configuration sous le build public Search 1.1.5, commencez par une exécution pilote bornée. Remplacez la liste de requêtes d'exemple par un seul terme prévu. Réglez `expandQueries` sur false, `maxExpandedQueries` sur 0, `maxResults` sur 2, `resultsPerQuery` sur 2, `maxPagesPerQuery` sur 1 et `searchDistribution` sur "balanced".

Un contrôle de référence avec "python tutorial" a renvoyé deux lignes de métadonnées, avec des identifiants de publication, des URL de publication, des identifiants d'auteur, des handles, des dates de publication en mai et en août, et une raison d'arrêt OUTPUT égale à `max_results_reached`. Ce pilote confirme les champs de recherche de base et la provenance, mais ce n'est ni un référentiel de tendance à plusieurs requêtes, ni un test de campagne publicitaire.

## Champs natifs du jeu de données et preuves d'exécution

Les enregistrements natifs du jeu de données comprennent `postId`, `postUrl`, `authorId`, `profileHandle`, `publishedAt` et `observedAt`. Les champs de provenance de la recherche suivent le contexte de la requête : `rootQuery` est la famille d'origine, `query` est le terme de recherche exécuté, et `querySource` identifie l'origine de ce terme. Les champs `pageIndex` et `pageRank` enregistrent la position sur la page source collectée. Les champs `status` et `statusReason` indiquent les états de résultat au niveau de l'élément. Les champs facultatifs restent null s'ils manquent dans la source.

L'objet `OUTPUT` fournit des preuves d'exécution, et non une correspondance automatique des requêtes. Les champs clés comprennent :

- `queriesSearched` : tableau des termes réellement exécutés.
- `queryPlans` : liste planifiée des définitions de requête, de racine et de source.
- `effectiveResultsPerQuery` : limite abaissée de vidéos enregistrées par terme, calculée pendant la distribution équilibrée.
- `rowsSaved` : nombre total de vidéos distinctes écrites dans le jeu de données.
- `duplicatesSkipped` : vidéos candidates omises par la déduplication globale.
- `stopReason` : état d'arrêt global de l'exécution, par exemple `max_results_reached`.
- `sourceStatusCounts` : états sources agrégés, par exemple `{ok: 1}`.
- `status` et `statusReason` : résultat d'exécution de premier niveau, par exemple `status: "ok"` et `statusReason: null`.

Dans l'exécution de contrôle à une seule requête, `OUTPUT` a indiqué `stopReason: "max_results_reached"`, `rowsSaved: 2`, `sourceStatusCounts: {ok: 1}`, `status: "ok"` et `statusReason: null`.

Une fraction utile est le nombre de vidéos à identifiant connu, revues et jugées pertinentes, divisé par l'échantillon candidat comparable et examinable pour ce terme tenté. Les termes en échec ou non tentés n'ont aucune fraction valide.

## Préparez votre plan de collecte

1. Définissez votre question de recherche et vos familles de requêtes avant de chercher. Ne regroupez des termes que lorsqu'ils représentent le même concept, et conservez une liste explicite de requêtes.
2. Fixez le `maxResults` partagé, `resultsPerQuery`, `maxPagesPerQuery`, le choix d'expansion et `searchDistribution`. Désactivez l'expansion lorsque vous comparez une liste fixe exacte. Un `maxResults` partagé sert de plafond total de vidéos enregistrées pour toutes les requêtes, tandis que `resultsPerQuery` plafonne chaque terme.
3. Choisissez la distribution équilibrée lorsque vous avez besoin d'une part planifiée entre les termes. Choisissez la distribution séquentielle seulement si votre objectif est de remplir d'abord les termes antérieurs. La distribution équilibrée peut abaisser `effectiveResultsPerQuery` pour partager la limite totale, mais elle ne garantit ni que les quotas seront remplis, ni que l'allocation inutilisée sera réattribuée.
4. Séparez votre budget planifié de vos données utiles réelles. Enregistrez le statut de tentative, les lignes enregistrées, les identifiants de vidéo connus, les doublons, l'identité manquante et les états d'échec de la source. Zéro ligne utile après un échec de la source indique une disponibilité inconnue, et non un intérêt nul pour le sujet.
5. Préservez la provenance et traitez la déduplication globale avec soin. La provenance consiste à conserver la source enregistrée exacte et l'heure de collecte inscrite dans `observedAt`. La déduplication globale native n'enregistre une vidéo qu'une seule fois, sous la première requête où elle a été observée. Pour capturer chaque apparition dans une requête, conservez des registres d'exécution séparés par requête.
6. Appliquez la même règle manuelle de pertinence à tous les groupes. Distinguez les vidéos candidates des éléments utiles en vérifiant les valeurs exactes de `postId` et de `postUrl`. Calculez les fractions utiles seulement avec les données tentées et utilisables, et traitez les termes en échec ou non tentés comme inconnus.
7. Signalez les lacunes avant de comparer les groupes. Marquez les termes non tentés comme `not_attempted` plutôt que comme zéro, et gardez visibles les plafonds de la source. Ne classez jamais les groupes de requêtes d'après les seuls totaux bruts lorsque les limites de collecte ou les échecs diffèrent.
8. Enregistrez votre plan de requêtes et le registre réel de l'échantillon. Examinez les champs `OUTPUT` tels que `queriesSearched`, `queryPlans`, `rowsSaved`, `duplicatesSkipped` et `stopReason` pour consigner la preuve exacte d'arrêt avant de faire une [analyse de tendance](/fr/articles/reperer-tendances-tiktok-ensemble-fixe-de-sujets/) ou une [analyse de créatifs](/fr/articles/biblioth%C3%A8que-exemples-ugc-tiktok/).

## Registres de collecte fictifs d'origine

Toutes les valeurs ci-dessous sont une fiction originale, créée pour illustrer les budgets de collecte, les états d'arrêt et les limites de la déduplication globale. Elles ne représentent ni des référentiels produit en conditions réelles, ni des résultats de pilote.

Prenons trois termes, A, B et C, avec `maxPagesPerQuery` réglé sur 1, l'expansion désactivée, `maxResults` réglé sur 6 et le `resultsPerQuery` demandé réglé sur 6.

- Exécution équilibrée : le `effectiveResultsPerQuery` indiqué est 2, ce qui crée une limite planifiée de 2 vidéos enregistrées par terme. Si chaque terme renvoie 2 vidéos pertinentes distinctes, le registre montre A=2, B=2, C=2, soit 6 vidéos enregistrées au total. La fraction utile est 2/2 pour chaque terme.
- Exécution séquentielle : la limite configurée par terme est 6 pour les termes A, B et C. Le terme A renvoie 6 vidéos enregistrées et remplit le plafond partagé `maxResults` de 6. Les termes B et C ne sont jamais tentés. Le registre indique un maximum planifié de 6 pour chaque terme, avec A=6 enregistrées, B=0 enregistrée (`not_attempted`) et C=0 enregistrée (`not_attempted`). Noter 0 ligne enregistrée pour B et C relève de la tenue du registre ; la disponibilité de leur échantillon reste inconnue.
- Échec de la source dans l'exécution équilibrée : le terme A enregistre 2 vidéos utiles (fraction 2/2), le terme C enregistre 2 vidéos utiles (fraction 2/2), et le terme B rencontre une erreur de source. Le terme B consigne 0 ligne enregistrée, 0 ligne utile et une fraction de pertinence inconnue. L'étiquette `source_failed` est une notation du registre pour le lecteur, et non une valeur d'énumération native du jeu de données.

| Terme de requête | Mode | Maximum planifié | Tenté | Lignes enregistrées | Lignes utiles | Raison ou état d'arrêt |
| --- | --- | --- | --- | --- | --- | --- |
| Terme A | Équilibré | 2 | Oui | 2 | 2 | Limite par requête atteinte |
| Terme B | Équilibré | 2 | Oui | 2 | 2 | Limite par requête atteinte |
| Terme C | Équilibré | 2 | Oui | 2 | 2 | Limite par requête atteinte |
| Terme A | Séquentiel | 6 | Oui | 6 | 6 | Plafond partagé `maxResults` atteint |
| Terme B | Séquentiel | 6 | Non | 0 | Inconnu | `not_attempted` |
| Terme C | Séquentiel | 6 | Non | 0 | Inconnu | `not_attempted` |
| Terme A | Équilibré (échec B) | 2 | Oui | 2 | 2 | Limite par requête atteinte |
| Terme B | Équilibré (échec B) | 2 | Oui | 0 | Inconnu | `source_failed` |
| Terme C | Équilibré (échec B) | 2 | Oui | 2 | 2 | Limite par requête atteinte |

### Registre fictif d'appartenance aux requêtes

Une exécution de requêtes fictive et distincte évalue les apparitions des vidéos entre les termes, sans que la déduplication globale écarte les chevauchements.

| ID vidéo | Appartenance au terme A | Appartenance au terme B | Appartenance au terme C | Première requête conservée |
| --- | --- | --- | --- | --- |
| V1 | Présent | Absent | Absent | Terme A |
| V2 | Présent | Présent | Absent | Terme A |
| V3 | Absent | Présent | Absent | Terme B |
| V4 | Absent | Absent | Présent | Terme C |
| V5 | Absent | Absent | Présent | Terme C |

Ce tableau d'appartenance contient 6 appartenances au total pour 5 identifiants de vidéo distincts. Un seul export dédupliqué globalement ne conserve V2 que sous le terme A. Conserver la provenance du terme A pour V2 ne prouve pas que V2 était absent du terme B. L'appartenance complète aux requêtes ne peut être suivie qu'en enregistrant, pour chaque requête, un registre d'exécution borné et séparé.

## Action suivante

Utilisez les entrées publiques de l'[Actor](https://apify.com/chronometrica/tiktok-search-scraper) et de la [Task](https://apify.com/chronometrica/tiktok-search-scraper/examples/tiktok-keyword-monitoring-snapshot) pour fixer vos limites de collecte, puis enregistrez votre plan de requêtes et votre registre de tentatives avant de comparer les sujets.

## Sources et lectures complémentaires

- [Discussion des créateurs de contenu sur Reddit :](https://www.reddit.com/r/ContentCreators/comments/1qdhj7j/how_do_you_guys_find_new_tiktok_trends_early/)
- [Task TikTok Keyword Monitoring Snapshot :](https://apify.com/chronometrica/tiktok-search-scraper/examples/tiktok-keyword-monitoring-snapshot)
- [Actor TikTok Search Scraper :](https://apify.com/chronometrica/tiktok-search-scraper)