* @license MIT License */ class EchoNest_Api_Catalog extends EchoNest_Api { /** * Creates a catalog. * http://developer.echonest.com/docs/v4/catalog.html#create * * @param string $name The name of the catalog * @param string $type The type of the catalog (artist or song) * @return array response object */ public function create($name, $type) { $response = $this->client->post('catalog/create', array( 'name' => $name, 'type' => $type )); return $this->returnResponse($response); } /** * Updates (adds or deletes) items from a catalog. The body of the post should include an item block that describes modifications to the catalog. * When a catalog is updated, the contents of the catalog are resolved to Echo Nest IDs. This resolving process happens asynchronously to the call. The update method returns a 'ticket' that can be used with the catalog/status call to check on the status of the update * http://developer.echonest.com/docs/v4/catalog.html#update * * @param string $id The ID of the catalog * @param string $data_type The type of data to be uploaded (json, itunes, xspf, m3u) * @param string $data The data to be uploaded (data in the form specified by 'data_type') * @return array response object */ public function update($id, $data, $data_type = 'json') { $response = $this->client->post('catalog/update', array( 'id' => $id, 'data' => $data, 'data_type' => $data_type, )); return $this->returnResponse($response); } /** * Checks the status of a catalog update. * http://developer.echonest.com/docs/v4/catalog.html#status * * @param string $ticket The ticket to check (returned by upload or update) * @return array response object */ public function status($ticket) { $response = $this->client->get('catalog/status', array( 'ticket' => $ticket, )); return $this->returnResponse($response); } /** * Get basic information on a catalog * http://developer.echonest.com/docs/v4/catalog.html#profile * * @param string $id The ID or name of the catalog * @param bool $byName If the name of the catalog is used as the first argument, this must be set to true * @return array response object */ public function profile($id, $byName = false) { $response = $this->client->get('catalog/profile', array( $byName ? 'name' : 'id' => $id, )); return $this->returnResponse($response, 'catalog'); } /** * Returns all of the data stored in the catalog. Also returns Echo Nest IDs for items that have been resolved to Echo Nest IDs along with information requested via bucket. * http://developer.echonest.com/docs/v4/catalog.html#read * * @param string $id The ID of the catalog * @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 * @return array response object */ public function read($id, $results = 15, $start = 0, $bucket = null) { $response = $this->client->get('catalog/read', array( 'id' => $id, 'results' => $results, 'start' => $start, 'bucket' => $bucket, )); return $this->returnResponse($response, 'catalog'); } /** * Returns feeds based on the artists in a personal catalog. Unlike catalog/read method, the catalog/feed method interleaves items and sorts them by date. * http://developer.echonest.com/docs/v4/catalog.html#feed * * @param string $id The ID of the catalog * @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 string $since limit the items to those that have occurred since the given date (YYYY-mm-dd) * @return array response object */ public function feed($id, $results = 15, $start = 0, $bucket = null, $since = null) { $response = $this->client->get('catalog/feed', array( 'id' => $id, 'results' => $results, 'start' => $start, 'bucket' => $bucket, 'since' => $since, )); return $this->returnResponse($response, 'feed'); } /** * Deletes the entire catalog. Only the API key used to create a catalog can be used to delete that catalog. * http://developer.echonest.com/docs/v4/catalog.html#delete * * @param string $id The ID of the catalog * @return array response object */ public function delete($id) { $response = $this->client->post('catalog/delete', array( 'id' => $id, )); return $this->returnResponse($response); } /** * Returns a list of all taste profiles that are similar to the given set of taste profiles. * This method returns similar taste profiles of the given use type. * Similarity search is restricted to taste profiles that were created with the caller's API key. * http://developer.echonest.com/docs/v4/catalog.html#similar-beta * * @param string $id The ID of the catalog * @return array response object */ public function similar($id) { $response = $this->client->get("catalog/similar", array( "id" => $id )); return $this->returnResponse($response); } /** * Returns a list of all catalogs created on this key * http://developer.echonest.com/docs/v4/catalog.html#list * * @param integer $results the number of results desired (0 < $results < 100) * @param string $start the desired index of the first result returned * @return array response object */ public function getList($results = 15, $start = 0) { $response = $this->client->get('catalog/list', array( 'results' => $results, 'start' => $start, )); return $this->returnResponse($response, 'catalogs'); } }