Google non ha bisogno di presentazioni, grazie ad una tecnologia di indicizzazione efficiente e a un database di dimensioni colossali è divenuto il punto di riferimento per chiunque voglia reperire informazioni nel WEB.
Tra le funzionalità accessorie di Google ce n'è una che esaudisce il sogno di molti webmaster: mettere a disposizione dei propri navigatori il database del motore di ricerca, senza doverli dirottare su www.google.it.
Sono le Google Web APIs, un webservice che attraverso il protocollo SOAP (Simple Object Access Protocol) consente di "imbrigliare" la potenza di Google nelle pagine di un sito.
Le uniche limitazioni riguardano il numero di richieste giornaliere (massimo 1.000) e la quantità di risultati visualizzabili per richiesta (massimo 10).
Il servizio è disponibile da poco più di un anno ed è ancora sperimentale, ma già vale la pena di provare. Vediamo come poterlo sfruttare con il nostro linguaggio PHP.
Di che cosa abbiamo bisogno?
Di uno script che agisca da client SOAP e che quindi sia in grado di inviare richieste al servizio e decodificarne le risposte; ci serviremo di un'apposita libreria di classi Php: inizialmente la mia scelta era caduta su PEAR::SOAP, ma a causa di alcuni bug spuntati nelle recenti release ho optato per NuSOAP (http://dietrich.ganx4.com/nusoap/), il progetto di Sourceforge da cui PEAR::SOAP deriva.
Scelto lo script, dobbiamo seguire le semplici istruzioni descritte nella pagina dedicata da Google alle Web APIs; avendo scelto l'applicazione, possiamo saltare il punto 1 ("Download the developer's kit"), per passare immediatamente al 2: l'iscrizione che consente di ricevere via mail l'indispensabile chiave di indentificazione.
Il servizio in due parole
La documentazione del servizio, molto chiara, è consultabile sia online che in locale (se si scarica il "developer's kit" quasi inutile per chi programma in Php).
Il webservice sta in ascolto all'indirizzo http://api.google.com/search/beta2 e attende di ricevere una request HTTP di tipo POST, i parametri che il client deve fornire sono il nome della procedura da eseguire e gli argomenti della medesima (Es. i termini da ricercare, il linguaggio entro cui restringere i risultati e così via).
Le procedure remote richiamabili sono tre, ma ci concentreremo esclusivamente sulla più importante, "doGoogleSearch", che consente di effettuare ricerche nel database di Google con funzionalità analoghe a quelle disponibili accedendo alla homepage del motore.
Per l'utilizzo pratico non è necessaria una comprensione dei Webservice e del protocollo SOAP, ma comunque consiglio un attenta lettura di due articoli: Introduzione ai Webservices che descrive le basi teoriche dei servizi WEB e SOAP: far comunicare le applicazioni sul Web che fornisce un'utile panoramica su SOAP.
NuSOAP
NuSOAP è una libreria Php in grado di offrire sia funzionalità client che server per SOAP. In questo caso ci occuperemo soltanto delle prime visto
che non dobbiamo creare un webservice, bensì utilizzarne uno già esistente.
Purtroppo non è possibile scaricare tutti i file necessari in un solo pacchetto, e siamo costretti a prelevarli uno per uno dal cvs di Sourceforge. I più pigri possono trovare package completo con la versione disponibile al momento in cui scrivo, ma è fondamentale tenere d'occhio gli aggiornamenti sul sito che ospita il progetto.
NuSOAP crea automaticamente la request nel formato XML di SOAP e la invia a destinazione, quindi preleva la risposta e la decodifica in un array o in un oggetto Php.
"doGogleSearch" con NuSOAP
Si tratta di un'operazione semplicissima:
<?php
/*
include la classe base (il file nusoap.php)
*/
include("nusoap_directory/nusoap.php");
/*
crea un istanza del client SOAP e indica l'indirizzo del servizio
*/
$soapclient = new soapclient("http://api.google.com/search/beta2");
/*
decommenta la riga seguente per vedere i messaggi di debug
*/
// $soapclient->debug_flag = 1;
/*
Google vuole che la request venga confezionata con il seguente namespace
*/
$namespace = 'urn:GoogleSearch' ;
/*
L'array con i parametri da passare alla procedura remota
*/
$parametri = array(
//la chiave di accesso fornitaci con l'iscrizione
'key' => 'XXX-TUA_CHIAVE_ACCESSO-XXX',
//i parametri per la ricerca
'q' => '"corso webmaster" site:html.it',
//Il risultato da cui iniziare la visualizzazione
'start' => 0,
//Il numero di risultati da restituire (max 10)
'maxResults' => 8,
//Elimina i duplicati
'filter' => true,
//Circoscrive in base all'argomento
//o al TLD (top level domain, es .it)
'restrict' => '',
//Elimina i siti per adulti
'safeSearch' => false,
//Seleziona il linguaggio (si può omettere)
'lr' => 'lang_it',
//Codifica usata per la request (default UTF-8)
'ie' => '',
//Codifica usata per la risposta (default UTF-8)
'oe' => ''
);
/*
Invoca la procedura remota "doGoogleSearch"
*/
$risposta = $soapclient->call("doGoogleSearch", $parametri, $namespace);
/*
Se riceve una risposta SOAP di errore la stampa
*/
if($soapclient->fault){
echo('ERRORE! '.$soapclient->faultstring."n<br>") ;
}
else{
/*
DIMOSTRATIVO
Stampa l'array completo con il risultato della ricerca
*/
echo('<pre>') ;
print_r($risposta);
echo('</pre>') ;
}
?>
Impostando adeguatamente il parametro 'q' ("query") abbiamo cercato all'interno del network di HTML.it ("site:html.it") la frase "corso webmaster" (l'abbiamo evidenziato in rosso).
Fortunatamente la sintassi per la ricerca è la stessa che possiamo usare normalmente con Google.
print_r() visualizza un array associativo multidimensionale, del quale trovate un' elencazione completa all'url http://www.google.it/apis/reference.html#search_results_format: la voce che più ci interessa è $risposta['resultElements'], poichè contiene un sotto-array con i risultati veri e propri della ricerca.
Ad esempio in $risposta['resultElements'][0] troviamo il primo degli 8 risultati che abbiamo scelto di visualizzare, cosicchè print_r($risposta['resultElements'][0]) darebbe il seguente output
Array
(
[cachedSize] => 17k
[hostName] =>
[snippet] => Corso di WebMaster Base Questo corso parte dai concetti di base quali la comunicazione attraverso Internet e tocca tutti gli argomenti che sono coinvolti ...
[directoryCategory] => Array
(
[specialEncoding] =>
[fullViewableName] =>
)
[relatedInformationPresent] => 1
[directorytitle] =>
[summary] =>
[URL] => http://corsi.html.it/wm01.htm
[title] => CORSI DI FORMAZIONE - Corso di WebMaster Base
)
Osservazioni sull'uso di NuSOAP
Il metodo soapclient::call() prende come argomenti rispettivamente la procedura remota da eseguire, un array di parametri e l'eventuale namespace. Quest'ultimo per Google è sempre "urn:GoogleSearch", quale che sia la procedura remota chiamata. I più curiosi possono visualizzare i formati XML di richiesta e risposta eseguendo il metodo call e visualizzando il contenuto delle proprietà $soapclient->request e $soapclient->response.
Un motore di ricerca personalizzato
Lo script che segue è una dimostrazione di come si possa inserire in una propria pagina un motore di ricerca personalizzato che sfrutti Google.
<?php
/*
Il modulo html
*/
$searchForm = <<<EOD
<h2>My "personal" search engine</h2>
<form action="{$_SERVER['PHP_SELF']}">
<input type="text" size="40" value="" name="query" /> <input type="submit" value=" GO! " /><br />
<input type="radio" name="lr" value="" checked="checked">Cerca nel Web <input type="radio" name="lr" value="lang_it" /> Cerca solo pagine in italiano
</form>
EOD;
/*
Controlliamo che il submit non sia avvenuto a modulo vuoto
*/
$_GET['query'] = isset($_GET['query']) ? trim($_GET['query']) : NULL ;
if ( !empty($_GET['query']) ){
/*
include la classe base di NuSOAP e il file con i parametri
*/
include_once("nusoap_directory/nusoap.php") ;
include_once("parametri.php") ;
/*
crea un' istanza del client SOAP e indica l'indirizzo del servizio
*/
$soapclient = new soapclient("http://api.google.com/search/beta2") ;
/*
Invoca la procedura remota "doGoogleSearch"
*/
$risposta = $soapclient->call('doGoogleSearch', $parametri, 'urn:GoogleSearch') ;
/*
Se riceve una risposta SOAP di errore la stampa
*/
if($soapclient->fault){
exit('ERRORE! '.$soapclient->faultstring) ;
}
$output = '' ;
$output .= $searchForm."<br />" ;
$output .= 'La ricerca <strong> - '.stripslashes( $risposta['searchQuery'] ).' - </strong>' ; ;
$output .= 'ha restituito <strong>'.$risposta['estimatedTotalResultsCount'].' risultati</strong>' ;
$output .= '<ul>' ;
/*
Aggiunge uno alla volta i risultati della ricerca alla variabile $output
*/
foreach ($risposta['resultElements'] as $r){
$output .= '<li><a href="' . $r['URL'] . '" target="_blank">'.$r['title'] . '</a><br />';
$output.= $r['snippet'] . '(' .$r['cachedSize'] . ')<br />';
$output.= '<span style="color : #ff0000 ; font-size:10pt">'.$r['URL'].'</span></li><br /><br />' ;
}//END foreach
$output.= '</ul>' ;
/*
Visualizza i risultati
*/
echo($output) ;
}
/*
Se non è stata inviata alcuna richiesta
*/
else{
echo($searchForm) ;
}//END else
?>
Qui sotto il file con i parametri che abbiamo incluso:
<?php
//FILE parametri.php
/*
L'array con i parametri da passare alla procedura remota
*/
$parametri = array(
//la chiave di accesso fornitaci con l'iscrizione
'key' => 'XXX-TUA_CHIAVE_ACCESSO-XXX',
//i parametri per la ricerca
'q' => $_GET['query'],
//Il risultato da cui iniziare la visualizzazione
'start' => 0,
//Il numero di risultati da restituire (max 10)
'maxResults' => 10,
//Elimina i duplicati
'filter' => true,
//Circoscrive in base all'argomento
//o al TLD (top level domain, es .it)
'restrict' => '',
//Elimina i siti per adulti
'safeSearch' => false,
//Seleziona il linguaggio (si può omettere)
'lr' => $_GET['lr'],
//Codifica usata per la request (default UTF-8)
'ie' => '',
//Codifica usata per la risposta (default UTF-8)
'oe' => ''
);
?>
Il risultato
Ecco come si presenta la pagina dopo la ricerca:
Allo script manca un sistema di paginazione dei risultati che ho tralasciato per questioni di semplicità e disponibilità di spazio.
Conclusioni
In questa occasione abbiamo affrontato l'argomento Webservices da un punto di vista puramente pratico, al solo scopo di mostrare una delle molte applicazioni utili, ma in un prossimo futuro ci addentreremo nei meandri di XML-RPC e SOAP. Tra le altre cose scopriremo come sia possibile realizzare un proprio servizio WEB analogo alle "Google Web APIs" grazie a Php.
