Yahoo BOSS: introduzione al web service

Nel luglio 2008 è stato proposto da Yahoo il nuovo servizio BOSS, Build your Own Search Service, che consente agli sviluppatori di creare applicazioni con la possibilità di interfacciarsi con il servizio di ricerca di Yahoo, sfruttando quindi le potenzialità del motore di ricerca all'interno dei propri programmi. Trattandosi di un web service, lo sviluppatore non è vincolato ad uno specifico linguaggio per poter accedere al servizio, ma può utilizzare lo strumento che preferisce per inviare le richieste via HTTP ed interpretare le relative risposte nel formato XML o JSON. In queste pagine introdurremo il lettore all'utilizzo del servizio BOSS, affrontando il problema dal punto di vista di PHP. Nei prossimi articoli verranno proposti esempi di utilizzo più complessi per effettuare ricerche di pagine web e di immagini.

Accesso al servizio

L'accesso a Yahoo BOSS è fornito gratuitamente agli sviluppatori che sono già utenti registrati su Yahoo! Network. Una volta ottenuto un account Yahoo, è necessario registrare la propria applicazione per richiedere la chiave (App ID) da utilizzare nel nostro codice. Oltre a specificare il nome della nostra applicazione e una breve descrizione, ci viene richiesto di scegliere il tipo metodo di autenticazione, necessaria per interfacciarsi con servizi Yahoo che la richiedono. Nel nostro caso, il metodo "Generic" è la scelta adeguata, ossia nessuna autenticazione verrà richiesta all'utente.

Funzionamento del servizio

BOSS è una web service basato su architettura REST, il che significa che le risorse messe a disposizione sono accessibili semplicemente effettuando una chiamata HTTP GET verso la relativa URL. L'indirizzo da indicare per le ricerche sul web è sempre nel formato:

http://boss.yahooapis.com/ysearch/web/v1/{query}?{parametri}

dove {query} e {parametri} sono ovviamente dei segnaposto per i valori reali.

Le risposte fornite dal web service possono essere nel formato JSON (opzione predefinita) o nel formato XML. Questa seconda opzione sarà la scelta adottata nei nostri esempi.

Rispetto al precedente servizio di ricerca offerto da Yahoo, BOSS ha molti meno vincoli e soprattutto non pone un limite sul numero di query giornaliere, anche se il suo utilizzo può essere filtrato per limitare l'uso di bot automatici che vanno ad intasare di richieste il servizio stesso.

Costruzione di una query

Il formato della query rispecchia quello di una normale ricerca che l'utente può effettuare manualmente con il motore di ricerca. L'unico accorgimento riguarda l'utilizzo di alcuni caratteri speciali che vanno codificati in maniera opportuna, per fortuna in modo molto semplice, utilizzando la funzione urlencode():

$query = "una query molto complessa";
$query = urlencode($query);

Per quanto riguarda la scelta dei parametri, andiamo ad elencarne i principali:

• appid, ossia l'application ID che abbiamo ottenuto in fase di registrazione, obbligatorio ai fini del funzionamento del nostro codice;
• format, il formato di risposta (xml o json, dove json è l'opzione predefinita);
• start, la posizione di partenza dei risultati, dove 0 è il primo risultato ed il valore predefinito, utile nel caso di gestione della paginazione;
• count, il numero di risultati che vogliamo ottenere da una query, 10 come valore di default, si può aumentare fino ad un massimo di 50;
• lang, il codice della lingua in cui si effettua la ricerca (predefinito "en" per l'inglese), da utilizzare congiuntamente con region;
• region, il codice della regione in cui si effettua la ricerca (predefinito "us" per Stati Uniti), da utilizzare congiuntamente con lang;
• sites, l'elenco di domini, separati da virgole, in cui si vuole restringere la ricerca;
• filter, nel caso volessimo applicare un filtro alla ricerca, per eliminare contenuti a carattere pornografico (-porn) o contenuti che esprimano odio o violenza (-hate), quest'ultimo disponibile solo per i risultati in inglese;
• type, nel caso volessimo specificare i tipi di file ottenuti in risposta (ad esempio "html" per ottenere solo risultati in formato HTML; oppure "pdf,msoffice" per ottenere risultati in formato PDF o in uno dei formati del pacchetto Office)

Note: lang e region sono particolarmente utili nel caso in cui si voglia effettuare una ricerca tra le news;
sites equivale ad usare la parola chiave "site:" nella query durante una ricerca manuale.

Un primo esempio

Costruiamo ora un primo esempio di ricerca per vedere il funzionamento del servizio nella pratica. Assumiamo che il modulo di ricerca abbia la seguente forma, personalizzabile a piacere:

<form action="boss_example.php">
<input type="text" name="query" />
<input type="submit" name="submit" value="Cerca" />
</form>

Questo significa che il file boss_example.php, descritto di seguito, sarà dedicato ad effettuare la ricerca e gestire i risultati, ottenendo dal form la stringa di ricerca nella variabile $_GET['query'] (non specificando il metodo di ricerca, GET è l'opzione predefinita). Di seguito il file boss_example.php:

<?php
// Application ID
$appid = 'MIA-ID';
// Alcuni parametri
$param = array();
$param[] = "appid={$appid}";
$param[] = "format=xml"; // Risposta in XML
$param[] = "filter=-porn"; // Filtro pornografia
$param[] = "type=html"; // Solo documenti html nei risultati
// Costruisco una stringa tipo param1=value¶m2=value2&...
$param = implode('&', $param);
// Pulizia query
if (empty($_GET['query'])) {
    die("Cosa stai cercando?");
}
$query = urlencode($_GET['query']);
// URL del servizio
$url = "http://boss.yahooapis.com/ysearch/web/v1/{$query}?{$param}";
// Effettuo la chiamata HTTP ed ottengo la risposta XML
if ($result = file_get_contents($url)) {
    // Gestione dei risultati
    echo nl2br(htmlentities($result));
}
?>

Nell'esempio, la richiesta HTTP viene effettuata con la funzione file_get_contents() passando l'URL come parametro, che è l'opzione più semplice che abbiamo a disposizione. Un'altra possibilità consiste nell'utilizzo dell'estensione CURL: definendo una funzione come quella dell'esempio che segue, la si può sostituire a file_get_contents() nell'esempio precedente.

function curl_get_contents($url){
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $res = curl_exec($ch);
    curl_close($ch);
    return $res;
}

Quest'ultimo esempio richiama alcune porzioni di codice proposte nella documentazione di Yahoo BOSS, che è bene consultare per avere un quadro più completo.

Interpretare i risultati

Nel primo esempio i risultati ottenuti nel formato XML sono stati semplicemente stampati a video con l'istruzione echo, scelta che ovviamente non è utile in un caso d'uso reale, ma che ci consente di avere una panoramica completa sul modo in cui il web service ci fornisce i risultati stessi. In questo paragrafo vediamo di approfondire il formato della risposta XML per capire in quale modo sia possibile sfruttarla al meglio per i nostri scopi.

Di seguito proponiamo lo scheletro di una possibile risposta XML:

<ysearchresponse responsecode="200">
  <nextpage><![CDATA[...]]></nextpage>
  <resultset_web count="10" start="0" totalhits="XYZ" deephits="XYZ">
    <result>
      <abstract><![CDATA[...]]></abstract>
      <date>yyyy/mm/dd</date>
      <dispurl><![CDATA[...]]></dispurl>
      <clickurl>URL da cliccare</clickurl>
      <size>Dimensione risultato</size>
      <title>Titolo risultato</title>
      <url>URL risultato</url>
    </result>
  </resultset_web>
</ysearchresponse>

Osserviamo che il tag radice è <ysearchresponse>, che riporta un attributo responsecode indicante il valore del codice HTTP della risposta (200 significa che l'operazione è andata a buon fine). Nel tag <nextpage> viene riportato l'indirizzo della pagina successiva nel caso volessimo sfruttarlo per costruire una paginazione: in sostanza si tratta dell'URL di ricerca con l'aggiornamento del parametro start descritto nel paragrafo precedente.

Il tag successivo, <resultset_web>, contiene l'elenco dei risultati, uno per ogni tag figlio <result>. Oltre ai risultati, abbiamo qualche informazione numerica sotto forma di attributi:

• count, 10 nell'esempio, indica il numero di risultati presenti nel resultset, parametro che è possibile manipolare come indicato nel paragrafo precedente;
• start, il punto di partenza, anche in questo caso descritto nel paragrafo precedente;
• totalhits, il numero totale di risultati per le chiavi di ricerca specificate, senza contare eventuali duplicati;
• deephits, il numero totale di risultati tenendo in considerazione i duplicati; in entrambi i casi si tratta di approssimazioni che vanno ad essere più precise man mano che l'attributo start aumenta, ossia processando un maggior numero di risultati.

Per ogni elemento <result>, che rappresenta uno dei risultati, andiamo a trovare diversi tag figli che rappresentano le informazioni relative a quello specifico risultato:

• abstract, un estratto del documento, comunemente visibile nei risultati dei motori di ricerca;
• date, data di ultima modifica nel formato aaaa/mm/gg
• clickurl, URL da utilizzare nei link, effettua un redirect tramite un dominio Yahoo
• dispurl, URL da utilizzare in un output HTML
• title, titolo del risultato
• size, dimensione in byte del risultato
• url, vero indirizzo del risultato

Nota: per inserire un link al risultato in una propria pagina web, è richiesto l'utilizzo di clickurl e non di url, per fornire a Yahoo informazioni sull'utilizzo del web service.

Per interpretare il codice XML all'interno del nostro script PHP abbiamo varie opzioni. Nel prossimo articolo proporremo esempi in questo senso tramite l'estensione SimpleXML, oltre ad esempi di ricerca più articolati, che ci aiuteranno a completare il quadro.

Link di approfondimento

• Introduzione ai web service, articolo introduttivo all'uso dei web service
• REST, pagina su Wikipedia, introduzione all'architettura REST
• Yahoo! Search BOSS, pagina ufficiale su Yahoo! Developer Network, da cui è possibile iscriversi al servizio e consultare la documentazione