[iOs] Link Maker: generazione dinamica dei link di Apple Store

Per la generazione dei link di tutti gli articoli (ebook, musica, app, podcast, audiolibri, ecc.) disponibili su iTunes, iBook ed App Store, Apple mette a disposizione la pagina di iTunes Link Maker:  http://linkmaker.itunes.apple.com

Link Maker Apple

Esistono, in realtà, vari strumenti utili per la generazione dei link (creare link ad iTunes), utili però solo per la creazione di widget e link statici. Ad esempio, in questo Q&A si spiega come generare link a propri item (come, ad esempio, alla pagina delle app sviluppate da uno sviluppatore o da una società: Creating easy-to-read short links to the App Store for your apps and company).

Tuttavia, non esiste un vero e proprio framework che consenta di recuperare dinamicamente tali link. Occorre richiamare una URL di servizio, fornita proprio da Apple, così come si legge dalla Search API Documentation.

Ho così realizzato uno “scriptino” PHP in grado di restituirvi i risultati della pagina di iTunes Link Maker in formato JSON. Per fare ciò, mi sono aiutato con uno sniffer e ho recuperato tutte le URL richiamate dopo aver lanciato una ricerca sulla pagina di Link Maker. Le URL generate “dietro le quinte” dalla ricerca sono un bel po’ e cambiano in base alla combinazione tra “media” selezionato (categoria di item: audio, video, app, ebook, ecc.) e relative entity (sottocategorie di item non selezionabili, ma impostate da Apple come ulteriori keyword di ricerca, in base al media selezionato).

Potete provare la ricerca dalla form di esempio disponibile qui:

Nello script PHP che ho realizzato, non faccio altro che richiamare la stessa URL di Apple, passando una combinazioni di parametri (essenzialmente cambiano “media” ed “entity“):

http://itunes.apple.com/WebObjects/MZStoreServices.woa/ws/wsSearch?term=%s&country=%s&media=%s&entity=%s&limit=%s&genreId=%s&version=2&output=json

Al posto di %s occorre inserire dei valori ammissibili (la lista completa la trovate sulla documentazione ufficiale – Search API Documentation):

  • term: contiene la keyword di ricerca (ad esempio, “Oasis what’s the story morning glory”)
  • country: identificativo del Paese (IT, US, UK, ecc.). La ricerca restituirà gli item disponibili sugli Apple Store del paese selezionato. La lista completa dei Paesi è disponibile qui: http://www.francescoficetola.it/link-maker/countries.json
  • media: deve contenere la categoria di item. I valori ammissibili sono: audiobook (per gli AudioLibri), shortFilm (per i Cortometraggi), movie (per i Film), software (per le iOs app), ebook (per i Libri), macSoftware (per le Mac Apps), music (per i brani audio), podcast (per i PodCast), musicVideo (per i Video).
  • limit: numero massimo di risultati di ricerca da restituire;
  • entity: contiene le sottocategorie dei prodotti. Questo valore dipende dal parametro media impostato (le varie combinazioni sono elencate di seguito);
  • genreId: (opzionale) contiene il codice relativo al genere di media desiderato. Esistono varie combinazioni, disponibili al seguente link:

Ecco le combinazioni di media e relative entity, così come mappate nel mio script PHP:

//AUDIOLIBRI
if($media=='audiobook'){
   $entity = array('audiobookAuthor','audiobook');
}

//CORTOMETRAGGI
if($media=='shortFilm'){
   $entity = array('shortFilmArtist','shortFilm');
}

//FILM
if($media=='movie'){
   $entity = array('movieArtist','movie');
}

//iOS Apps
if($media=='software'){
   $entity = array('softwareDeveloper','software','iPadSoftware');
}

//LIBRI
if($media=='ebook'){
   $entity = array('ebookAuthor','metaEbook,textbook,ebook');
}

//Mac Apps
if($media=='macSoftware'){
   $entity = array('softwareDeveloper','macSoftware');
}

//MUSICA
if($media=='music'){
   $entity = array('musicArtist','song','album','musicVideo');
}

//PODCAST
if($media=='podcast'){
   $entity = array('musicArtist','podcastAuthor','podcast');
}

//VIDEO
if($media=='musicVideo'){
   $entity = array('musicVideoArtist','musicVideo');
}

Se volete richiamare direttamente il mio script PHP, senza passare dalla form di esempio su linkata (magari per farvi restituire un JSON da utilizzare nelle vostre app), eccovi la URL diretta:

  • http://francescoficetola.it/link-maker/linkmaker.php?term=%s&country=%s&media=%s&limit=%s&genreId=%s

I valori ammissibili da passare sono quelli espressi precedentemente e di seguito riassunti:

  • media: audiobook, shortFilm, movie, software, ebook, macSoftware, music, podcast, musicVideo
  • country: IT, US, UK, ecc.
  • term: la vostra query di ricerca (ad esempio, Oasis what’s the story morning glory”)
  • limit: (opzionale, di default è impostato a 50) determina il numero massimo di risultati che occorre restituire per ognuna delle combinazioni di URL di ricerca richiamate da Apple, in base al media impostato.
  • genreId: (opzionale) codice del genere degli item, il cui valore ammissibile è disponibile nel dizionario lmMediaTypeAndGenreDictionaries fornito da Apple.

Le combinazioni di entity sono definite direttamente nello script e non occorre specificare il parametro in input.

Ecco un esempio di ricerca:

http://francescoficetola.it/link-maker/linkmaker.php?term=jovanotti+bella&country=IT&media=music&limit=50&genreId=14