Introduction aux API de Google

Notre projet créé va disposer de quotas pour chaque API utilisée, mais aussi avoir une identification propre. Il ne reste plus qu’à activer la ou les API utile(s) dans la bibliothèque en cliquant sur le bouton d’activation. Selon les cas, Google va encourager l’utilisateur à créer une clé d’API ou des identifiants afin de pouvoir s’authentifier ultérieurement.

Fig. 2. Activation de l’API Custom Search.

Rien de bien compliqué à ce stade, mais n’hésitons pas à créer plusieurs types d’authentification si nécessaire, à savoir une clé d’API (c’est le cas par défaut), des identifiants OAuth (souvent nécessaires pour se connecter) voire une clé de compte de service (plus rare, mais parfois la seule solution vraiment fonctionnelle). Maintenant, mettons les mains dans le cambouis et passons au code…

Utiliser la librairie Google API PHP Client

Google recommande d’utiliser des méthodes propres définies dans sa librairie Google API PHP Client (source : https://github.com/google/google-api-php-client). Si ce programme n’est pas le plus simple à aborder pour les plus débutants d’entre nous, il présente l’avantage de contenir de multiples méthodes pour se connecter à la plupart des API de Google. Cela évite d’avoir à tout développer manuellement, bien qu’il soit parfois plus simple de passer par des méthodes simples comme cURL ou GET.

Pour ne pas nous mélanger les pinceaux dans les diverses techniques possibles, il est donc plus intéressant de se focaliser uniquement sur cette librairie PHP de Google. Ainsi, tous les exemples reprendront globalement le même fonctionnement de base, en suivant ces étapes :

1. Télécharger la bibliothèque Google API PHP Client ;
2. Dézipper et copier le dossier complet dans le répertoire de travail du programme ;
3. Activer l’autoload (méthode de programmation orientée objet qui permet d’activer automatiquement l’ensemble des classes et objets d’un programme) ;
4. Créer une connexion client ;
5. S’authentifier avec une clé d’API, des identifiants OAuth ou une clé de compte de service ;
6. Utiliser l’API désirée avec les méthodes de la librairie PHP. Google met à jour les fonctionnalités afin de proposer l’ensemble des possibilités permises par ses API.

Précisons juste que la librairie fonctionne sur une classe PHP appelée Google_Service dont héritent de nombreuses classes-filles pour chaque API (utile pour l’étape 6 présentée précédemment). La documentation officielle n’est pas très claire à ce sujet (source : https://goo.gl/eGhrju) alors voici l’explication du mode de fonctionnement : par exemple, si nous cherchons à appeler l’API URL Shortener pour raccourcir les URL, il faut instancier la classe Google_Service_Urlshortener. Si nous voulons appeler l’API Webfonts pour obtenir des informations sur les polices Google, nous instancierons Google_Service_Webfonts. Et ainsi de suite pour chaque API visée, toujours en respectant la forme « Google_Service_NomAPI ».

En cas de doute pour une méthode d’API, il convient de se rendre dans le répertoire « vendor/google/apiclient-services/src/Google/Service » pour trouver la liste des classes PHP utiles, c’est souvent plus simple que de lire la documentation…

Il existe de rares exceptions dans les noms qui peuvent être trouvées par ce biais. Par exemple, l’API Search Console n’est pas entièrement accessible dans l’objet Google_Service_SearchConsole. Certaines API peuvent être utilisée via la méthode Google_Service_Webmasters initialement créée à l’époque de Google Webmaster Tools (donc avant le changement de nom de l’outil).

Rien de bien compliqué, n’est-ce-pas ? Voyons donc ce que cela peut donner côté code. Pas de crainte à avoir, tout est commenté étape par étape, il ne reste qu’à adapter quelque peu le code selon les besoins.

C’est ainsi que débute la majorité des programmes pour se connecter aux API de Google. Ce qui pourra changer éventuellement est le mode d’authentification. Dans l’exemple, il s’agit de la forme la plus simple avec uniquement une clé d’API (méthode setDeveloperKey), mais bon nombre de services demandent une authentification OAuth voire une clé de compte de service. Ces méthodes sont un peu plus complexes à mettre en œuvre mais expliquées dans le GitHub officiel (source : https://goo.gl/JCgqhL) ou dans la documentation de Google Developers (source : https://goo.gl/hY5tMZ). Voici un résumé des spécificités à connaître dans ces cas précis :

• Un fichier JSON contenant les identifiants du client peut être demandé et se télécharge dans l’interface de gestion des API ;
• Une portée d’utilisation (« scope ») doit être ajoutée pour spécifier le service visé. La liste des scopes de Google est disponible ici : https://goo.gl/kgvofr ;
• OAuth implique la création d’un « token » via une page de redirection, dont le but est d’authentifier le client en ligne, à l’instar de ce que fait Google Connect ;
• Une clé de compte de service demande parfois que le propriétaire du compte soit autorisé à utiliser un outil de Google. En effet, la clé de compte de service génère une adresse email spécifique qu’il faut parfois ajouter dans la liste des propriétaires de la Google Search Console, de Google Analytics, etc. Ce sont des cas rares mais nous pouvons passer des heures à chercher pourquoi l’API ne fonctionne pas, alors que c’est juste une validation qui manque…

Les documentations du GitHub ou de Google sont perfectibles et surtout ne sont pas toujours mises à jour, c’est pourquoi nous pouvons être confrontés à des erreurs lorsque nous tentons de suivre avec attention les informations fournies. C’est notamment le cas pour les connexions OAuth ou par clé de compte de services, quelques mises à jour du code sont manquantes et des informations ont été omises. Les programmes que nous présenterons dans nos articles ont tous été testés et fonctionnent parfaitement, il conviendra donc de s’en servir comme base saine…

Découverte de l’API Custom Search : effectuer une requête web

L’API Custom Search de Google permet à tout un chacun d’interagir avec un moteur de recherche interne (CSE pour « custom search element ») mais aussi d’effectuer une recherche web globale selon certaines conditions. Ainsi, nous pourrons effectuer des requêtes internes, obtenir des informations sur les pages, etc.

Pour créer un moteur personnalisé, il faut se rendre à l’adresse https://cse.google.fr. Nous pouvons soit créer un moteur purement intrasite, soit créer un moteur généraliste comme nous le verrons par la suite. Il suffit d’ajouter une ou plusieurs URL dans lesquelles chercher (Google CSE applique en quelque sorte la fonction « site: » pour rechercher à l’intérieur de ces pages) puis de paramétrer la langue, comme indiqué dans la figure 4.

Fig. 3. Création d’un moteur CSE.

Dans le cas d’analyse SEO, il est assez peu intéressant de créer un moteur de recherche interne. Il est préférable d’effectuer des recherches web totales pour effectuer des requêtes générales, suivre l’indexation voire le positionnement des pages par exemple. Il faut se rendre dans la page « Configuration » du moteur créé et changer deux paramètres, comme l’indique la documentation officielle (https://goo.gl/pzGwoS) :

• Supprimer la ou les URL ajoutée(s) ;
• Passer l’option de restriction de recherche sur « Chercher sur l’ensemble du Web en privilégiant les sites inclus ».

Fig. 4. Créer un moteur web généraliste en changeant les options du moteur CSE.

Nous possédons désormais un moteur de recherche Web, mais il faut savoir que ce dernier ne donnera pas nécessairement les mêmes résultats que les «  vrais  » Google.fr ou Google.com. En effet, Google a supprimé l’API Search qui permettait cela pour ne laisser la place qu'à l’API Custom Search. Par conséquent, quelques manques empêchent d’obtenir exactement les mêmes résultats que dans le moteur classique. La documentation le précise d’ailleurs pour lever tous les doutes à ce sujet (https://goo.gl/VWTkXw). Voici donc un résumé de fonctionnalités qui ne s’appliquent pas et qui engendrent des modifications de classement dans les SERP :

• Aucune oneBox et aucun featured snippet ;
• Pas de recherche en temps réel ;
• Pas de recherche universelle ;
• Aucune personnalisation des résultats (historique de recherche) ;
• Pas de fonctionnalités de réseau social ;
• Pas de géolocalisation.

Avant de mettre la main à la pâte, il est conseillé d’utiliser l’API Custom Search directement dans l’outil de test fourni par Google (https://goo.gl/1AzNzZ). En effet, les quotas sont très limités dans la version gratuite (100 requêtes par jour) et il est préférable de tester plusieurs paramètres avant de créer notre programme. C’est également un bon exercice pour constater les possibilités de l’API.

Côté code, l’API Custom Search offre l’avantage de ne nécessiter qu’une clé d’API, donc inutile de s’embêter avec une connexion OAuth ou une clé de compte de service. Comme nous avons déjà étudié ce type d’exemple, il suffit de reprendre totalement ce qui a été fait dans la section « Utiliser la librairie Google API PHP Client » de cet article.

Ensuite, si nous souhaitons effectuer une recherche, il ne reste qu’à ajouter le code suivant pour tester une requête dans le moteur personnalisé généraliste. Il convient juste de ne pas oublier de préciser le paramètre « cx » (identifiant du moteur CSE) dans le code, sinon l’API ne fonctionnera pas correctement.

Le tableau retourné propose moult informations pour chaque résultat, au-delà de l’ordre de classement (ordre d’apparition des résultats dans le tableau). Par exemple, nous pouvons obtenir des informations sur les micro-données Schema.org (comme AggregateRating pour les notes, Breadcrumb pour la présence d’un fil d’Ariane ou encore Product pour un produit…). Nous avons également la possibilité d’étudier chaque snippet ou balise title de résultat, ce qui peut s’avérer pratique quand on souhaite étudier ces deux données.

L’API Custom Search peut aussi être intéressante pour effectuer le suivi interne du site. En effet, il suffit de faire une requête de type « site:https://www.notre-site.fr » pour obtenir un suivi intéressant. Nous pouvons alors lister les titres et snippets, compter le nombre total de pages indexées dans Google, etc.

Usage avancé de l’API Custom Search : trouver une position

Bien que le moteur CSE dans sa version Web généraliste ne propose pas exactement les mêmes classements que le Google que nous utilisons habituellement, il peut être intéressant de comprendre comment utiliser l’API pour trouver le classement d’un nom de domaine (page d’accueil ou interne) pour une requête donnée.

Dans le programme PHP entièrement commenté qui va suivre, nous allons récupérer un tableau de données contenant la liste des URL qui précèdent notre site web recherché. Ainsi, pour toute requête testée, nous allons pouvoir chercher une URL dans les SERP, et si cette dernière est trouvée, nous récupèrerons sa position, quelques informations, et surtout la liste des pages qui la précède. Précisons qu’il ne s’agit que d’un exemple de fonction, retenons donc plutôt l’esprit du programme et son mode de fonctionnement général.

Nous allons créer une fonction crawlSerp() qui va fonctionner de manière récursive. Cela signifie que cette même fonction peut s’appeler elle-même (prenez l’exemple de la suite de Fibonacci en mathématiques, c’est de la récursivité). Dans notre cas, cela va permettre de crawler la première page du moteur CSE pour une requête ciblée, puis si notre URL n’est pas présente, de faire de même avec la seconde page des SERP, et ainsi de suite. Pour éviter de chercher trop profondément dans les SERP, nous pouvons limiter le nombre de pages à tester (5 par défaut, donc les 50 premiers résultats).
La figure 6 montre le genre de résultat que l’on pourrait obtenir après que le programme ait crawlé plusieurs pages des SERP sur une requête précise. Il suffit de modifier dans le code la requête d’origine, le nom de domaine recherche, le nombre de pages maximum à crawler et enfin les paramètres du moteur CSE (paramètre « cx » notamment et clé de l’API).

Fig. 5. Récupération du ranking d’une page avec l’API Custom Search.

Trêve de bavardage, voici le programme dans son ensemble :

Nous maîtrisons désormais toutes les bases des API de Google et notamment de l’API Custom Search. Pour faire suite à cette introduction, nous étudierons en détail dans de prochaines lettres d’Abondance des services plus intéressants en matière de SEO. Patience… 😉