rem42 / scraper-itunes

v1.0 2018-08-28 13:44 UTC

Requires

• php: >=5.5.9
• doctrine/common: ^2.8
• jms/serializer-bundle: ^2.0
• rem42/scraper: ^1.0
• symfony/dom-crawler: ^3.0

MIT

• rem42

Published on Packagist.org on 2018-08-28 13:45 UTC

README

Scraper for the public iTunes Search API (no API key required): search by movie, music, tvShow, software and ebook, lookup by identifier and App Store customer reviews.

Installation

composer require rem42/scraper-itunes

Requirement

• PHP >= 8.4
• rem42/scraper ^3.4

Usage

use Scraper\Scraper\Client;
use Scraper\ScraperItunes\Enum\ItunesMovieEntity;
use Scraper\ScraperItunes\Enum\ItunesReviewSort;
use Scraper\ScraperItunes\Request\ItunesAppRequest;
use Scraper\ScraperItunes\Request\ItunesCustomerReviewsRequest;
use Scraper\ScraperItunes\Request\ItunesMovieSearchRequest;
use Scraper\ScraperItunes\Request\ItunesSoftwareSearchRequest;

$client = new Client($httpClient); // any Symfony HttpClientInterface

// Typed search: the media is fixed, the entity and attribute are enums
$search = $client->send(
    (new ItunesMovieSearchRequest())
        ->setTerm('inception')
        ->setCountry('FR')
        ->setEntity(ItunesMovieEntity::Movie)
        ->setLimit(5)
);
$search->resultCount;
$search->results; // array<Movie>

// App Store
$apps = $client->send((new ItunesSoftwareSearchRequest())->setTerm('instagram')->setCountry('FR'));

// Lookup of one application (returns a Software)
$app = $client->send((new ItunesAppRequest())->setId(389801252)->setCountry('FR'));

// Customer reviews
$reviews = $client->send(
    (new ItunesCustomerReviewsRequest())->setId(389801252)->setLang('fr')->setSortBy(ItunesReviewSort::MostRecent)
);
$reviews->reviews;

Search requests

Request	media	entity enum	attribute enum
ItunesMovieSearchRequest	movie	ItunesMovieEntity	ItunesMovieAttribute
ItunesMusicSearchRequest	music	ItunesMusicEntity	ItunesMusicAttribute
ItunesTvShowSearchRequest	tvShow	ItunesTvShowEntity	ItunesTvShowAttribute
ItunesSoftwareSearchRequest	software	ItunesSoftwareEntity	ItunesSoftwareAttribute
ItunesEbookSearchRequest	ebook	ItunesEbookEntity	ItunesEbookAttribute
ItunesSearchRequest	any (ItunesMedia, podcast, audiobook...)	string or enum	string or enum

Common parameters: setTerm(), setCountry(), setLimit() (1-200), setLang(), setVersion(), setExplicit().

Results are mapped from their kind / wrapperType:

Model	Result
Movie	feature-movie
Song	song
MusicVideo	music-video
Album	collection (album)
MusicArtist	artist
TvEpisode	tv-episode
TvSeason	collection (TV Season)
Software	software, mac-software
Ebook	ebook
ItunesResult	any other type (common fields only)

Other requests

Request	Endpoint	Returns
ItunesLookupRequest	itunes.apple.com/lookup	ItunesSearch
ItunesAppRequest	itunes.apple.com/lookup	Software
ItunesCustomerReviewsRequest	itunes.apple.com/{cc}/rss/customerreviews/.../json	CustomerReview

Upgrading from the legacy version

• Sources moved to src/, namespace Scraper\ScraperItunes\ is unchanged; Entity\* became Model\* (public typed properties instead of getters/setters).
• App / SoftwareSearch are replaced by Software.
• Search setMedia() / setEntity() take enums (strings are still accepted by the generic ItunesSearchRequest).
• Customer reviews now use the JSON feed instead of the XML one; the application header entry (ReviewSoftware) is no longer exposed.