The Echonest API no longer exists, so sadly this project will merely live as an archive.
This addon provides an abstraction layer for accessing the Echo Nest V4 APIs via Ember-Data.
This project is intended to work with Ember-Data 2.x, so if you wish to use it with a previous version, please file an issue. If there is enough interest, we can work on handling older versions as well. Better yet, we'd love you to submit a PR adding this functionality!
EDEN uses the BabelJS polyfill for additional ES6 features (such as includes
),
so please make sure you have enabled it in your app!
In order to use this addon, you must register for an Echo Nest API Key. If you see three keys on your profile (API/Consumer/Shared Secret), you can ignore the other two (deprecated) and use the API Key.
Note: API Keys are intended for non-commercial use. If you intend to make more money than simply covering your hosting costs, please contact Echo Nest for licensing. I also highly recommend reviewing their API Ground Rules.
ember install ember-data-echonest
Once you have installed the addon, you need to add your API Key to the ENV config. We highly recommend using
ember-cli-dotenv to save your key to a .env
file so that
you don't have to upload it to your project repo. I've called mine ECHONEST_KEY
, and you can view the
demo app's config
to see how I've injected the key.
The addon exposes a number of models, adapters, and serializers you can use to access data from the Echo Nest API. If a particular API is not supported, please review our issue list and create a new one if it has not yet been requested. Contributions especially welcome!
If you have not already, update your application to include the BabelJS Polyfill for new ES6 features such as includes
:
//ember-cli-build.js
new EmberApp(defaults, {
babel: {
includePolyfill: true
}
});
Each section below details the usage of a particular type of data provided by Echo Nest. Within these sections are specific methods used for retrieving that model type. In order to utilize these APIs, you must pass the name of the method you wish to use for your request:
this.store.query('echonest-genre', {
method: 'list'
});
This parameter must be passed in order for Ember-Data-Echonest to know how to construct the proper request url.
Many of the APIs have additional query params called buckets that allow you to specify additional information to be
returned in the response. In order to use these buckets, you would pass a query param bucket
to Ember-Data with
an array of strings containing the names of each bucket to be included. Every model type has the same buckets available,
unless otherwise noted.
Artist buckets are supported by the following methods: extract
, profile
, search
, similar
, top_hottt
biographies
- Returns up to the 15 most recent biographies found on the web related to the artistblogs
- Returns up to the 15 most recent blogs found on the web related to the artistdiscovery
- Returns the discovery score for the artist. This is a measure of how unexpectedly popular the artist isdiscovery_rank
- Returns the discovery rank for the artistdoc_counts
- Returns document counts for each of the various artist document typesfamiliarity
- Returns the familiarity for the artistfamiliarity_rank
- Returns the familiarity rank for the artistgenre
- Returns all genres for an artisthotttnesss
- Returns the hotttnesss for the artisthotttnesss_rank
- Returns the hotttnesss rank for the artistimages
- Returns up to the 15 most recent images found on the web related to the artistartist_location
- Returns information about the location of origin for the artistnews
- Returns up to the 15 most recent news articles found on the web related to the artistreviews
- Returns up to the 15 most recent reviews found on the web related to the artistsongs
- Returns up to the 15 hotttest songs for the artisturls
- Returns links to this artist's pages on various sitesvideo
- Returns up to the 15 most recent videos found on the web related to the artistyears_active
- Returns years active information for the artist
this.store.queryRecord('echonest-artist', {
method: 'profile',
name: 'Calvin Harris',
bucket: ['biographies', 'images', 'urls']
});
Returns a list of artist biographies
this.store.query('echonest-biography', {
name: 'Weezer'
});
Returns a list of blog articles related to an artist
this.store.query('echonest-blog', {
name: 'Deadmau5'
});
Extract artist names from text
this.store.query('echonest-artist', {
method: 'extract'
text: 'I love Taylor Swift and Kanye West both, why do they keep fighting? I wish they would collab with Eminem!'
});
sort: Categories to sort by - familiarity-asc, hotttnesss-asc, familiarity-desc, hotttnesss-desc, artist_start_year-asc, artist_start_year-desc, artist_end_year-asc, artist_end_year-desc
this.store.query('echonest-artist', {
method: 'extract',
text: 'I love Taylor Swift and Kanye West both, why do they keep fighting? I wish they would collab with Eminem!',
sort: 'hotttnesss-desc'
});
max_familiarity: The maximum familiarity for artists returned from the query (0-1, Default: 1) min_familiarity: The minimum familiarity for artists returned from the query (0-1, Default: 0) max_hotttnesss: The maximum hotttnesss for artists returned from the query (0-1, Default: 1) min_hotttnesss: The minimum hotttnesss for artists returned from the query (0-1, Default: 0)
this.store.query('echonest-artist', {
method: 'extract',
text: 'I love Taylor Swift and Kanye West both, why do they keep fighting? I wish they would collab with Eminem!',
min_familiarity: .7
});
results: Number of desired results (0-100, Default: 15)
this.store.query('echonest-artist', {
method: 'extract',
text: 'I love Taylor Swift and Kanye West both, why do they keep fighting? I wish they would collab with Eminem!',
results: 75
});
Returns a numerical estimation of how familiar an artist is currently
this.store.queryRecord('echonest-artist', {
method: 'familiarity',
name: 'Radiohead'
});
An artist name
or id
can be provided. For example:
this.store.queryRecord('echonest-artist', {
method: 'familiarity',
id: 'ARH6W4X1187B99274F'
});
List the top artists for a given genre
this.store.query('echonest-artist', {
method: 'genre',
name: 'Rock'
});
Note: The API docs indicate the artist buckets are supported; however, testing has shown this to throw a 500 error.
Returns a numerical description of how hottt an artist is currently
this.store.queryRecord('echonest-artist', {
method: 'hotttnesss',
name: 'Taylor Swift'
});
An artist name
or id
can be provided. For example:
this.store.queryRecord('echonest-artist', {
method: 'hotttnesss',
id: 'ARH6W4X1187B99274F'
});
type: Controls the type of hotttnesss that is used (overall, social, reviews, mainstream, Default: overall)
Note: As of yet we have been unable to ascertain the usefulness of this parameter. All tests of the API have returned the same results for an artist regardless of type.
this.store.queryRecord('echonest-artist', {
method: 'hotttnesss',
name: 'Taylor Swift',
type: 'mainstream'
});
Returns a list of images related to an artist
this.store.query('echonest-image', {
name: 'Taylor Swift'
});
Returns basic profile information for an artist
this.store.queryRecord('echonest-artist', {
method: 'profile',
name: 'Taylor Swift'
});
An artist name
or id
can be provided. For example:
this.store.queryRecord('echonest-artist', {
method: 'profile',
id: 'ARH6W4X1187B99274F'
});
Returns a list of news articles related to an artist
this.store.queryRecord('echonest-news', {
name: 'Taylor Swift'
});
An artists id
can be provided instead of name
, as shown for other APIs.
high_relevance: Whether to only show highly relevant articles or all news mentioning the artist (Default: false) results: Number of desired results (0-100, Default: 15) start: Desired index of the first result returned (0+, Default: 0)
this.store.queryRecord('echonest-news', {
name: 'Taylor Swift',
high_relevance: true,
results: 50,
start: 15
});
Returns a list of album reviews related to an artist
this.store.queryRecord('echonest-reviews', {
name: 'Taylor Swift'
});
An artists id
can be provided instead of name
, as shown for other APIs.
results: Number of desired results (0-100, Default: 15) start: Desired index of the first result returned (0+, Default: 0)
this.store.queryRecord('echonest-reviews', {
name: 'Taylor Swift',
results: 75,
start: 10
});
Returns a list of artists matching the provided name
query
this.store.query('echonest-artist', {
name: 'Taylor Swift',
method: 'search'
});
fuzzy_match: Perform a fuzzy search on the query (Default: false)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
fuzzy_match: true
});
sort: Categories to sort by - familiarity-asc, hotttnesss-asc, familiarity-desc, hotttnesss-desc, artist_start_year-asc, artist_start_year-desc, artist_end_year-asc, artist_end_year-desc
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
sort: 'hotttnesss-desc'
});
description: Match artists by description
, such as style
or mood
(supports multiple)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
description: ['romantic', '00s']
});
style: Match artists by style
(supports multiple)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
style: ['country pop', '00s']
});
mood: Match artists by mood
(supports multiple)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
mood: ['romantic', 'party music']
});
rank_type: For matching by description
, style
, or mood
,
match by query relevance or artist familiarity rank (Default: relevance)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
mood: ['romantic'],
rank_type: 'familiarity'
});
genre: Match artists by genre
(supports multiple)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
genre: ['country pop', 'bluegrass']
});
artist_location: A location of interest in relation to the artist
query
Note: Location names can optionally be qualified with a type specifier of city
, region
or country
.
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
artist_location: 'city:Los Angeles+CA'
});
max_familiarity: The maximum familiarity for artists returned from the query (0-1, Default: 1) min_familiarity: The minimum familiarity for artists returned from the query (0-1, Default: 0) max_hotttnesss: The maximum hotttnesss for artists returned from the query (0-1, Default: 1) min_hotttnesss: The minimum hotttnesss for artists returned from the query (0-1, Default: 0)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
min_familiarity: .7
});
artist_start_year_before: Limit to artists whose first active year is before the provided year artist_start_year_after: Limit to artists whose first active year is after the provided year artist_end_year_before: Limit to artists whose last active year is before the provided year artist_end_year_after: Limit to artists whose last active year is after the provided year
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
artist_start_year_before: 2000
});
results: Number of desired results (0-100, Default: 15) start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
results: 75,
start: 10
});
Returns a list of artists matching the provided name
query
this.store.query('echonest-artist', {
name: 'Taylor Swift',
method: 'similar'
});
max_familiarity: The maximum familiarity for artists returned from the query (0-1, Default: 1) min_familiarity: The minimum familiarity for artists returned from the query (0-1, Default: 0) max_hotttnesss: The maximum hotttnesss for artists returned from the query (0-1, Default: 1) min_hotttnesss: The minimum hotttnesss for artists returned from the query (0-1, Default: 0)
this.store.query('echonest-artist', {
name: 'Taylor Swift',
method: 'similar',
min_familiarity: .7
});
artist_start_year_before: Limit to artists whose first active year is before the provided year artist_start_year_after: Limit to artists whose first active year is after the provided year artist_end_year_before: Limit to artists whose last active year is before the provided year artist_end_year_after: Limit to artists whose last active year is after the provided year
this.store.query('echonest-artist', {
name: 'Taylor Swift',
method: 'similar',
artist_start_year_after: 2000
});
results: Number of desired results (0-100, Default: 15) min_results: Minimum number of desired results (0-100, Default: 15) start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-artist', {
name: 'Taylor',
method: 'search',
results: 75,
start: 10
});
Suggest artist names based on a partial query
this.store.query('echonest-artist', {
method: 'suggest',
name: 'Tay'
});
results: Number of desired results (0-100, Default: 15)
this.store.query('echonest-artist', {
method: 'suggest',
name: 'Taylor',
results: 75
});
Returns a list of the top artists by hotttness_rank
this.store.query('echonest-artist', {
method: 'top_hottt'
});
results: Number of desired results (0-1000, Default: 15) start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-artist', {
method: 'top_hottt',
results: 75,
start: 10
});
genre: Filter results to artists from the selected genres
this.store.query('echonest-artist', {
method: 'top_hottt',
genre: ['rock', 'pop']
});
Retrieve an artist's Twitter handle
this.store.queryRecord('echonest-twitter', {
name: 'Ed Sheeran'
});
Retrieve links to artist profiles and official sites. Supports last.fm, MusicBrainz, Myspace, Twitter, and the artist's homepage.
this.store.queryRecord('echonest-urls', {
name: 'Ed Sheeran'
});
Note: Docs claim Wikipedia urls are supported & Twitter is completely undocumented for this API, but testing indicates otherwise.
Returns a list of videos related to an artist
this.store.query('echonest-video', {
name: 'Taylor Swift'
});
results: Number of desired results (0-100, Default: 15) start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-video', {
name: 'Taylor Swift',
results: 75,
start: 10
});
Descriptions of artists
Returns a list of the most relevant descriptions (along with their frequency and weight) for a given artist
this.store.query('echonest-description', {
method: 'artist',
name: 'Taylor Swift'
});
sort: Sort by weight or frequency (Default: frequency)
this.store.query('echonest-description', {
method: 'artist',
name: 'Taylor Swift',
sort: 'weight'
});
Returns a list of the best descriptive terms to use with search APIs. Allows two values for type
:
mood
- A mood or feeling associated with the music (ie 'aggressive', 'dreamy', or 'epic')style
- A genre or type of music (ie 'rock', 'classical', or '90s')
this.store.query('echonest-description', {
type: 'style'
});
Returns a list of the most frequent descriptive terms to use with search APIs.
this.store.query('echonest-description', {
method: 'top'
});
results
- Number of desired results (0-1000, Default: 15)
Note: The docs list 0-100 as allowed ranges, but testing has revealed up to 1000 results can be returned without error.
this.store.query('echonest-description', {
method: 'top',
results: 385
});
urls
- Include urls tied to the genre (generally wikipedia)description
- Include a text description of the genre
this.store.query('echonest-genre', {
method: 'something',
bucket: ['urls', 'description']
});
Returns a list of all available genres
this.store.query('echonest-genre', {
method: 'list'
});
Results: Number of desired results (0+, Default: 1000)
this.store.query('echonest-genre', {
name: 'rock',
method: 'search',
results: 75
});
Returns the profile of a single genre (as a list w/ a single item)
this.store.query('echonest-genre', {
method: 'profile',
name: 'rock'
});
Returns a list of genres matching the provided name
substring
this.store.query('echonest-genre', {
name: 'rock',
method: 'search'
});
results: Number of desired results (0+, Default: 15)
this.store.query('echonest-genre', {
name: 'rock',
method: 'search',
results: 75
});
Note: The Search API Docs indicate the default value for
results
is 100, but my testing indicates the actual default is 15. Additionally, they document a max value of 100,
but any value is respected.
Start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-genre', {
name: 'rock',
method: 'search',
start: 25
});
Returns a list of genres similar to the provided genre name
. An exact genre name must be provided to receive results.
this.store.query('echonest-genre', {
name: 'hard rock',
method: 'similar'
});
results: Number of desired results (0+, Default: 15)
this.store.query('echonest-genre', {
name: 'hard rock',
method: 'similar',
results: 75
});
Note: The Similar API Docs indicate the default value for
results
is 100, but my testing indicates the actual default is 15. Additionally, they document a max value of 100,
but any value is respected.
start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-genre', {
name: 'hard rock',
method: 'similar',
start: 10
});
Song buckets are supported by the following methods: profile
, search
audio_summary
- returns summary audio parameters for the songartist_discovery
- returns the discovery score for the song's artist. This is a measure of how unexpectedly popular the artist is.artist_discovery_rank
- returns the discovery rank for the song's artistartist_familiarity
- returns the familiarity for the song's artistartist_familiarity_rank
- returns the familiarity rank for the song's artistartist_hotttnesss
- returns the hotttnesss for the song's artistartist_hotttnesss_rank
- returns the hotttnesss rank for the song's artistartist_location
- returns information about the location of origin for the song's artistsong_currency
- returns the currency score of the song. This is a measure of how recently popular the song is.song_currency_rank
- returns the currency rank of the song.song_discovery
- returns the discovery score of the song. This is a measure of how unexpectedly popular the song is.song_discovery_rank
- returns the discovery rank of the song.song_hotttnesss
- returns the hotttnesss of the songsong_hotttnesss_rank
- returns the hotttnesss rank of the songsong_type
- returns a list of song types for the song. Possible song types returned are: 'christmas', 'live' 'studio', 'acoustic', and 'electric'tracks
- returns detailed track information for the song. You must also specify a Rosetta id space such as 7digital-US.id:rosetta-catalog
- returns catalog specific information about the song for the given catalog. See Project Rosetta Stone for details.id:Personal-Catalog-ID
- returns personal catalog specific information about the song for the given catalog. See Project Rosetta Stone for details.
this.store.query('echonest-song', {
method: 'search',
title: 'the lion sleeps tonight',
bucket: ['song_currency', 'song_discovery', 'song_hotttnesss', 'song_type']
});
Returns a list of songs released by the provided artist
this.store.query('echonest-song', {
method: 'artist',
name: 'Taylor Swift'
});
Artist id
can be used in place of name
results: Number of desired results (0-100, Default: 15) start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-song', {
method: 'artist',
name: 'Taylor Swift',
results: 100,
start: 15
});
Returns a list of songs matching the provided song ID(s)
this.store.query('echonest-song', {
method: 'profile',
id: 'SOYOUXP14DAE470D22'
});
Multiple IDs:
this.store.query('echonest-song', {
method: 'profile',
id: ['SOYOUXP14DAE470D22', 'SOORVLT13ADC025EF9']
});
Alternatively, one or more track_id
can be provided instead of the song id
:
this.store.query('echonest-song', {
method: 'profile',
id: 'TRTLKZV12E5AC92E11'
});
Returns a list of songs matching the provided query parameters
this.store.query('echonest-song', {
method: 'search',
title: 'bohemian rhapsody'
});
The parameters below can be used individually or in combination to refine the results:
title: The title of the song
this.store.query('echonest-song', {
method: 'search',
title: 'boom boom pow'
});
artist: The name of the primary artist
this.store.query('echonest-song', {
method: 'search',
artist: 'justin timberlake'
});
combined: Query both the artist and title fields with the same string
this.store.query('echonest-song', {
method: 'search',
combined: 'nirvana'
});
description: A description of the artist
this.store.query('echonest-song', {
method: 'search',
description: 'emo'
});
Multiple descriptions:
this.store.query('echonest-song', {
method: 'search',
description: ['emo', 'alt-rock']
});
style: A musical style or genre
See List Terms for more information about available styles.
this.store.query('echonest-song', {
method: 'search',
style: 'jazz'
});
Multiple styles:
this.store.query('echonest-song', {
method: 'search',
style: ['jazz', 'funky']
});
mood: A song's mood
See List Terms for more information about available moods.
this.store.query('echonest-song', {
method: 'search',
mood: 'happy'
});
Multiple moods:
this.store.query('echonest-song', {
method: 'search',
mood: ['happy', 'sad']
});
artist_id: An Echo Nest or Rosetta artist ID
this.store.query('echonest-song', {
method: 'search',
artist_id: 'ARH6W4X1187B99274F'
});
song_type: Restrict results to a specific type of song ('acoustic', 'christmas', 'electric', 'live', 'studio')
this.store.query('echonest-song', {
method: 'search',
title: 'boom boom pow',
song_type: 'live'
});
Multiple song types:
this.store.query('echonest-song', {
method: 'search',
title: 'boom boom pow',
song_type: ['live', 'electric']
});
Song types can be modified with a state dictating whether to include or exclude that type:
true
- Include the type in results (Default)false
- Exclude the type from results
this.store.query('echonest-song', {
method: 'search',
title: 'boom boom pow',
song_type: ['live', 'electric:true', 'christmas: false']
});
The above query would return songs that are both live
and electric
, but not christmas
.
results: Number of desired results (0-100, Default: 15)
this.store.query('echonest-song', {
method: 'search',
title: 'boom boom pow',
results: 100
});
start: Desired index of the first result returned (0+, Default: 0)
this.store.query('echonest-song', {
method: 'search',
title: 'boom boom pow',
start: 20
});
sort: Indicates how results should be ordered
this.store.query('echonest-song', {
method: 'search',
title: 'boom boom pow',
sort: 'song_hotttnesss-desc'
});
Sort Options: Add -asc
or -desc
to indicate sort direction
tempo
duration
loudness
speechiness
acousticness
liveness
artist_familiarity
artist_hotttnesss
artist_start_year
artist_end_year
song_hotttnesss
latitude
longitude
mode
key
energy
danceability
For more available search parameters, visit the Song Search API Docs
audio_summary
- returns summary audio parameters for the track
this.store.queryRecord('echonest-track', {
method: 'profile',
id: 'TRTLKZV12E5AC92E11',
bucket: ['audio_summary']
});
this.store.queryRecord('echonest-track', {
method: 'profile',
id: 'TRTLKZV12E5AC92E11'
});
Alternatively, you may lookup tracks by their md5
hash:
this.store.queryRecord('echonest-track', {
method: 'profile',
md5: '881f4e47e88e8b570e34a3b49c8262ac'
});
Currently Unsupported
The Echo Nest API can be used to create playlists on the fly. To access it, simply query for a list of songs
using the various playlist
methods.
id:catalog-name
tracks
this.store.query('echonest-song', {
artist: 'Eminem',
method: 'playlist/basic'
})
A number of different parameters can be used to seed the playlist: artist_id
, artist
, song_id
, genre
, track_id
.
Multiples of each are allowed, but only a maximum of five across all seed parameters.
artist_id: ID(s) of seed artist(s)
this.store.query('echonest-song', {
artist_id: 'ARH6W4X1187B99274F',
method: 'playlist/basic'
})
artist: Name(s) of seed artist(s)
this.store.query('echonest-song', {
artist: 'Mariah Carey',
method: 'playlist/basic'
})
song_id: ID(s) of seed song(s)
this.store.query('echonest-song', {
song_id: 'SOCZMFK12AC468668F',
method: 'playlist/basic'
})
genre: Seed genre(s)
this.store.query('echonest-song', {
genre: 'rock',
method: 'playlist/basic'
})
track_id: ID(s) of seed track(s)
this.store.query('echonest-song', {
track_id: 'TRTLKZV12E5AC92E11',
method: 'playlist/basic'
})
type: The type of playlist to be generated (artist-radio, song-radio , genre-radio, Default: artist-radio)
artist-radio
- plays songs for the given artists and similar artistssong-radio
- plays songs similar to the song specified.genre-radio
- plays songs from artists matching the given genre
this.store.query('echonest-song', {
type: 'genre-radio',
genre: 'rock',
method: 'playlist/basic'
})
results: Desired number of songs in the playlist (0-100, Default: 15)
this.store.query('echonest-song', {
artist: 'Eminem',
method: 'playlist/basic',
results: 50
})
limited_interactivity: Set rules for the playlist to conform to (true, false, stylea, styleb, Default: false)
When the limited_interactivity parameter is set to true, the playlist will conform to the following rules:
- no more than 2 songs in a row from the same album
- no more than 3 songs from an album in a 3 hour period
- no more than 3 different songs in a row by the same artist
- no more than 4 songs by the same artist in a 3 hour period
If limited_interactivity is set to true, skipped songs are not considered to have been played for
limited interactivity conformance purposes. If limited_interactivity is set to
styleb
, skipped songs are considered to have been played for limited interactivity purposes.
Currently Unsupported
CONTRIBUTING.md details how to contribute to this project.
git clone git@github.com:elwayman02/ember-data-echonest.git
cd ember-data-echonest
npm install
bower install
ember server
- Visit your app at http://localhost:4200.
npm test
(Runsember try:testall
to test your addon against multiple Ember versions)ember test
ember test --server
ember build
For more information on using ember-cli, visit http://www.ember-cli.com/.