Dopo aver introdotto il lettore all'uso di Yahoo! BOSS ed aver proposto alcuni esempi per l'uso di questo strumento per la ricerca di pagine web, andiamo a completare l'argomento proponendo degli spunti utili per effettuare ricerche mirate di immagini o di news. Questa tematica sarà naturalmente molto simile a quanto già affrontato per la ricerca di pagine web, ma sono presenti numerose piccole differenze che giustificano la scelta di dedicarvi alcuni paragrafi aggiuntivi. Restano valide tutte le indicazioni sul codice fornite in precedenza, quindi l'uso della libreria SimpleXML per interpretare i risultati o l'uso dell'estensione Curl piuttosto che della funzione file_get_contents() per inviare le richieste HTTP.
Ricerca di immagini
Il primo cambiamento riguarda l'indirizzo del web service, che riflette il fatto di effettuare ricerche per immagini:
http://boss.yahooapis.com/ysearch/images/v1/{query}?{parametri}
Rimangono validi tutti i parametri descritti per la ricerca nel web, a cui è possibile aggiungerne altri, quali ad esempio:
- filter, che assume come valori yes oppure no (yes di default, indica l'attivazione del filtro per i contenuti ritenuti offensivi, quali ad esempio violenza o pornografia);
- dimensions, che può assumere uno tra i seguenti valori: all (predefinito), small (miniature o icone), medium (immagini di media dimensione, che di solito non superano la dimensione dello schermo), large (immagini più larghe, che possono raggiungere o superare la dimensione dello schermo), wallpaper oppure widewallpaper.
I risultati della ricerca saranno sempre in formato XML simile a quanto analizzato in precedenza, con le dovute modifiche. In particolare, il nodo principale che contiene tutti i risultati non sarà più <resultset_web> ma ovviamente <resultset_images>, al cui interno troveremo tanti nodi <result> ad indicare i singoli risultati. Il nodo <resultset_images> avrà, in analogia con il corrispondente per la ricerca sul web, alcuni attributi che indicano il numero totale dei risultati (totalhits e deephits) ed il riferimento alla posizione dei risultati che si stanno visualizzando (start e count).
Interpretare i risultati della ricerca di immagini
Per ogni nodo <result> saranno presenti tutta nodi quante sono le informazioni disponibili sulla singola immagine. Di seguito proponiamo un elenco di massima:
- title, il titolo dato all'immagine
- abstract, una sua breve descrizione
- filename, il nome del file
- date, la data di indicizzazione dell'immagine, nel formato aaaa/mm/gg
- width, la larghezza dell'immagine in pixel
- height, l'altezza dell'immagine in pixel
- size, la dimensione del file in byte
- mimetype, il tipo MIME (ad esempio image/jpeg)
- format, il formato dell'immagine (ad esempio jpeg)
- thumbnail_width, la larghezza della miniatura in pixel
- thumbnail_height, l'altezza della miniatura in pixel
- thumbnail_url, l'indirizzo URL della miniatura
- url, l'indirizzo URL dell'immagine
- clickurl, 'indirizzo URL da usare nei propri collegamenti per linkare l'immagine
- refererurl, l'indirizzo URL del referer, ossia della pagina web che ospita l'immagine
- refererclickurl, l'indirizzo URL da usare nei propri collegamenti per linkare il referer
La maggior parte di queste informazioni sono di ovvia interpretazione per quanto riguarda l'utilizzo delle immagini. L'unico appunto probabilmente riguarda l'uso dei campi <clickurl> e <refererclickurl> che forse non sono immediatamente chiari: si tratta, come già visto per la ricerca web, di URL utilizzati da Yahoo! per fini statistici e vanno sempre utilizzati nel caso in cui noi volessimo inserire un collegamento dalle nostre pagine web alle immagini ottenute tramite la ricerca.
Altri vincoli da tenere a mente quanto utilizziamo i risultati della ricerca sono i seguenti:
- è necessario mostrare almeno uno tra i campi
<title>e<abstract>in riferimento a ciascuna immagine - è richiesto di mostrare almeno i primi 40 caratteri del campo
<refererurl> - è richiesto di usare sempre i campi
<clickurl>e<refererclickurl>sia per i link, come spiegato sopra, sia per qualsiasi altro tipo di collegamento (ad esempio per mostrare all'interno di un frame la pagina che ospita l'immagine)
Esempio di ricerca di immagini
Poiché l'utilizzo del servizio per la ricerca di immagini è molto simile alla ricerca di pagine web, proponiamo direttamente un esempio che dovrebbe chiarire come si possa mettere insieme le informazioni appena apprese.
Creiamo innanzi tutto il modulo per la ricerca, nel file boss_image.php:
<form action="boss_image_search.php" method="post">
Cerca risultati
<select name="site">
<option value="">su tutto il web</option>
<option value="html.it">su HTML.it</option>
</select>
<input type="text" name="query" />
<input type="submit" name="submit" value="Cerca" />
</form>
Il modulo invia la richiesta alla pagina boss_image_search.php a cui riserviamo la gestione dei risultati. Di seguito il codice di tale pagina:
<?php // Application ID $appid = 'MIA-APP-ID'; // Alcuni parametri $param = array(); $param[] = "appid={$appid}"; $param[] = "format=xml"; // Risposta in XML $param[] = "count=5"; // 5 immagini per volta nei risultati if ($_REQUEST['site'] == 'html.it') { $param[] = "sites=html.it"; } // Costruisco una stringa tipo param1=value¶m2=value2&... $param = implode('&', $param); // Pulizia query if (empty($_REQUEST['query'])) { die("Cosa stai cercando?"); } $query = urlencode($_REQUEST['query']); // URL del servizio $url = "http://boss.yahooapis.com/ysearch/images/v1/{$query}?{$param}"; // Effettuo la chiamata HTTP ed ottengo la risposta XML if ($result = file_get_contents($url)) { // Gestione dei risultati $xml = simplexml_load_string($result); foreach ($xml->resultset_images->attributes() as $k => $v) { $$k = $v; } $res_start = $start + 1; $res_end = $start + $count; echo "<p>Risultati: {$res_start}-{$res_end} di " . number_format($deephits, 0, ',', '.') . " per la ricerca su <b>{$_REQUEST['query']}</b></p>"; // Mostro i risultati in tabella echo '<table>'; foreach ($xml->resultset_images->result as $r) { echo ' <tr> <td><a href="' . $r->clickurl . '"><img alt="' . $r->title . '" src="' . $r->thumbnail_url . '" /></a></td> <td> <b>' . $r->title . '</b><br /> ' . $r->abstract . '<br /> <span style="color: darkgreen;">' . $r->refererurl . '</span> </td> </tr> '; } echo '</table>'; } else { echo 'Errore interrogazione'; } ?>
Il risultato di questo script sarà la creazione di una tabella, formata da 5 righe e due colonne, in cui per ciascuna riga sarà presente un risultato: la miniatura cliccabile dell'immagine sulla colonna di sinistra, mentre su quella di destra verranno riportati il titolo, l'abstract e l'URL che la ospita. Il lettore attento avrà notato numerose analogie con la ricerca per le pagine web, come ad esempio il modo in cui è possibile specificare i parametri di ricerca (mediante l'array $param nel nostro codice), o la gestione degli attributi del result set utilizzando il ciclo foreach per valorizzare variabili quali $deephits, $start e $count.
Ricerca di news
Analizziamo ora la ricerca di notizie sul web sfruttando il medesimo web service. Come per le immagini, anche in questo caso sarà necessario utilizzare un indirizzo ad hoc per le nostre richieste, nell'usuale forma (in grassetto la parte da cambiare):
http://boss.yahooapis.com/ysearch/news/v1/{query}?{parametri}
Rimangono validi i parametri descritti per la ricerca sul web, a cui andiamo ad aggiungere un ulteriore parametro per filtrare le notizie in base alla data di pubblicazione: con il parametro age possiamo appunto indicare l'intervallo temporale in cui cercare. Il valore predefinito è pari a 7d (7 days, ossia la ricerca viene effettuata su notizie pubblicate negli ultimi 7 giorni). In generale un valore per questo parametro viene costruito concatenando un numero intero ad una delle seguenti lettere:
- s, seconds, ossia secondi
- m, minutes, ossia minuti
- h, hours, ossia ore
- d, days, ossia giorni
- w, weeks, ossia settimane
Il numero intero e la lettera vanno riportati senza spaziatura, ed è possibile inoltre indicare un intervallo sfruttando il segno meno ("trattino"), ad esempio 5d-10d indica la ricerca di notizie vecchie dai 5 ai 10 giorni. Non è consentito indicare intervalli multipli o inserire più volte il parametro age. L'archivio delle notizie mantiene un indice fino a 30 giorni, quindi non è consentito cercare notizie più vecchie.
Interpretare i risultati della ricerca di news
Analogamente a quanto già visto per pagine web e immagini, anche la ricerca di news ci porta ad avere come risposta un documento XML il cui nodo più importante, che rappresenta il result set, si chiama appunto <resultset_news>. Al suo interno troveremo un nodo <result> per ciascuna news trovata, con diverse nodi figli che vanno a descrivere tutte le informazioni della notizia in questione.
Di seguito proponiamo l'elenco di tali nodi ed il relativo significato:
- title, il titolo della notizia
- abstract, un breve riassunto
- date, la data di pubblicazione o di ultima revisione
- time, l'orario di pubblicazione o di ultima revisione
- language, la lingua in cui è scritta la notizia (ad esempio "en english")
- url, l'indirizzo URL in cui è riportata la notizia
- clickurl, l'indirizzo da utilizzare nei propri risultati come link alla notizia
- source, il nome della fonte da cui è tratta la notizia
- sourceurl, l'indirizzo URL della fonte
Conclusioni
L'interpretazione dei risultati avviene in modo assolutamente analogo a quanto visto per la ricerca di pagine web e per la ricerca di immagini, per cui sarà sufficiente utilizzare gli esempi proposti in precedenza adattandoli al contesto delle news. In particolare, un aspetto molto interessante sarà la ricerca mirata per una singola lingua o per un singolo paese, nel caso in cui si vogliano utilizzare solo notizie localizzate.
Abbiamo dunque visto che con poche righe di codice è possibile integrare le funzionalità di ricerca all'interno delle proprie pagine web. Oltre alla ricerca, che magari gli utenti preferiscono effettuare direttamente su un motore di ricerca, potrebbe essere interessante aggiungere alle nostre pagine web notizie o immagini in tema con l'argomento del nostro sito, sfruttando quindi l'indice di Yahoo! per avere contenuti che possono dare un piccolo valore aggiunto alle nostre pagine.
