phpInfo.netLes ArchivesLes éléPHPants

  
  Accueil
  Trucs & Astuces
  Scripts
  Regex
  Annuaire
  Articles

.
      
 Articles   SOAP et les APIs Web de Google  Par Jean-Pierre DEZELUS   Juin 2002    »  Les API Web de Google
 »  Présentation rapide de SOAP et WSDL
 »  Prérequis
 »  Formuler une requête
 »  Exploiter les résultats
 »  Démonstration et script complet


Les API Web de Google

Depuis plusieurs semaines maintenant Google vous offre la possibilité d'intégrer pratiquement toutes les fonctionnalités de son puissant moteur de recherches à votre site.

Pour proposer son API Web, Google s'appuie sur le protocole SOAP (Simple Object Access Protocol) et sur le langage WSDL (Web Services Description Language). Ce service, à usage personnel et surtout non commercial, vous permettra d'exécuter jusqu'à 1000 requêtes par jour à destination de ses serveurs tout en restituant les résultats dans la forme de votre choix.
Si votre site est particulièrement bien référencé chez Google, ce système peut donc avantageusement remplacer votre moteur de recherche interne, à condition bien sûr que la demande de vos visiteurs ne dépasse pas la limite des 1000 requêtes par jour.

Attention toutefois, ce service est en version béta, donc sans garantie de bon fonctionnement et peut être intérrompu à n'importe quel moment par Google et cela de façon définitive.

J'ajouterai un grand merci à Loïc d'Anterroches, Webmaster de XHTML.net pour son article consacré à l'API Google, à l'origine de l'article que vous lisez aujourd'hui. Le script que vous trouverez en fin d'article est une amélioration de celui proposé sur XHTML.net.

Présentation rapide de SOAP et WSDL

L'objectif de cet article n'est pas de présenter SOAP , mais une petite description de ce protocole et du langage WSDL qui lui est associé vous aidera à comprendre son utilité et son principe de fonctionnement.

Pour rester simple, SOAP (Simple Object Access Protocol) est un protocole d'échange de données et de services entre applicatifs et sites Web. Il s'appuie sur le protocole HTTP pour le transport et sur le langage XML pour la description des données et des messages transmis.
Le langage WSDL (Web Services Description Language) sert quant à lui à décrire la façon d'appeler et d'utiliser les services Web distants.

SOAP est implémenté dans PHP au travers d'une librairie disponible dans PEAR (PHP Extension and Application Repository).

Prérequis

Plusieurs éléments sont nécessaires à la mise en oeuvre des services Web de Google sur votre site.

Le kit du développeur
La première chose à faire est de télécharger le Kit du développeur sur le site de Google. Ce sera pour vous l'occasion de lire et de donner votre accord sur les termes de la licence.

Ce kit ne contient malheureusement pas d'exemple d'utilisation de l'API Google avec le langage PHP (seuls Java et .Net sont représentés) mais nous verrons plus loin comment nous en sortir.
Vous trouverez dans ce kit 2 fichiers particulièrement intéressants :
  • APIs_Reference.html : c'est le manuel de référence complet de l'API Google. Il décrit sous quelle forme envoyer les requêtes aux serveurs, et comment exploiter les données retournées. Gardez toujours ce document sous la main.
  • GoogleSearch.wsdl : ce fichier qui pour nous restera purement informatif donne la description des services Web offert par Google. On y trouve entre autres le nom et le format des requêtes qu'il est possible d'envoyer ou qui sous quelle forme nous pouvons recevoir les résultats.
Un n° de licence
Pour pouvoir utiliser les services Web de Google, il vous faut un compte. Ce compte se traduit sous la forme d'une clé à 32 caractères qui vous est délivrée contre votre email et un mot de passe.
Cette clé personnelle devra être transmise dans chaque requête envoyée au serveur.
Elle vous donnera droit à 1000 requêtes par jour.

SOAP/PEAR
Pour pouvoir dialoguer avec les serveurs de Google sur la base du protocole SOAP, il vous faut récupérer son implémentation dans PHP au travers de PEAR.
La totalité de PEAR n'est pas nécessaire, c'est pourquoi nous ne téléchargerons (avec le prérequis suivant) que le strict nécessaire au bon fonctionnement de nos scripts..

Pour ceux qui souhaitent disposer de la totalité de PEAR, le serveur CVS de PHP.net est à leur disposition.

La classe SOAP_Google
La librairie SOAP fournie avec PEAR ne suffit pas à elle même pour pouvoir dialoguer avec les services Web de Google. Il nous faut une couche supplémentaire qui met en forme les messages envoyés et qui restitue de manière facilement exploitable par PHP les messages reçus en retour.
Cette couche existe et a été écrite par Sebastian Bergmann. Elle est disponible sur son site personnel www.sebastian-bergmann.de/?page=google. Vous trouverez aussi sur le site le snapshot de SOAP/PEAR que j'évoquais précedemment et qui est indispensable au bon fonctionnement de la classe de Sebastian.

Maintenant que nous disposons de tous les éléments de base, il ne nous reste plus qu'à écrire le script PHP qui va interroger effectivement les serveurs de Google.

Formuler une requête

La formulation de la requête est on ne peut plus simple, grâce surtout à la classe de Sebastian Bergmann.

<?php
// n° de licence google
$key = 'aaaabbbbccccddddeeeeffffgggghhhh';

require_once(
'SOAP_Google.php');

// paramètres de la requête
$parametres = Array
(
    
'query'        => 'ma recherche',
    
'restrict'     => 'countryFR',
    
'safeResearch' => true,
    
'start'        => 0,
    
'maxResults'   => 10,
    
'lr'           => 'lang_fr|lang_en',
    
'ie'           => 'utf8',
    
'oe'           => 'utf8'
);

// exécution de la requête
$google = new SOAP_Google($key);
?>

Les différents paramètres de la requête sont décrits très précisemment dans le document APIs_Reference.html fourni avec le kit du développeur. Sachez qu'ils sont strictement identiques aux champs du formulaire de recherche proposé par Google sur son propre site.
  • query : contient les termes à rechercher. En les faisant précéder de site:www.votresite.com, vous limiterez la recherche à votre seul site.
  • restrict : limite dans l'exemple la recherche aus sites français.
  • safeResearch : permet de ne proposer aucun site pour adultes dans les résultats.
  • maxResults : définit le nombre de réponses par page.
  • start : index du 1er élément retourné. Pour obtenir les pages suivantes il faut l'incrémenter de maxResults.
  • lr (language restrict) : langues des résultats retournés. Dans l'exemple seules les pages en français et en anglais figureront dans les résultats.
  • ie (input encoding) : jeu de caractères utilisé pour les requêtes envoyées.
  • oe (output encoding) : jeu de caractères à utiliser pour les données retournées par Google.


Exploiter les résultats

L'exploitation des résultats est elle aussi élémentaire. Il faut d'abord s'assurer que la requête a abouti. Ce ne sera pas toujours le cas, par exemple si vous avez atteint la limite des 1000 demandes/jour.

<?php
if ($resultats = $google->search($parametres))
{
    
// traitement des résultats
    // .....
}
else
{
    
// la requête n'a pas abouti
    
echo "Erreur !";
}
?>

Le traitement peut avoir réussi mais le nombre de résultats égal à zéro. Il faut aussi le vérifier.
Comme vous l'avez peut-être constaté, l'ensemble des données retournées par Google est disponible dans le tableau associatif $resultat.
Celui-ci contient d'une part des informations générales comme le temps d'exécution (searchTime), les bornes (startIndex et endIndex), et d'autre part les données elles mêmes (resultElements).

Chaque élément $resultats['resultElements'] est à son tour un tableau associatif contenant l'URL, le résumé, le titre, la taille du cache, etc.

<?php
if (sizeof($resultats['resultElements']) > 0)
{
    
$numero = $resultats['startIndex'];
   
    
// réponses
    
foreach ($resultats['resultElements'] as $reponse)
    {
        
// URL + titre
        
echo ($numero++);
        echo
'. <a href="'.$reponse['URL'].'">'.$reponse['title'].'</a>;
        // extrait
        echo '
<br />''.$reponse['snippet'].'<br />';
        
// description ODP
        
if (($description = $reponse['directoryTitle']) != '')
        {
            echo
'Description: '.$description.'<br />';
        }
        
// catégorie ODP
        
if (($categorie = $reponse['directoryCategory']['fullViewableName']) != '')
        {
            echo
'Cat&eacute;gorie: ';
            echo
'<a href="http://directory.google.com/'.$categorie.'/">';
            echo
str_replace('/', ' > ', $categorie).'</a><br />';
        }
        
// lien + cache
        
$url = eregi_replace('^http://', '', $reponse['URL']);
        echo
'<font color="#008000">'.$url.' - '.$reponse['cachedSize'].'</font>';
        echo
' - <a href="http://www.google.com/search?q=cache:'.urlencode($url);
        echo
'" target="_blank">En cache</a>';
        
// pages similaires
        
echo ' - <a href="api-google.php?q=related:'.urlencode($url).'">';
        echo
'Pages similaires</a><br /><br />';
    }

    
// page prec
    
if ($resultats['startIndex'] > $maxResults)
    {
        echo
'<a href="api-google.php?q='.urlencode($q).'&debut=';
        echo (
$resultats['startIndex']-$maxResults-1).'">&laquo;</a>';
    }

    
// n° page courante
    
echo '&nbsp;'.(int)(($resultats['startIndex'] / $maxResults)+1).'&nbsp;';
   
    
// page suiv
    
if (($resultats['startIndex'] + $maxResults) == ($resultats['endIndex'] + 1))
    {
        echo
'<a href="api-google.php?q='.urlencode($q).'&debut=';
        echo (
$resultats['endIndex']).'">&raquo;</a>';
    }
}
?>


Démonstration et script complet

Pour terminer voici deux exemples d'utilisation de ces scripts.

Le premier exemple vous montre comment il est possible d'intégrer complètement le moteur de recherche à son site. Je l'ai donc fait pour phpInfo.net en appliquant la charte graphique pour les résultats et en limitant les recherches au domaine phpinfo.net.

Pour le deuxième exemple je me suis tout simplement amusé à reproduire un écran de résultat "à la Google".
Le script utilisé est disponible dans la rubrique Scripts de phpInfo.net.

A vous de jouer maintenant !
Synseo