L’endpoint adAnalytics est là où réside la logique d’extraction. Il comporte plusieurs contraintes structurelles qui imposent des décisions d’ingénierie spécifiques en matière de conception des requêtes, de gestion des erreurs et de stratégie de chargement incrémental.
Absence de pagination
La caractéristique la plus inhabituelle de l’endpoint adAnalytics : il n’a pas de pagination. Tous les autres endpoints importants dans l’univers des API de plateformes publicitaires — SearchStream de Google, l’API Insights de Meta — utilisent la pagination pour gérer les grands ensembles de résultats. L’adAnalytics de LinkedIn renvoie tous les résultats en une seule réponse, plafonnée à 15 000 éléments.
Si votre requête renvoie plus de 15 000 lignes, l’API tronque la réponse sans vous avertir que la troncature a eu lieu. Vous n’obtenez pas d’erreur. Vous obtenez simplement 15 000 lignes au lieu de 25 000, et à moins de compter les lignes par rapport à vos attentes, vous ne le saurez pas.
Cela signifie que vous devez gérer vous-même la taille de la réponse en contrôlant la portée de chaque requête. Le pattern standard consiste à segmenter par plage de dates — demander une semaine à la fois plutôt qu’un mois, ou un jour à la fois pour les comptes avec de nombreuses campagnes. La bonne taille de segment dépend de l’échelle de votre compte : le nombre de campagnes multiplié par le nombre de jours dans votre plage doit rester bien en dessous de 15 000 avec une marge.
Pour les grands comptes gérant des centaines de campagnes actives avec des répartitions démographiques (qui multiplient le nombre de lignes), vous pourriez avoir besoin de demander un seul jour à la fois. Intégrez la logique de segmentation par date dans votre code d’extraction dès le départ plutôt que de découvrir le problème de troncature quand votre pipeline tourne depuis six mois et que vous remarquez que les comptages de campagnes ne correspondent pas à l’interface LinkedIn.
La limite de 20 métriques
Chaque requête adAnalytics peut inclure un maximum de 20 métriques. L’API LinkedIn offre plus de 20 métriques — métriques de performance de base, métriques d’actions sociales, métriques virales, métriques d’engagement vidéo et métriques de conversion. Si vous les voulez toutes, vous avez besoin de plusieurs requêtes par période.
La clé de jointure est la combinaison de l’identifiant creative ou campagne et la date. Pour une seule campagne sur un seul jour, vous feriez deux requêtes (métriques 1-20 et métriques 21+) et joindriez sur (campaign_id, date_day) dans votre couche de transformation.
En pratique, cela signifie décider quelles métriques vous avez réellement besoin plutôt que tout collecter. La plupart des équipes n’ont pas besoin des métriques de taux d’engagement viral aux côtés des données standard de clics et de dépenses. Soyez délibéré sur les métriques dans chaque requête, documentez la décision et construisez vos jointures explicitement.
Query tunneling pour les URLs longues
L’API LinkedIn utilise des paramètres de requête pour spécifier les campagnes, creatives et métriques que vous souhaitez récupérer. Pour les comptes avec de nombreuses campagnes, la liste des IDs de campagne dans les paramètres de requête peut dépasser les limites de longueur d’URL — généralement autour de 2 000 à 4 000 caractères selon la couche HTTP. Quand vous atteignez la limite, vous obtenez une erreur 414 URI Too Long.
La solution de contournement est le “query tunneling” : au lieu d’une requête GET avec les paramètres dans l’URL, vous envoyez une requête POST avec les paramètres dans le corps. L’API LinkedIn supporte ce pattern — vous envoyez les mêmes paramètres, simplement dans le corps d’un POST plutôt qu’ajoutés à l’URL.
C’est non évident la première fois que vous le rencontrez. Le code d’erreur est suffisamment clair (414), mais la solution n’est pas aussi bien documentée qu’elle devrait l’être. Si vous construisez un extracteur personnalisé, ajoutez le support du query tunneling dès le départ pour tout endpoint acceptant de longues listes de paramètres. Si vous utilisez un outil managé, vérifiez qu’il gère correctement le query tunneling — certaines implémentations plus anciennes utilisaient uniquement des requêtes GET.
Pagination curseur pour les endpoints d’entités
L’endpoint analytics n’a pas de pagination, mais les endpoints d’entités (comptes, groupes de campagnes, campagnes, creatives) utilisent la pagination basée sur les curseurs. En janvier 2024, LinkedIn a migré ces endpoints d’entités de la pagination par index vers la pagination par curseur.
La pagination par index vous permet de demander directement “la page 3 des résultats” en spécifiant un offset. La pagination par curseur vous donne un token de curseur opaque avec chaque réponse que vous transmettez pour obtenir la page suivante — il n’y a aucun moyen de sauter à une page spécifique. C’est en fait une approche plus fiable (moins sujette aux enregistrements manquants quand les données changent en cours de pagination), mais c’est un changement incompatible pour tout code de pipeline personnalisé écrit avant janvier 2024.
Si vous travaillez avec du code écrit avant cette migration, les endpoints d’entités doivent être mis à jour. L’endpoint analytics n’a pas été affecté — il n’a jamais eu de pagination à migrer.
Limites de taux (que LinkedIn ne vous communique pas)
Les limites de taux de LinkedIn ont deux types : au niveau application (total d’appels pour tous les utilisateurs de votre application) et au niveau membre (appels liés à un token OAuth spécifique). Les deux se réinitialisent à minuit UTC.
LinkedIn ne publie pas les chiffres spécifiques des limites. Vous apprenez vos limites en les atteignant, ou en regardant l’onglet Analytics du portail développeur, qui affiche votre utilisation de quota. Il n’y a aucun moyen programmatique en temps réel de vérifier à quel point vous êtes proche d’une limite avant de l’atteindre.
Les alertes email arrivent à 75 % du quota — avec un délai de 1 à 2 heures. Au moment où vous recevez l’email, vous pouvez déjà avoir atteint la limite. Intégrez un backoff exponentiel avec jitter dans votre code d’extraction, et traitez les réponses 429 comme attendues plutôt qu’exceptionnelles.
Pour les comptes à fort volume exécutant plusieurs extractions concurrentes, les limites de taux non publiées rendent la planification de capacité difficile. L’approche pratique : commencez prudemment, surveillez régulièrement le tableau de bord de quota du portail développeur pendant les premières semaines, et ralentissez si vous voyez la consommation de quota s’approcher des limites.
Versionnage mensuel de l’API
LinkedIn utilise un versionnage mensuel de l’API avec une spécification basée sur les headers. Vous incluez un header Linkedin-Version: YYYYMM avec chaque requête pour spécifier la version d’API souhaitée. Chaque version est supportée pendant au moins un an depuis sa sortie.
L’URL de base est https://api.linkedin.com/rest/. L’endpoint /v2/ legacy a été complètement déprécié en juin 2023 — toute documentation ou code référençant le chemin v2 doit être mis à jour.
L’implication pratique du versionnage mensuel : LinkedIn peut livrer des changements incompatibles chaque mois, et vous devez suivre le changelog pour savoir quand quelque chose que vous utilisez change. En pratique, LinkedIn ne livre pas de changements incompatibles chaque mois, mais le header de version est votre protection — vous adoptez les nouveaux comportements en mettant à jour votre header de version plutôt qu’ils vous soient imposés.
Un changement incompatible notable à suivre : les métriques Sponsored Messaging ont changé en juillet 2024. Les impressions et clics ne sont plus rapportés pour les campagnes Sponsored Messaging. Ils sont remplacés par les envois et ouvertures. Si vous avez des campagnes Sponsored Messaging et que votre code d’extraction demande les anciennes métriques, vous obtiendrez maintenant des zéros pour les impressions et clics. Mettez à jour votre configuration de métriques et votre documentation pour utiliser les nouveaux champs.
Les complications des données démographiques
Les pivots démographiques professionnels (MEMBER_COMPANY, MEMBER_JOB_TITLE, MEMBER_SENIORITY, etc.) sont disponibles via adAnalytics mais viennent avec des contraintes supplémentaires au-delà des contraintes standard :
- Les valeurs sont approximatives et protégées pour la vie privée — LinkedIn applique du bruit sur les petits nombres
- Seules les 100 premières valeurs par creative par jour sont retournées
- Un seuil minimum de 3 événements est requis avant qu’une valeur apparaisse
- La rétention des données pour les répartitions démographiques est limitée à 2 ans (contre 10 ans pour les données de performance standard)
La granularité journalière n’est disponible que pendant 6 mois. Après cela, LinkedIn arrondit automatiquement à l’agrégation mensuelle. Pour la conception de pipeline : si vous souhaitez des données démographiques journalières, vous devez les capturer dans la fenêtre de 6 mois. Les backfills historiques au-delà donnent au mieux des données à granularité mensuelle.
Ces contraintes signifient que les données démographiques nécessitent une stratégie de pipeline différente des métriques de performance standard. Gardez les extractions démographiques séparées des extractions de performance, avec une documentation explicite sur ce que représentent les valeurs et pourquoi elles pourraient ne pas s’additionner exactement aux totaux. Voir linkedin-ads-b2b-data-value pour savoir comment interpréter et utiliser ces données de manière productive.