mirror of
https://github.com/Yetangitu/ampache
synced 2025-10-04 18:29:40 +02:00
428 lines
19 KiB
PHP
428 lines
19 KiB
PHP
<?php
|
|
|
|
/**
|
|
* Api calls for getting data about artists.
|
|
*
|
|
* @link http://developer.echonest.com/docs/v4/artist.html
|
|
* @author Brent Shaffer <bshafs at gmail dot com>
|
|
* @license MIT License
|
|
*/
|
|
class EchoNest_Api_Artist extends EchoNest_Api
|
|
{
|
|
/**
|
|
* Set the artist id. The artist name OR the artist ID is required for many of the methods in this API
|
|
*
|
|
* @param string $id the artist ID. An Echo Nest ID or a Rosetta Stone ID
|
|
* @return EchoNestApiArtist the current object instance
|
|
*/
|
|
public function setId($id)
|
|
{
|
|
return $this->setOption('id', $id);
|
|
}
|
|
|
|
/**
|
|
* Set the artist name. The artist name OR the artist ID is required for many of the methods in this API
|
|
*
|
|
* @param string $name the artist name
|
|
* @return EchoNestApiArtist the current object instance
|
|
*/
|
|
public function setName($name)
|
|
{
|
|
return $this->setOption('name', $name);
|
|
}
|
|
|
|
/**
|
|
* Get a list of audio documents found on the web related to an artist.
|
|
* http://developer.echonest.com/docs/v4/artist.html#audio
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param integer $start the desired index of the first result returned
|
|
* @return array list of audio documents found
|
|
*/
|
|
public function getAudio($results = 15, $start = 0)
|
|
{
|
|
$response = $this->getForArtist('artist/audio', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'audio');
|
|
}
|
|
|
|
/**
|
|
* Get a list of artist biographies.
|
|
* http://developer.echonest.com/docs/v4/artist.html#biographies
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param integer $start the desired index of the first result returned
|
|
* @param string|array $license the desired licenses of the returned biographies
|
|
* @return array list of biographies found
|
|
*/
|
|
public function getBiographies($results = 15, $start = 0, $license = null)
|
|
{
|
|
$response = $this->getForArtist('artist/biographies', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
'license' => $license,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'biographies');
|
|
}
|
|
|
|
/**
|
|
* Get a list of blog articles related to an artist.
|
|
* http://developer.echonest.com/docs/v4/artist.html#blogs
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param integer $start the desired index of the first result returned
|
|
* @param bool $high_relevance if true only items that are highly relevant for this artist will be returned
|
|
* @return array list of blogs found
|
|
*/
|
|
public function getBlogs($results = 15, $start = 0, $high_relevance = false)
|
|
{
|
|
$response = $this->getForArtist('artist/blogs', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
'high_relevance' => $high_relevance,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'blogs');
|
|
}
|
|
|
|
/**
|
|
* Get our numerical estimation of how familiar an artist currently is to the world.
|
|
* http://developer.echonest.com/docs/v4/artist.html#familiarity
|
|
*
|
|
* @param string $id the artist ID. An Echo Nest ID or a Rosetta Stone ID
|
|
* @return decimal
|
|
*/
|
|
public function getFamiliarity()
|
|
{
|
|
$response = $this->getForArtist('artist/familiarity');
|
|
|
|
return $this->returnResponse($this->returnResponse($response, 'familiarity'), 'artist');
|
|
}
|
|
|
|
/**
|
|
* Returns our numerical description of how hottt an artist currently is. Contact us at biz@echonest.com for information on how to obtain additional hotttnesss information, including historical hotttnesss data for each artist and a detailed breakdown of hotttnesss into editorial, social and mainstream categories.
|
|
* http://developer.echonest.com/docs/v4/artist.html#hotttness
|
|
*
|
|
* @param string $type controls the type of hotttnesss that is used (overall, social, reviews, mainstream)
|
|
* @return decimal
|
|
*/
|
|
public function getHotttnesss($type = 'overall')
|
|
{
|
|
$response = $this->getForArtist('artist/hotttnesss', array(
|
|
'type' => $type,
|
|
));
|
|
|
|
return $this->returnResponse($this->returnResponse($response, 'hotttnesss'), 'artist');
|
|
}
|
|
|
|
/**
|
|
* Get a list of artist images.
|
|
* http://developer.echonest.com/docs/v4/artist.html#images
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param integer $start the desired index of the first result returned
|
|
* @param string|array $license the desired licenses of the returned images
|
|
* @return array array of images found
|
|
*/
|
|
public function getImages($results = 15, $start = 0, $license = null)
|
|
{
|
|
$response = $this->getForArtist('artist/images', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
'license' => $license,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'images');
|
|
}
|
|
|
|
/**
|
|
* Get a list of news articles found on the web related to an artist.
|
|
* http://developer.echonest.com/docs/v4/artist.html#news
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param integer $start the desired index of the first result returned
|
|
* @param bool $high_relevance if true only news articles that are highly relevant for this artist will be returned
|
|
* @return array array of news articles found
|
|
*/
|
|
public function getNews($results = 15, $start = 0, $high_relevance = false)
|
|
{
|
|
$response = $this->getForArtist('artist/news', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
'high_relevance' => $high_relevance,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'news');
|
|
}
|
|
|
|
/**
|
|
* Get basic information on an artist: the name, the Echo Nest ID, and the MusicBrainz ID.
|
|
* http://developer.echonest.com/docs/v4/artist.html#profile
|
|
*
|
|
* @param string|array $bucket indicates what data should be returned with each artist. possible values include:
|
|
* - audio returns up to the 15 most recent audio documents found on the web related to the artist
|
|
* - biographies returns up to the 15 most recent biographies found on the web related to the artist
|
|
* - blogs returns up to the 15 most recent blogs found on the web related to the artist
|
|
* - docs_count returns document counts for each of the various artist document types
|
|
* - familiarity returns the familiarity for the artist
|
|
* - hotttnesss returns the hotttnesss for the artist
|
|
* - images returns up to the 15 most recent images found on the web related to the artist
|
|
* - news returns up to the 15 most recent news articles found on the web related to the artist
|
|
* - reviews returns up to the 15 most recent reviews found on the web related to the artist
|
|
* - songs returns up to the 15 hotttest songs for the artist
|
|
* - terms returns links to this artist's pages on various sites
|
|
* - urls returns up to the 15 most recent videos found on the web related to the artist
|
|
* - video returns up to the 15 most recent videos found on the web related to the artist
|
|
* - years_active returns years active information for the artist
|
|
* - id:[rosetta-catalog] returns catalog specific information about the artist for the given catalog. See Project Rosetta Stone for details
|
|
* - id:[Personal-Catalog-ID] returns personal catalog specific information about the artist for the given catalog. See Project Rosetta Stone for details
|
|
* - id:musicbrainz
|
|
* - id:playme
|
|
* - id:7digital
|
|
* @return array array of information
|
|
*/
|
|
public function getProfile($bucket = null)
|
|
{
|
|
$response = $this->getForArtist('artist/profile', array(
|
|
'bucket' => $bucket,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'artist');
|
|
}
|
|
|
|
/**
|
|
* Get reviews related to an artist's work.
|
|
* http://developer.echonest.com/docs/v4/artist.html#reviews
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param string $start the desired index of the first result returned
|
|
* @return array array of news articles found
|
|
*/
|
|
public function getReviews($results = 15, $start = 0)
|
|
{
|
|
$response = $this->getForArtist('artist/reviews', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'reviews');
|
|
}
|
|
|
|
/**
|
|
* Search artists.
|
|
* http://developer.echonest.com/docs/v4/artist.html#search
|
|
* @param array $options visit the documentation above to see all available options. Some options include:
|
|
* - $bucket audio, biographies, blogs, familiarity, hotttnesss, images, news, reviews, terms, urls, video, id:CA1234123412341234, id:musicbrainz, id:playme, or id:7digital indicates what data should be returned with each artist
|
|
* - $limit if true, limit the results to the given idspace or catalog
|
|
* - $name the name of the artist to search for
|
|
* - $description a description of the artist (alt-rock,-emo,harp^2)
|
|
* - $fuzzy_match if true, a fuzzy search is performed
|
|
* - $max_familiarity the maximum familiarity for returned artists (0.0 < familiarity < 1.0)
|
|
* - $min_familiarity the minimum familiarity for returned artists (0.0 < familiarity < 1.0)
|
|
* - $max_hotttnesss the maximum hotttnesss for returned artists (0.0 < hotttnesss < 1.0)
|
|
* - $min_hotttnesss the minimum hotttnesss for returned artists (0.0 < hotttnesss < 1.0)
|
|
* - $sort sort terms based upon weight or frequency (familiarity-asc, hotttnesss-asc, familiarity-desc, hotttnesss-desc)
|
|
* @return array array of search results
|
|
*/
|
|
public function search($options = array())
|
|
{
|
|
$response = $this->get('artist/search', $options);
|
|
|
|
return $this->returnResponse($response, 'artists');
|
|
}
|
|
|
|
/**
|
|
* Extract artist names from text.
|
|
* http://developer.echonest.com/docs/v4/artist.html#extract-beta
|
|
*
|
|
* @param string $text the text to search for an artist's name
|
|
* @param array $options visit the documentation above to see all available options. Some options include:
|
|
* - format The format of the response (json, xml, jsonp). JSON by default.
|
|
* - results The Number of results desired, 0 < results < 1000, (Default=15)
|
|
* - limit If true, limit the results to the given idspace or catalog
|
|
* - max_familiarity The maximum familiarity for returned artists (0.0 < familiarity < 1.0)
|
|
* - min_familiarity The minimum familiarity for returned artists (0.0 < familiarity < 1.0)
|
|
* - max_hotttnesss The maximum hotttnesss for returned artists (0.0 < hotttnesss < 1.0)
|
|
* - min_hotttnesss The minimum hotttnesss for returned artists (0.0 < hotttnesss < 1.0)
|
|
* - sort Sort terms based upon weight or frequency (familiarity-asc, hotttnesss-asc, familiarity-desc, hotttnesss-desc)
|
|
* - callback Required for jsonp requests. the callback function for JSONP requests.
|
|
* @return array array of news articles found
|
|
*/
|
|
public function extract($text, $options = array())
|
|
{
|
|
$options['text'] = $text;
|
|
|
|
$response = $this->get('artist/extract', $options);
|
|
|
|
return $this->returnResponse($response, 'artists');
|
|
}
|
|
|
|
/**
|
|
* Get a list of songs created by an artist.
|
|
* http://developer.echonest.com/docs/v4/artist.html#songs
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param string $start the desired index of the first result returned
|
|
* @return array array of news articles found
|
|
*/
|
|
public function getSongs($results = 15, $start = 0)
|
|
{
|
|
$response = $this->getForArtist('artist/songs', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'songs');
|
|
}
|
|
|
|
/**
|
|
* Return similar artists given one or more artists for comparison. The Echo Nest provides up-to-the-minute artist similarity and recommendations from their real-time musical and cultural analysis of what people are saying across the Internet and what the music sounds like.
|
|
* http://developer.echonest.com/docs/v4/artist.html#similar
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param integer $min_results Indicates the minimum number of results to be returned regardless of constraints (0 < $results < 100)
|
|
* @param integer $start the desired index of the first result returned
|
|
* @param string|array $bucket indicates what data should be returned with each artist
|
|
* @param decimal $max_familiarity the maximum familiarity for returned artists (0.0 < familiarity < 1.0)
|
|
* @param decimal $min_familiarity the minimum familiarity for returned artists (0.0 < familiarity < 1.0)
|
|
* @param decimal $max_hotttnesss the maximum hotttnesss for returned artists (0.0 < hotttnesss < 1.0)
|
|
* @param decimal $min_hotttnesss the minimum hotttnesss for returned artists (0.0 < hotttnesss < 1.0)
|
|
* @param bool $limit if true, limit the results to the given idspace or catalog
|
|
* @param string|array $seed_catalog only give similars to those in a catalog or catalogs, An Echo Nest artist catalog identifier
|
|
* @return array array of similar artists found
|
|
* @see getProfile
|
|
*/
|
|
public function getSimilar($results = 15, $min_results = 15, $start = 0, $bucket = null,
|
|
$max_familiarity = 1.0, $min_familiarity = 0.0, $max_hotttness = 1.0, $min_hotttness = 0.0,
|
|
$reverse = false, $limit = false, $seed_catalog = null)
|
|
{
|
|
$response = $this->getForArtist('artist/similar', array(
|
|
'results' => $results,
|
|
'min_results' => $min_results,
|
|
'start' => $start,
|
|
'bucket' => $bucket,
|
|
'max_familiarity' => $max_familiarity,
|
|
'min_familiarity' => $min_familiarity,
|
|
'max_hotttnesss' => $max_hotttness,
|
|
'min_hotttnesss' => $min_hotttness,
|
|
'limit' => $limit,
|
|
'seed_catalog' => $seed_catalog
|
|
));
|
|
|
|
return $this->returnResponse($response, 'artists');
|
|
}
|
|
|
|
/**
|
|
* Get a list of most descriptive terms for an artist
|
|
* http://developer.echonest.com/docs/v4/artist.html#terms
|
|
*
|
|
* @param string $sort sort terms based upon weight or frequency (can be either "weight" or "frequency")
|
|
* @return array array of descriptive terms found
|
|
*/
|
|
public function getTerms($sort = 'frequency')
|
|
{
|
|
$response = $this->getForArtist('artist/terms', array(
|
|
'sort' => $sort,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'terms');
|
|
}
|
|
|
|
/**
|
|
* Return a list of the top hottt artists.
|
|
* http://developer.echonest.com/docs/v4/artist.html#top-hottt
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param string $start the desired index of the first result returned
|
|
* @param string|array $bucket indicates what data should be returned with each artist
|
|
* @param bool $limit if true artists will be limited to those that appear in the catalog specified by the id: bucket
|
|
* @return array array of top hottt found. Data varies according to $bucket
|
|
* @see getProfile
|
|
*/
|
|
public function getTopHottt($results = 15, $start = 0, $bucket = null, $limit = false)
|
|
{
|
|
$response = $this->get('artist/top_hottt', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
'bucket' => $bucket,
|
|
'limit' => $limit,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'artists');
|
|
}
|
|
|
|
/**
|
|
* Returns a list of the overall top terms. Up to 1,000 terms can be returned.
|
|
* http://developer.echonest.com/docs/v4/artist.html#top-terms
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 1000)
|
|
* @return array array of top terms
|
|
*/
|
|
public function getTopTerms($results = 15)
|
|
{
|
|
$response = $this->get('artist/top_hottt', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
'bucket' => $bucket,
|
|
'limit' => $limit,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'terms');
|
|
}
|
|
|
|
/**
|
|
* Get links to the artist's official site, MusicBrainz site, MySpace site, Wikipedia article, Amazon list, and iTunes page.
|
|
* http://developer.echonest.com/docs/v4/artist.html#urls
|
|
*
|
|
* @return array array of urls for an artist
|
|
*/
|
|
public function getUrls()
|
|
{
|
|
$response = $this->getForArtist('artist/urls');
|
|
|
|
return $this->returnResponse($response, 'urls');
|
|
}
|
|
|
|
/**
|
|
* Get links to the artist's official site, MusicBrainz site, MySpace site, Wikipedia article, Amazon list, and iTunes page.
|
|
* http://developer.echonest.com/docs/v4/artist.html#video
|
|
*
|
|
* @param integer $results the number of results desired (0 < $results < 100)
|
|
* @param string $start the desired index of the first result returned
|
|
* @return array array of urls for an artist
|
|
*/
|
|
public function getVideo($results = 15, $start = 0)
|
|
{
|
|
$response = $this->getForArtist('artist/video', array(
|
|
'results' => $results,
|
|
'start' => $start,
|
|
));
|
|
|
|
return $this->returnResponse($response, 'video');
|
|
}
|
|
|
|
/**
|
|
* Send a GET request for an artist.
|
|
* This is for when an id or name attribute are required
|
|
*/
|
|
protected function getForArtist($path, array $parameters = array(), array $options = array())
|
|
{
|
|
if (!isset($parameters['id'], $parameters['name'])) {
|
|
if ($id = $this->getOption('id')) {
|
|
$parameters = array_merge(array('id' => $id), $parameters);
|
|
}
|
|
elseif ($name = $this->getOption('name')) {
|
|
$parameters = array_merge(array('name' => $name), $parameters);
|
|
}
|
|
else {
|
|
throw new Exception('This method requires an artist id or name. Please set this using the setId() or setName() methods on the Artist API');
|
|
}
|
|
}
|
|
|
|
return $this->get($path, $parameters, $options);
|
|
}
|
|
}
|