Flickr, per i pochi che non lo conoscono, è un sito web che offre un servizio di condivisione di foto, e più recentemente anche di filmati, tramite il quale gli utenti possono pubblicare il loro materiale, visualizzare le pubblicazioni degli altri utenti, commentarle o iscriversi a gruppi tematici. L'iscrizione al servizio è gratuita, anche se è prevista una versione "Pro" a pagamento che offre funzionalità aggiuntive e più spazio di archiviazione. Nel marzo del 2005, Flickr è stato acquistato da Yahoo! e questo ha portato all'integrazione dei vecchi account sulla nuova piattaforma. Oltre a ciò, diverse migliorie sono state apportate al servizio, tra cui un innalzamento dei limiti sullo spazio offerto, sia per gli account gratuiti che per quelli a pagamento.
Come molti servizi web in stile 2.0, anche Flickr mette a disposizione degli sviluppatori un web service che permette di interfacciarsi al servizio, consentendo quindi di integrare nella propria applicazione o nel proprio sito web tutte le principali funzionalità disponibili. Anche qui, come per molti altri servizi, il canale di comunicazione è semplicemente HTTP, e la lingua franca è XML: ciò significa che è possibile sfruttare le API di Flickr con un qualsiasi linguaggio di programmazione. Lo scopo di queste pagine è introdurre il lettore all'uso delle API di Flickr, dal punto di vista dello sviluppatore PHP.
Per iniziare
L'architettura del servizio consente di utilizzare diversi formati sia per l'invio delle richieste che per l'interpretazione delle risposte. Sebbene sia possibile implementare tutte le funzionalità in modo autonomo, per semplificare la vita agli sviluppatori sono già presenti diverse librerie, definite Kit API, non supportate ufficialmente da Flickr ma comunque da tenere in considerazione per la loro completezza. Tra le altre, lo Zend Framework offre qualche spunto all'interno del package Zend_Service, ma le funzionalità relative a Flickr sono abbastanza limitate, in quanto l'utilizzo è circoscritto a quelle funzioni che non richiedono autenticazione (in sostanza, soltanto la ricerca di foto nell'archivio pubblico).
Un progetto più completo, che utilizzeremo nei nostri esempi, è sicuramente phpFlickr, rilasciato con licenza GNU/GPL e compatibile con PHP 4 e PHP 5. Una volta scaricati i sorgenti di phpFlickr, è sufficiente scompattarli e copiarli in una directory all'interno del nostro spazio web. Da notare inoltre il fatto che questo pacchetto si appoggia ad alcune librerie di PEAR, in particolare su HTTP_Request che è l'unica indispensabile, le quali vengono comunque distribuite insieme a phpFlickr.
Per consentire alla nostra applicazione di interfacciarsi al servizio, sarà necessario ottenere una chiave (API Key), che potrà essere rilasciata per un uso commerciale o non commerciale. È importante in questo caso fare riferimento ai termini d'uso del servizio. Naturalmente per richiedere una chiave API dobbiamo essere in possesso di un account sul sito Flickr. Va ricordato che la chiave è univoca per l'applicazione e per l'account, ossia non è possibile trasferire una chiave ottenuta da un account ad un altro. Registrando l'applicazione, ci verranno forniti due dati: la chiave API vera e propria, ed una seconda stringa chiamata "secret" che verrà utilizzata per il processo di autenticazione.
Ricerca di immagini
Proponiamo ora un primo esempio di codice che ci consente di effettuare una ricerca all'interno dell'archivio pubblico. Questo significa che non è richiesta una procedura di autenticazione.
L'intera classe phpFlickr è stata costruita rispettando la nomenclatura suggerita dall'API, ossia tutti i vari metodi sono disponibili con lo stesso nome, e richiedono gli stessi parametri nello stesso ordine, ad eccezione della chiave API che viene passata al costruttore. Questo significa che per effettuare una chiamata a flickr.photos.search, useremo la funzione photos_search() della classe. Questa funzione in particolare si differenzia da tutte le altre in quanto, a causa dell'elevato numero di parametri che si possono fornire in modo facoltativo, prevede di passare come unico parametro un array associativo.
<?php
// Chiave API
$api_key = 'mia-api-key';
// Includo la libreria phpFlickr
require_once('phpflickr/phpFlickr.php');
$flickr = new phpFlickr($api_key);
// Effettuo la ricerca
if (isset($_POST['submit'])) {
$param = array(
'text' => $_POST['cerca'],
'per_page' => 10,
);
$result = $flickr->photos_search($param);
// Gestione dei risultati
echo '<pre>';
print_r($result);
echo '</pre>';
}
// Mostro il form
echo '
<form method="post">
Fai una ricerca: <input type="text" name="cerca" />
<input type="submit" name="submit" value="Cerca" />
</form>';
?>Il codice proposto mostra un banalissimo modulo con un unico campo di testo utilizzato per la ricerca. Quando il modulo viene inviato, viene invocato il metodo photos_search() sull'oggetto $flickr istanziato nelle righe precedenti. Il risultato di questa chiamata è un array associativo che sarà quindi facile da gestire.
In questo esempio, come accennato precedentemente, non era necessaria alcuna autenticazione, per cui l'oggetto $flickr è stato istanziato passando solo la chiave API come parametro del costruttore. In caso di autenticazione, è necessario passare anche la stringa secret. Eventualmente è disponibile un terzo parametro booleano per decidere se lanciare una chiamata a die() in caso di errore all'interno della classe (il valore predefinito è false, ossia in caso di errore la classe non interrompe l'esecuzione).
I parametri utilizzati per la chiamata di photos_search() sono stati, per semplicità, soltanto due:
- text, per effettuare la ricerca all'interno del titolo, della descrizione o delle etichette (tag) delle varie foto;
- per_page, per indicare quanti risultati vogliamo ottenere con questa chiamata; il valore predefinito è 100, mentre il valore massimo è 500.
Alcuni parametri interessanti per la ricerca, oltre a text, possono essere i seguenti:
- user_id, per restringere la ricerca sulle foto inserite da un determinato utente;
- group_id, per restringere la ricerca sulle foto inserito all'interno di un determinato gruppo;
- tags, una lista di etichette, separate da virgole;
- tag_mode, da associare al parametro tags, può assumere come valori "any" (predefinito) se si sta cercando una qualsiasi delle etichette specificate, oppure "all" se si sta cercando l'elenco esatto di tutte le etichette specificate.
Inoltre sono presenti numerosi parametri legati alla localizzazione geografica delle fotografie, alle date di scatto e di upload, alle licenze d'uso, ad altri parametri inerenti le macchine fotografiche utilizzate. Oltre al parametro per_page può essere invece interessante specificare il parametro page, che di default vale 1, per costruire una eventuale paginazione nella ricerca.
Interpretare i risultati della ricerca
Per quanto riguarda l'interpretazione dei risultati, abbiamo semplicemente stampato a video l'array $result ottenuto da photos_search(). Dando un'occhiata più da vicino, scopriamo che questo array è costituito da cinque elementi:
- page, ossia la pagina corrente all'interno dei risultati;
- pages, ossia il numero totale di pagine disponibili;
- perpage, ossia il numero di risultati per ogni pagina, che avevamo specificato durante la chiamata;
- total, ossia il numero totale di risultati disponibili per la ricerca effettuata;
- photo, a sua volta un array, che contiene i risultati veri e propri.
All'interno di $result['photo'] troveremo quindi 10 elementi, a loro volta array associativi, costituiti dai seguenti campi:
- id, ossia l'identificativo della foto;
- owner, ossia l'identificativo del proprietario della foto;
- secret, una stringa da utilizzare per ricostruire l'URL della foto (vedi seguito);
- server, l'identificativo del server su cui è memorizzata la foto;
- farm, l'identificativo della farm in cui è memorizzata la foto;
- title, il titolo della foto;
- ispublic, posto a 1 se la foto è pubblica, 0 altrimenti;
- isfriend, posto a 1 se la foto è riservata agli amici, 0 altrimenti;
- isfamily, posto a 1 se la foto è riservata alla famiglia, 0 altrimenti.
Alcuni di questi dati ci consentono di ricostruire gli indirizzi URL su flickr.com in cui sono ospitate le immagini o altre informazioni. Ad esempio con l'identificativo della foto e del rispettivo proprietario, possiamo costruire, tra gli altri, i seguenti indirizzi:
Profilo utente: http://www.flickr.com/people/{owner}/ Stream fotografico dell'utente: http://www.flickr.com/photos/{owner}/ Pagina con singola foto: http://www.flickr.com/photos/{owner}/{id}
Utilizzando gli altri identificativi, possiamo recuperare vari URL legati ad una singola foto:
Foto in dimensioni medie: http://farm{farm}.static.flickr.com/{server}/{id}_{secret}.jpg Foto in formato 75x75 pixel (small): http://farm{farm}.static.flickr.com/{server}/{id}_{secret}_s.jpg Foto in formato thumbnail (100 pixel sul lato lungo) http://farm{farm}.static.flickr.com/{server}/{id}_{secret}_t.jpg Foto in formato medio-piccolo (medium): http://farm{farm}.static.flickr.com/{server}/{id}_{secret}_m.jpg Foto in formato grande (big): http://farm{farm}.static.flickr.com/{server}/{id}_{secret}_b.jpg
Recuperando il codice precedente, possiamo fare quindi una piccola variazione alla parte relativa alla ricerca, per rendere i risultati più gradevoli da vedere:
// La parte che precede questo blocco rimane uguale al codice di pagina 2
// Effettuo la ricerca
if (isset($_POST['submit'])) {
$param = array(
'text' => $_POST['cerca'],
'per_page' => 10,
);
$result = $flickr->photos_search($param);
// Gestione dei risultati
foreach ($result['photo'] as $photo) {
$url_photo = "http://farm{$photo['farm']}.static.flickr.com/{$photo['server']}/{$photo['id']}_{$photo['secret']}.jpg";
$url_owner = "http://www.flickr.com/photos/{$photo['owner']}";
$title = empty($photo['title']) ? 'senza titolo' : htmlentities($photo['title']);
echo '
<div>
<a href="' . $url_photo . '">' . $title . '</a>
pubblicata da <a href="' . $url_owner . '">' . $photo['owner'] . '</a>
</div>
';
}
}
// La parte che segue questo blocco rimane uguale al codice di pagina 2Questo codice effettua semplicemente un ciclo sui risultati, stampando a video, su tante righe quante sono le foto ottenute, un link con il titolo della foto (oppure la dicitura "senza titolo" se il campo è vuoto) ed un link con il riferimento al proprietario della foto stessa.
Altri spunti
Prima di concludere, rimandiamo alla documentazione ufficiale dell'API di Flickr e della classe phpFlickr, raccomandando una lettura attenta, anche per avere un'anticipazione di tutte le funzionalità dell'API. Nella prossima puntata affronteremo il problema dell'autenticazione, che a prima vista potrebbe sembrare macchinoso, e cercheremo di sfruttare altre funzionalità dell'API, proponendo diversi esempi di codice che andranno a corredare la parte descrittiva.
