API calls for accessing Premium Content Sandboxes
A Premium Content Sandbox (PCS) is a collection of licensed content that is made available to developers. Typically, a PCS contains content such as audio, video, and images associated with a single album release or for a single artist. Developers that wish to build an application based upon a PCS must apply for and receive approval for access and agree to a PCS-specific Terms of Service that outlines the conditions for the development and publishing of a PCS-based application. Access to some content in a PCS will be controlled to prevent unauthorized distribution or use.
Access to a PCS typically is more tightly controlled than the standard Echo Nest API. Since a PCS contains premium, licensed assets, content owners need assurance that their assets will not be abused. Additionally, some content owners may wish to retain publishing rights to any applications that are based upon a PCS. It is important for you as a developer to make sure you fully understand all restrictions around a PCS before you begin development.
For more information on the available set of Premium Content Sandboxes visit the Premium Content SandBox page.
Lists detailed information about each asset in the sandbox. This method describes each asset in detail but does not provide direct access to the assets. This method does not require an approved API key. Note that different sandboxes may return different sets of data and metadata.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key. format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests sandbox yes no emi_evanescence The name of the sandbox results no no 0 < results < 100, (Default=15) the number of results desired start no no 0, 15, 30 the desired index of the first result returned Example query:
http://developer.echonest.com/api/v4/sandbox/list?api_key=YOUR_API_KEY&sandbox=emi_evanescence&results=2Here is an example response:
{ "response": { "status": { "code": 0, "message": "Success", "version": "4.2" }, "start": 0, "total": 455, "assets": [ { "explicit": false, "filename": "emi_evanescence/EMIDV1141615-videopreview.mpg", "id": "2d2b8d352d6f2bc8297266117116421d", "title": "Going Under (Video)", "type": "preview_video", "year": "2010" }, { "echonest_ids": [ { "foreign_id": "emi_artists:track:EMIDD1342735", "id": "TRFQBKY133B7EA9267" } ], "filename": "emi_evanescence/EMIDD1342735.mp3", "id": "5553fc4381551053345a8311878b8d94", "release": "Evanescence (Deluxe Edition)", "title": "Erase This", "type": "audio" } ], } }
Gets access to the listed assets. This method returns a secure token or URL that can be used by the application to access the asset. This method requires an API key that has been approved for the sandbox.
Parameter Required? Multiple? Values Description api_key yes no YOUR_API_KEY your API key format no no json, xml, jsonp The desired format of the response callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests sandbox yes no emi_evanescence The name of the sandbox id yes yes AB1234-2 The ID of the asset oauth_nonce yes no AbEBbadbabaABdba A random string of characters that differs from call to call and is never repeated in a 10 minute window. oauth_timestamp yes no 1321123421 The number of seconds elapsed since midnight, 1 January 1970. Be sure this is within ten minutes of the real time. You can get the current timestamp that the Echo Nest API is using by via the oauth/timestamp method oauth_version yes no 1.0 The oauth version. Provides the version of the authentication process as defined in the oauth specification. oauth_signature_method yes no HMAC-SHA1 Algorithm used to generate the signature. Supported methods are HMAC-SHA1 oauth_consumer_key yes no b30f027ead14e3056d8844b9e792a526 The consumer key used to sign calls oauth_signature yes no tR3+Ty81lMeYAr/Fid0kMTYa/WM= The cryptographic signature for the method call. Calls are signed using your consumer key, your shared secret, the HTTP method and an encoded version of the base string of the URL. Warning
This method requires a cryptographic signature. See Oauth API Methods for information about how to sign requests.
Example query:
http://developer.echonest.com/api/v4/sandbox/access?api_key=YOUR_API_KEY&sandbox=emi_evanescence&id=AB1234-2&id=AB1234-1&oauth_consumer_key=b30f027ead14e3056d8833b9e783a526&oauth_nonce=1234367&oauth_timestamp=1319830594&oauth_signature_method=HMAC-SHA1&oauth_signature=tR3+Ty81lMeYAr/Fid0kMTYa/WM=&oauth_version=1.0Here is an example response:
{ "response": { "status": { "version": "4.2", "code": 0, "message": "Success" }, "assets": [ { "url": "http://assets-cdn.echonest.com/emi_evanescence/TRVXTFV123E858A357.mp3?Expires=1319130782&Signature=Py4Eul8uB2-eEjphGLjEAKIN-Ecpu-OWrox7I4jnvvjFJH6AX0Yz80QUUvhCQxZr-gDns5LZqiIyk5YQMGvhJIMAIQFnVToDEcUVoiS6z3RTr9~vbOYscxw2b2~niS7ELxHBlHUXrc5GVzoWujb1sQBp0B0TxVl4Y-Fo4swf8-M_&Key-Pair-Id=APKAI7GSQ2RBQERQWBOA", "id": "c1b89c9b9e0ee9e53650f1d4e393d716" }, { "url": "http://assets-cdn.echonest.com/emi_evanescence/TRRSUVX123E858D3A6.mp3?Expires=1319130782&Signature=I4VvE3D4XTD6UpZPZJCHTXoFtj2-mn5Nvn~OseucT01iv3vhAsqtOca1NsYU6cJH9sRTJElGF0W3tX3PuAeP0hyY-6B~d8g0l~Jp4~pMhyZebAJYX3mPL0hhRY9OziFQNYlLc0-991T0sM9uLFsBZl3Mdbtqfpfh6QaWuQjN-GU_&Key-Pair-Id=APKAI7GSQ2RBQERQWBOA", "id": "67d0bf343b70b19e7a6de496dc2ab126" } ] } }