com.echonest.api.v4
Class EchoNestAPI

java.lang.Object
  com.echonest.api.v4.EchoNestAPI

public class EchoNestAPI
extends java.lang.Object

The main interface to the Echo Nest API

Constructor Summary

EchoNestAPI()
Creates a new EchoNestAPI.

EchoNestAPI(java.lang.String apiKey)
Creates a new EchoNestAPI with the given API key

Method Summary

ArtistCatalog	createArtistCatalog(java.lang.String name) Creates an artist catalog
Playlist	createBasicPlaylist(Params p) create a basic playlist
Playlist	createDynamicPlaylist(Params p) Creates a dynamic playlist.
SongCatalog	createSongCatalog(java.lang.String name) Creates a song catalog
Playlist	createStaticPlaylist(Params p) create a static playlist
ArtistCatalog	getArtistCatalogByID(java.lang.String id) Gets a previously created artist catalog by ID
ArtistCatalog	getArtistCatalogByName(java.lang.String name) Gets a previously created artist catalog by name
Track	getKnownTrack(java.io.File file) Determines whether or not the track is known by the echo nest
Track	getKnownTrack(java.lang.String md5) Determines whether or not the track is known by the echo nest
int	getMinCommandTime() Gets the minimum time between commands
Playlist	getNextInDynamicPlaylist(java.lang.String sessionID) Gets the next song in the dynamic playlist
Playlist	getNextInDynamicPlaylist(java.lang.String sessionID, int rating) Gets the next song in the dynamic playlist
Playlist	getNextInDynamicPlaylist(java.lang.String sessionID, int rating, int testMode)
java.util.List<Artist>	getSimilarArtists(Params p) Gets similar artists given a set of params (See ArtistParams)
SongCatalog	getSongCatalogByID(java.lang.String id) Gets a previously created song catalog by ID
SongCatalog	getSongCatalogByName(java.lang.String name) Gets a previously created song catalog by name
java.util.List<Song>	getSongs(Params p) Get info for songs based on a set of params (See SongParams)
java.util.List<Term>	getTopTerms(int count) Gets the most frequently occurring top terms
java.util.List<Song>	identifySongs(Params p) Identify a song given codes from the Echo Nest Fingerprinter
java.util.List<ArtistCatalog>	listArtistCatalogs() List all artist catalogs created with this API key
java.util.List<SongCatalog>	listSongCatalogs() List all song catalogs created with this API key
Artist	newArtistByID(java.lang.String id) Creates a new artist given the artist ID
Artist	newArtistByName(java.lang.String name) Creates a new artist given the artist name
Track	newTrackByID(java.lang.String id) Creates a track from a track ID
Track	newTrackByMD5(java.lang.String md5) Creates a track from a track ID
java.util.List<Artist>	searchArtists(Params p) Search for artists given a set of params (See ArtistParams)
java.util.List<Artist>	searchArtists(java.lang.String name) Search for artists by name
java.util.List<Artist>	searchArtists(java.lang.String name, int count) Search for artists by name and count
java.util.List<Song>	searchSongs(Params p) Search for songs given a set of params (See SongParams)
void	setHostName(java.lang.String hostName) Sets the host to use for the API.
void	setMinCommandTime(int minTime) Sets the minimum time between Echo Nest commands
void	setTraceRecvs(boolean traceRecvs) Enables / disables traccing of responses
void	setTraceSends(boolean traceSends) Enables / disables tracing of sent commands
void	showStats() Shows performance and error statistics for the API
java.util.List<Song>	similarSongs(Params p) Get similar songs based on a set of params (See SongParams)
java.util.List<Artist>	suggestArtists(Params p) Suggest artists given a set of params (See ArtistParams)
java.util.List<Artist>	suggestArtists(java.lang.String name) Suggest artists by name
java.util.List<Artist>	topHotArtists(int count) Gets the top hotttest artists
java.util.List<Artist>	topHotArtists(int start, int count) Gets the top hotttest artists
java.util.List<Artist>	topHotArtists(Params p) Gets the top hotttest artists based on params
Track	uploadTrack(java.io.File audioFile, boolean wait) Upload a track
Track	uploadTrack(java.net.URL trackUrl, boolean wait) Upload a track

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EchoNestAPI

public EchoNestAPI()
            throws EchoNestException

Creates a new EchoNestAPI. This method will attempt to get the Echo Nest API Key from the ECHO_NEST_API_KEY system property or environment variable

Throws:

EchoNestException

EchoNestAPI

public EchoNestAPI(java.lang.String apiKey)

Creates a new EchoNestAPI with the given API key

Parameters:

apiKey - the developer api key

Method Detail

newArtistByID

public Artist newArtistByID(java.lang.String id)
                     throws EchoNestException

Creates a new artist given the artist ID

Parameters:

id -

Returns:

Throws:

EchoNestException

newArtistByName

public Artist newArtistByName(java.lang.String name)
                       throws EchoNestException

Creates a new artist given the artist name

Parameters:

name -

Returns:

Throws:

EchoNestException

setHostName

public void setHostName(java.lang.String hostName)

Sets the host to use for the API.

Parameters:

hostName -

setMinCommandTime

public void setMinCommandTime(int minTime)

Sets the minimum time between Echo Nest commands

Parameters:

minTime -

getMinCommandTime

public int getMinCommandTime()

Gets the minimum time between commands

Returns:

setTraceSends

public void setTraceSends(boolean traceSends)

Enables / disables tracing of sent commands

Parameters:

traceSends -

setTraceRecvs

public void setTraceRecvs(boolean traceRecvs)

Enables / disables traccing of responses

Parameters:

traceRecvs -

showStats

public void showStats()

Shows performance and error statistics for the API

getSimilarArtists

public java.util.List<Artist> getSimilarArtists(Params p)
                                         throws EchoNestException

Gets similar artists given a set of params (See ArtistParams)

Parameters:

p -

Returns:

Throws:

EchoNestException

searchArtists

public java.util.List<Artist> searchArtists(Params p)
                                     throws EchoNestException

Search for artists given a set of params (See ArtistParams)

Parameters:

p -

Returns:

Throws:

EchoNestException

suggestArtists

public java.util.List<Artist> suggestArtists(Params p)
                                      throws EchoNestException

Suggest artists given a set of params (See ArtistParams)

Parameters:

p -

Returns:

Throws:

EchoNestException

suggestArtists

public java.util.List<Artist> suggestArtists(java.lang.String name)
                                      throws EchoNestException

Suggest artists by name

Parameters:

name -

Returns:

Throws:

EchoNestException

getTopTerms

public java.util.List<Term> getTopTerms(int count)
                                 throws EchoNestException

Gets the most frequently occurring top terms

Parameters:

count - the number of terms to return

Returns:

a list of top terms

Throws:

EchoNestException

searchArtists

public java.util.List<Artist> searchArtists(java.lang.String name)
                                     throws EchoNestException

Search for artists by name

Parameters:

name -

Returns:

Throws:

EchoNestException

searchArtists

public java.util.List<Artist> searchArtists(java.lang.String name,
                                            int count)
                                     throws EchoNestException

Search for artists by name and count

Parameters:

name -

count -

Returns:

Throws:

EchoNestException

topHotArtists

public java.util.List<Artist> topHotArtists(int count)
                                     throws EchoNestException

Gets the top hotttest artists

Parameters:

count -

Returns:

Throws:

EchoNestException

topHotArtists

public java.util.List<Artist> topHotArtists(int start,
                                            int count)
                                     throws EchoNestException

Gets the top hotttest artists

Parameters:

start - the starting index

count - the count

Returns:

Throws:

EchoNestException

topHotArtists

public java.util.List<Artist> topHotArtists(Params p)
                                     throws EchoNestException

Gets the top hotttest artists based on params

Parameters:

p -

Returns:

Throws:

EchoNestException

searchSongs

public java.util.List<Song> searchSongs(Params p)
                                 throws EchoNestException

Search for songs given a set of params (See SongParams)

Parameters:

p -

Returns:

Throws:

EchoNestException

similarSongs

public java.util.List<Song> similarSongs(Params p)
                                  throws EchoNestException

Get similar songs based on a set of params (See SongParams)

Parameters:

p -

Returns:

Throws:

EchoNestException

identifySongs

public java.util.List<Song> identifySongs(Params p)
                                   throws EchoNestException

Identify a song given codes from the Echo Nest Fingerprinter

Parameters:

p -

Returns:

Throws:

EchoNestException

getSongs

public java.util.List<Song> getSongs(Params p)
                              throws EchoNestException

Get info for songs based on a set of params (See SongParams)

Parameters:

p -

Returns:

Throws:

EchoNestException

uploadTrack

public Track uploadTrack(java.net.URL trackUrl,
                         boolean wait)
                  throws EchoNestException

Upload a track

Parameters:

trackUrl - the url of the track

wait - if true, wait for the analysis

Returns:

the ID of the track

Throws:

EchoNestException

uploadTrack

public Track uploadTrack(java.io.File audioFile,
                         boolean wait)
                  throws EchoNestException,
                         java.io.IOException

Upload a track

Parameters:

trackFile - the file to upload

wait - if true, wait for the analysis

Returns:

the ID of the track

Throws:

com.echonest.api.v3.artist.EchoNestException

EchoNestException

java.io.IOException

getKnownTrack

public Track getKnownTrack(java.lang.String md5)
                    throws EchoNestException

Determines whether or not the track is known by the echo nest

Parameters:

md5 - of the track

Returns:

true if the track is known

Throws:

EchoNestException

getKnownTrack

public Track getKnownTrack(java.io.File file)
                    throws java.io.IOException,
                           EchoNestException

Determines whether or not the track is known by the echo nest

Parameters:

file - the file to test

Returns:

true if the track is known

Throws:

java.io.IOException

EchoNestException

newTrackByID

public Track newTrackByID(java.lang.String id)
                   throws EchoNestException

Creates a track from a track ID

Parameters:

id - the ID or MD5 of the track

Returns:

a new track

Throws:

EchoNestException

newTrackByMD5

public Track newTrackByMD5(java.lang.String md5)
                    throws EchoNestException

Creates a track from a track ID

Parameters:

id - the ID or MD5 of the track

Returns:

a new track

Throws:

EchoNestException

createBasicPlaylist

public Playlist createBasicPlaylist(Params p)
                             throws EchoNestException

create a basic playlist

Parameters:

p - the playlist params (see PlaylistParams)

Returns:

the playlist

Throws:

EchoNestException

createStaticPlaylist

public Playlist createStaticPlaylist(Params p)
                              throws EchoNestException

create a static playlist

Parameters:

p - the playlist params (see PlaylistParams)

Returns:

the playlist

Throws:

EchoNestException

createDynamicPlaylist

public Playlist createDynamicPlaylist(Params p)
                               throws EchoNestException

Creates a dynamic playlist. Returns a dynamic playlist. A dynamic playlist is created with an initial set of parameters and songs are fetched one at a time using a session identifier. The playlist is dynamic and will return songs based on the listener's feedback. A dynamic playlist returns a single song at a time along with the session ID. When the client is ready to play the next song it makes a dynamic playlist request that includes the session ID

Parameters:

p - the params for the playlist (see PlaylistParams)

Returns:

the playlist

Throws:

EchoNestException

getNextInDynamicPlaylist

public Playlist getNextInDynamicPlaylist(java.lang.String sessionID,
                                         int rating)
                                  throws EchoNestException

Gets the next song in the dynamic playlist

Parameters:

sessionID - the session id

rating - a rating of 1 to 5 (zero means no rating)

Returns:

the playlist

Throws:

EchoNestException

getNextInDynamicPlaylist

public Playlist getNextInDynamicPlaylist(java.lang.String sessionID,
                                         int rating,
                                         int testMode)
                                  throws EchoNestException

Throws:

EchoNestException

createArtistCatalog

public ArtistCatalog createArtistCatalog(java.lang.String name)
                                  throws EchoNestException

Creates an artist catalog

Parameters:

name - the name of the catalog

Throws:

EchoNestException

getArtistCatalogByID

public ArtistCatalog getArtistCatalogByID(java.lang.String id)
                                   throws EchoNestException

Gets a previously created artist catalog by ID

Parameters:

id - the catalog ID

Returns:

the catalog or null if the catalog is not found or is not an artist catalog

Throws:

EchoNestException

getArtistCatalogByName

public ArtistCatalog getArtistCatalogByName(java.lang.String name)
                                     throws EchoNestException

Gets a previously created artist catalog by name

Parameters:

name - the catalog name

Returns:

the catalog or null if the catalog is not found or is not an artist catalog

Throws:

EchoNestException

getSongCatalogByID

public SongCatalog getSongCatalogByID(java.lang.String id)
                               throws EchoNestException

Gets a previously created song catalog by ID

Parameters:

id - the catalog ID

Returns:

the catalog or null if the catalog is not found or is not a song catalog

Throws:

EchoNestException

getSongCatalogByName

public SongCatalog getSongCatalogByName(java.lang.String name)
                                 throws EchoNestException

Gets a previously created song catalog by name

Parameters:

name - the catalog name

Returns:

the catalog or null if the catalog is not found or is not a song catalog

Throws:

EchoNestException

listArtistCatalogs

public java.util.List<ArtistCatalog> listArtistCatalogs()
                                                 throws EchoNestException

List all artist catalogs created with this API key

Returns:

a list of artist catalogs

Throws:

EchoNestException

createSongCatalog

public SongCatalog createSongCatalog(java.lang.String name)
                              throws EchoNestException

Creates a song catalog

Parameters:

name - the name of the catalog

Throws:

EchoNestException

listSongCatalogs

public java.util.List<SongCatalog> listSongCatalogs()
                                             throws EchoNestException

List all song catalogs created with this API key

Returns:

a list of artist catalogs

Throws:

EchoNestException

getNextInDynamicPlaylist

public Playlist getNextInDynamicPlaylist(java.lang.String sessionID)
                                  throws EchoNestException

Gets the next song in the dynamic playlist

Parameters:

sessionID - the session id

Returns:

the playlist

Throws:

EchoNestException