12.7. Recherche Google

Revenons au code d'exemple que nous avons vu au début du chapitre, qui effectue quelque chose de plus intéressant et de plus utile qu'obtenir la température.

Google fournit une API SOAP pour accéder aux résultats de recherche par la programmation. Pour l'utiliser, il faut s'inscrire aux Services Web Google.

Procédure 12.4. S'inscrire au Services Web Google

Allez à l'adresse http://www.google.com/apis/ et créez un compte Google. Il suffit d'une adresse e-mail. Après vous être inscrit, vous recevrez une clé de licence pour l'API Google par e-mail. Vous devrez passer cette clé en paramètre pour appeler les fonctions de recherche.
Toujours à l'adresse http://www.google.com/apis/, téléchargez le kit de développement des API Google. Il contient des exemples de code en de nombreux langages de programmation (mais pas en Python) et, surtout, il contient le fichier WSDL.
Décompressez le kit de développement et cherchez le fichier GoogleSearch.wsdl. Copiez ce fichier quelque part sur votre disque, vous en aurez besoin plus tard dans ce chapitre.

Une fois que vous avez une clé de licence et le fichier WSDL de Google, vous pouvez commencer vos expérimentation des services Web Google.

Exemple 12.12. Introspection des services Web Google

>>> from SOAPpy import WSDL
>>> server = WSDL.Proxy('/path/to/your/GoogleSearch.wsdl') 
>>> server.methods.keys()                                  
[u'doGoogleSearch', u'doGetCachedPage', u'doSpellingSuggestion']
>>> callInfo = server.methods['doGoogleSearch']
>>> for arg in callInfo.inparams:                          
...     print arg.name.ljust(15), arg.type
key             (u'http://www.w3.org/2001/XMLSchema', u'string')
q               (u'http://www.w3.org/2001/XMLSchema', u'string')
start           (u'http://www.w3.org/2001/XMLSchema', u'int')
maxResults      (u'http://www.w3.org/2001/XMLSchema', u'int')
filter          (u'http://www.w3.org/2001/XMLSchema', u'boolean')
restrict        (u'http://www.w3.org/2001/XMLSchema', u'string')
safeSearch      (u'http://www.w3.org/2001/XMLSchema', u'boolean')
lr              (u'http://www.w3.org/2001/XMLSchema', u'string')
ie              (u'http://www.w3.org/2001/XMLSchema', u'string')
oe              (u'http://www.w3.org/2001/XMLSchema', u'string')

	Pour commencer à utiliser les services Web Google, il suffit de créer un objet `WSDL.Proxy` et de lui indiquer votre copie locale du fichier WSDL de Google.
	D'après le fichier WSDL, Google fournit trois fonctions : `doGoogleSearch`, `doGetCachedPage` et `doSpellingSuggestion`. Elles font exactement ce que leur nom suggère : effectuer une recherche Google et retourner les résultats, obtenir la version dans le cache de Google d'une page Web et suggérer une orthographe différente pour les mots couramment mal orthographiés dans les recherches.
	La fonction `doGoogleSearch` prend de nombreux paramètres de différents types. Notez que si le fichier WSDL peut vous dire le nom et le type des arguments, il ne peut pas vous dire leur signification et comment les utiliser. Il pourrait théoriquement vous indiquer la plage de valeurs légales pour chaque paramètre si seules certaines valeurs était acceptées, mais le fichier WSDL de Google n'est pas aussi détaillé. `WSDL.Proxy` ne fait pas de miracle, il ne peut vous donner que l'informtion contenue dans le fichier WSDL.

Voici un bref résumé de tous les paramètres de la fonction doGoogleSearch :

key - La clé de licence reçue à l'inscription aux services Web Google.
q - Le mot ou la phrase recherchés. La syntaxe est exactement la même que sur le formulaire Web de Google, vous pouvez donc utiliser les paramètres de recherche avancés.
start - L'index de départ des résultats. Comme sur le site Web, la fonction retourne 10 résultats à la fois, si vous souhaitez accéder à la deuxième «page» de résultats, mettez start à 10.
maxResults - Le nombre de résultats à retourner. Pour l'instant limité à 10, mais vous pouvez en demander moins si vous n'êtes intéressés que par quelques résultats et voulez préserver votre bande passante.
filter - Si mis à True, Google filtrera les doublons des résultats.
restrict - Donnez lui comme valeur country plus le code de pays pour obtenir des résultats d'un pays en particulier. Par exemple countryUK limitera la recherche au Royaume Uni. Vous pouvez également spécifier linux, mac ou bsd pour rechercher parmis un ensemble de sites techniques défini par Google ou unclesam pour rechercher des sites traitant du gouvernement des Etats-Unis.
safeSearch - Si il est mis à True, Google filtrera les sites pornographiques.
lr («language restrict») - Donnez lui comme valeur le code d'une langue pour obtenir des résultats limités à une langue.
ie et oe («input encoding», encodage de l'entrée et «output encoding», encodage de la sortie) - N'est plus utilisé, l'entrée comme la sortie sont encodés en utf-8.

Exemple 12.13. Rechercher avec Google

>>> from SOAPpy import WSDL
>>> server = WSDL.Proxy('/path/to/your/GoogleSearch.wsdl')
>>> key = 'YOUR_GOOGLE_API_KEY'
>>> results = server.doGoogleSearch(key, 'mark', 0, 10, False, "",
...     False, "", "utf-8", "utf-8")             
>>> len(results.resultElements)                  
10
>>> results.resultElements[0].URL                
'http://diveintomark.org/'
>>> results.resultElements[0].title
'dive into <b>mark</b>'

	Après l'initialisation de l'objet `WSDL.Proxy`, nous pouvons appeler `server.doGoogleSearch` avec les dix paramètres. Rappelez-vous d'utiliser votre propre clé de licence pour les services Web Google.
	Il y a beaucoup d'information retournée, mais regardons d'abord les résultats de la recherche proprement dite. Ils sont stockés dans `results.resultElements` et nous pouvons y accéder comme à n'importe quelle liste Python.
	Chaque élément de `resultElements` est un objet qui a de nombreux attributs utiles comme `URL`, `title`et `snippet`. A ce stade, nous pouvons utiliser les techniques d'introspection habituelles de Python comme `dir(results.resultElements[0])` pour voir les attributs disponibles. Nous pouvons aussi utiliser l'introspection sur l'objet de délégation WSDL pour examiner les `outparams` de la fonction. Les deux techniques vous donneront accès à la même information.

L'objet results contient plus que les résultats de la recherche proprement dits. Il contient également des informations sur la recherche elle-même, telles que le temps qu'elle a pris et le nombre de résultats trouvés (même si seuls 10 ont été retournés). L'interface Web Google montre ces informations et elle sont également disponibles par la programmation.

Exemple 12.14. Accéder aux informations secondaires de Google

>>> results.searchTime                     
0.224919
>>> results.estimatedTotalResultsCount     
29800000
>>> results.directoryCategories            
[<SOAPpy.Types.structType item at 14367400>:
 {'fullViewableName':
  'Top/Arts/Literature/World_Literature/American/19th_Century/Twain,_Mark',
  'specialEncoding': ''}]
>>> results.directoryCategories[0].fullViewableName
'Top/Arts/Literature/World_Literature/American/19th_Century/Twain,_Mark'

	Cette recherche a pris 0.224919 secondes. Cela n'inclut pas le temps passé à envoyer et recevoir les documents XML SOAP. C'est uniquement le temps que Google a passé à traiter notre requête une fois celle-ci reçue.
	Au total, il y a approximativement 30 millions de résultats. Nous pouvons y accéder 10 par 10 en changeant le paramètre `start` et en appelant à nouveau `server.doGoogleSearch`.
	Pour certaines requêtes, Google retourne aussi une liste des catégories de l'Annuaire Google qui s'y rapportent. Il suffit alors d'ajouter ces URL à http://directory.google.com/ pour construire le lien vers la page de la catégorie.

Plongez au coeur de Python