Navigation

 Developer

Artist API Methods

Api calls for getting data about artists.

The Echo Nest provides methods to return a wide range of data about any music artist. For methods that return lists of artists (search, similar, top_hottt), results can be constrained to a particular rosetta stone catalog or personal catalog. See Project Rosetta Stone for details.

Buckets: Some artist methods such as search, similar, top_hottt, and profile accept a bucket parameter. This parameter allows you to specify what additional data should be returned with each artist. Multiple buckets can be specified simultaneously allowing you to request multiple sets of data in a single call. Possible artist buckets are:

Bucket Description
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
doc_counts (beta) 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
artist_location (beta) returns information about the location of origin for 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 (beta) returns up to the 15 hotttest songs for the artist
urls returns links to this artist's pages on various sites
video returns up to the 15 most recent videos found on the web related to the artist
years_active (beta) 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:Taste-Profile-ID returns personal catalog specific information about the artist for the given catalog. See Project Rosetta Stone for details.

biographies

Get a list of artist biographies.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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
license no yes echo-source, all-rights-reserved, cc-by-sa, cc-by-nc, cc-by-nc-nd, cc-by-nc-sa, cc-by-nd, cc-by, public-domain, unknown the desired licenses of the returned images

Example query:

http://developer.echonest.com/api/v4/artist/biographies?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0&license=cc-by-sa

Here is an example response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "start": 0,
        "total": 12,
        "biographies": [{
            "text": "\"Radiohead\" are an English alternative rock band from Abingdon, Oxfordshire, formed in 1985. The band consists of Thom Yorke (vocals, guitars, piano), Jonny Greenwood (guitars, keyboards, other instruments), Ed O'Brien (guitars, backing vocals), Colin Greenwood (bass, synthesisers) and Phil Selway (drums, percussion).",
            "site": "wikipedia",
            "url": "http://en.wikipedia.org/wiki/Radiohead",
            "license": {
                "type": "cc-by-sa",
                "attribution": "n/a",
                "url": ""
            }
        }]
    }
}

blogs

Get a list of blog articles related to an artist.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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
high_relevance no no true, false if true only items that are highly relevant for this artist will be returned

Example query:

http://developer.echonest.com/api/v4/artist/blogs?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0

Here is an example response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "start": 0,
        "total": 11503,
        "blogs": [{
            "name": "Grammy’s Live Blog",
            "url": "http://potholesinmyblog.com/grammys-live-blog/",
            "summary": " through Bruno Mars and B.o.B to see Janelle Monae is a cruel trick. 8:43 p.m. As much as that Muse song sucked, the performance was still more visually appealing than whatever it is that Lady Gaga did earlier. 8:41 p.m. Muse seems hellbent on riding the whole <span>Radiohead</span> for jocks shtick all the way to the bank. Good luck with that. 8:27 p.m. What was with that hat, by the way? 8:25 p.m. \"Born This Way\" still sounds like the entire '90s Madonna discography mashed up into one song, message of gay ... ",
            "date_found": "2011-02-13T20:18:12",
            "id": "f8c13e8afded66c5d61efeb6a30fcde8",
            "date_posted": "2011-02-13T16:32:52"
        }]
    }
}

familiarity

Get our numerical estimation of how familiar an artist currently is to the world.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests

Example query:

http://developer.echonest.com/api/v4/artist/familiarity?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
    "artist": {
      "familiarity": 0.9007877498316712,
      "id": "ARH6W4X1187B99274F",
      "name": "Radiohead"
    }
  }
}

hotttnesss

Returns our numerical description of how hottt an artist currently is.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
type no no overall, social, reviews, mainstream controls the type of hotttnesss that is used.

Example query:

http://developer.echonest.com/api/v4/artist/hotttnesss?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
    "artist": {
      "hotttnesss": 0.61081915371492912,
      "name": "Radiohead",
      "id": "ARH6W4X1187B99274F"
    }
  }
}

images

Get a list of artist images.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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
license no yes echo-source, all-rights-reserved, cc-by-sa, cc-by-nc, cc-by-nc-nd, cc-by-nc-sa, cc-by-nd, cc-by, public-domain, unknown the desired licenses of the returned images

Example query:

http://developer.echonest.com/api/v4/artist/images?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0&license=unknown

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "start": 0,
      "total": 121,
      "images": [
        {
          "url": "http://userserve-ak.last.fm/serve/_/174456.jpg",
          "license": {
            "url": "",
            "attribution": "",
            "type": "unknown"
          }
        }
      ]
    }
}

list_genres

Get a list of the available genres for use with search and playlisting. This method returns a list of genres suitable for use in the artist/search call when searching by description and for the creation of genre-radio playlists. The returned list of genres is inclusive of all supported genres.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests

Example query:

http://developer.echonest.com/api/v4/artist/list_genres?api_key=YOUR_API_KEY&format=json

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "genres": [
        { "name": "a cappella" },
        { "name": "acid house" },
        { "name": "acid jazz" },
        { "name": "acoustic blues" },
        { "name": "afrobeat" }
        //  many genres ommitted ...
      ]
    }
}

list_terms

Get a list of the best typed descriptive terms for use with search. This method returns a list of descriptive terms suitable for use in the artist/search call when searching by description. The returned list of terms is not necessarily inclusive of all supported terms, but does include terms that are known to return high quality results.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
type no no style, mood the type of term that is of interest

Example query:

http://developer.echonest.com/api/v4/artist/list_terms?api_key=YOUR_API_KEY&format=json&type=style

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "type": "style",
      "terms": [
        { "name": "rock" },
        { "name": "alternative" },
        { "name": "jazz" },
        { "name": "classical" },
        { "name": "indie" }
      ]
    }
}

Example query:

http://developer.echonest.com/api/v4/artist/list_terms?api_key=YOUR_API_KEY&format=json&type=mood

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "type": "mood",
      "terms": [
        { "name": "happy" },
        { "name": "angry" },
        { "name": "sad" },
        { "name": "relaxing" },
        { "name": "excited"  }
      ]
    }
}

news

Get a list of news articles found on the web related to an artist.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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
high_relevance no no true, false if true only news articles that are highly relevant for this artist will be returned

Example query:

http://developer.echonest.com/api/v4/artist/news?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "start": 0,
      "total": 121,
      "news": [
        {
          "name": "First Listen: The National High Violet",
          "url": "http://www.drownedinsound.com/news/4139479-first-listen--the-national-high-violet",
          "date_posted": "2010-04-12T00:00:00",
          "date_found": "2010-04-12T06:15:29",
          "summary": " off a new-found sophistication (think of how <span>Radiohead</span>'s rhythm section developed over their first five records). Menacing cellos saw a triplet at a time, rising up like tall buildings around you, then rest. The contrast between Berninger's minimal, one-note vocals and the rising volume of the layers and layers of instruments builds tension until finally the singer shifts key, recognizing the urgency... and then the music dissolves into an atonal coda.  'Afraid of Everyone' Opening ... ",
          "id": "484a6108e649f0251c182381e401f0c6"
        }
      ]
    }
}

profile

Get basic information about an artist.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
bucket no yes biographies, blogs, doc_counts, familiarity, hotttnesss, images, artist_location, news, reviews, songs, terms, urls, video, years_active, id:Rosetta-space indicates what data should be returned with each artist

Bucket: When specifying idspace buckets (those starting with "id:") the results will be returned in a "foreign_ids" key/element. See Project Rosetta Stone for more information on ID spaces.

Example queries:

http://developer.echonest.com/api/v4/artist/profile?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&bucket=id:7digital-US&format=json

http://developer.echonest.com/api/v4/artist/profile?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&bucket=biographies&bucket=blogs&bucket=familiarity&bucket=hotttnesss&bucket=images&bucket=news&bucket=reviews&bucket=terms&bucket=urls&bucket=video&bucket=id:musicbrainz

Here is an example response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "artist": {
            "foreign_ids": [{
                "catalog": "7digital-US",
                "foreign_id": "7digital-US:artist:304"
            }],
            "id": "ARH6W4X1187B99274F",
            "name": "Radiohead"
        }
    }
}

Here is an example call that retrieves location information for an artist: (beta)

http://developer.echonest.com/api/v4/artist/profile?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&bucket=artist_location

Here is an example response:

{
    "response": {
        "artist": {
            "artist_location": {
                "city": "Abingdon",
                "country": "United Kingdom",
                "location": "Abingdon, England, GB",
                "region": "England"
            },
            "id": "ARH6W4X1187B99274F",
            "name": "Radiohead"
        },
        "status": {
            "code": 0,
            "message": "Success",
            "version": "4.2"
        }
    }
}
Here is an example call that retrieves counts for each document type associated with an artist::
http://developer.echonest.com/api/v4/artist/profile?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&bucket=doc_counts

Here is an example response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "artist": {
            "id": "ARH6W4X1187B99274F",
            "name": "Radiohead"
            "doc_counts": {
                "biographies" : 18,
                "blogs" : 256,
                "images" : 118,
                "news" : 32,
                "reviews" : 16,
                "songs" : 198,
                "videos" : 456
            }
        }
    }
}

reviews

Get reviews related to an artist's work.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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/artist/reviews?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "start": 0,
      "total": 121,
      "reviews": [
        {
          "name": "Radiohead - Radiohead: Hail to the Thief: Special Collectors Edition (from Under The Radar)",
          "url": "http://www.undertheradarmag.com/reviews/radiohead_hail_to_the_thief_special_collectors_edition/",
          "summary": "After the revolutionary OK Computer and Kid A/Amnesiac, Radiohead took a step sideways with Hail to the Thief. The band had refined its sound, and its particular brand of adventurous electronic/organic push/pull. Hail sounded less like the cohesive statements that their predecessors put forth, and instead seemed more a collection of songs. Great songs, of course, with the guitars taking center stage once again. From the brilliant \"2+2=5\" to the threatening \"Where I End and You Begin\" to the slin......",
          "date_reviewed": "2009-11-10T00:00:00",
          "date_found": "2009-11-12T23:25:39",
          "image_url": "http://www.undertheradarmag.com/uploads/review_images/radiohead_hail_to_the_thief_2.jpg",
          "release": "Radiohead: Hail to the Thief: Special Collectors Edition",
          "id": "2ef4e2fd1b8f8d9772713433ec900abb"
        }
      ]
  }
}

extract (beta)

Extract artist names from text.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
results no no 0 < results < 1000, (Default=15) the number of results desired
bucket no yes biographies, blogs, doc_counts, familiarity, hotttnesss, images, artist_location, news, reviews, songs, terms, urls, video, years_active, id:Rosetta-space indicates what data should be returned with each artist
limit no no true, false if 'true', limit the results to any of the given idspaces or catalogs
text no no Siriusmo is my favorite, but I also like hrvatski text that contains artist names
max_familiarity no no 0.0 < familiarity < 1.0 the maximum familiarity for returned artists
min_familiarity no no 0.0 < familiarity < 1.0 the minimum familiarity for returned artists
max_hotttnesss no no 0.0 < hotttnesss < 1.0 the maximum hotttnesss for returned artists
min_hotttnesss no no 0.0 < hotttnesss < 1.0 the minimum hotttnesss for returned artists
sort no no familiarity-asc, hotttnesss-asc, familiarity-desc, hotttnesss-desc, artist_start_year-asc, artist_start_year-desc, artist_end_year-asc, artist_end_year-desc, specified the sort order of the results
results no no 0 < results < 100, (Default=15) the number of results desired

Warning

If limit is set to anything but false, at least one idspace must also be provided in the bucket parameter.

Bucket: When specifying idspace buckets (those starting with "id:") the results will be returned in a "foreign_ids" key/element. See Project Rosetta Stone for more information on ID spaces.

Example query:

http://developer.echonest.com/api/v4/artist/extract?api_key=YOUR_API_KEY&format=json&text=Siriusmo%20is%20my%20favorite%20,%20but%20I%20also%20like%20hrvatski&results=10

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
    "artists": {
      "artist": [
        {
          "name": "Siriusmo",
          "id": "ARJNJT81187B98CF40",
        },
                        {
                          "name": "Hrvatski",
                          "id": "ARQR3191187B9B17AD",
                        }
      ]
    }
  }
}

songs

Get a list of songs created by an artist.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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/artist/songs?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&start=0&results=2

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "start": 0,
      "total": 121,
      "songs": [
        {
          "id": "SOXZYYG127F3E1B7A2",
          "title": "Karma police"
        },
        {
          "id": "SOXZABD127F3E1B7A2",
          "title" : "Creep"
        }
      ]
    }
  }
}

similar

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.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name yes (up to 5) ARH6W4X1187B99274F, 7digital-US:artist:304 ARH6W4X1187B99274F^2 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name yes Weezer, the+beatles ,the+beatles^0.5 the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
results no no 0 < results < 100, (Default=15) the number of results desired
min_results no no 0 < results < 100, (Default=15) Indicates the minimum number of results to be returned regardless of constraints
start no no 0, 15, 30 the desired index of the first result returned
bucket no yes biographies, blogs, doc_counts, familiarity, hotttnesss, images, artist_location, news, reviews, songs, terms, urls, video, years_active, id:Rosetta-space indicates what data should be returned with each artist
max_familiarity no no 0.0 < familiarity < 1.0 the maximum familiarity for returned artists
min_familiarity no no 0.0 < familiarity < 1.0 the minimum familiarity for returned artists
max_hotttnesss no no 0.0 < hotttnesss < 1.0 the maximum hotttnesss for returned artists
min_hotttnesss no no 0.0 < hotttnesss < 1.0 the minimum hotttnesss for returned artists
artist_start_year_before no no 1970, 2011, present Matches artists that have an earliest start year before the given value
artist_start_year_after no no 1970, 2011, present Matches artists that have an earliest start year after the given value
artist_end_year_before no no 1970, 2011, present Matches artists that have a latest end year before the given value
artist_end_year_after no no 1970, 2011, present Matches artists that have a latest end year after the given value
limit no no true, false if 'true', limit the results to any of the given idspaces or catalogs
seed_catalog no yes (up to 5) CAKSMUX1321A708AA4 only give similars to those in a catalog or catalogs, An Echo Nest artist catalog identifier

Warning

If limit is set to anything but false, at least one idspace must also be provided in the bucket parameter.

Bucket: When specifying idspace buckets (those starting with "id:") the results will be returned in a "foreign_ids" key/element. See Project Rosetta Stone for more information on ID spaces.

Boosting: This method can take multiple seed artists. You an give a seed artist more or less weight by boosting the artist. A boost is an affinity for a seed that gives it more or less weight when making calculations based on the argument. In case seeds are not meant to be equally valued, the boost can help clarify where along a spectrum each argument falls. The boost is a positive floating point value, where 1 gives the normal weight. It is signified by appending a caret and weight to the argument.

Example boosting:

To give Radiohead a 2.75 boost:

id=ARH6W4X1187B99274F^2.75 or name=Radiohead^2.75

Example query:

http://developer.echonest.com/api/v4/artist/similar?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "artists": [
        {
          "name": "Thom Yorke",
          "id": "ARH1N081187B9AC562"
        }
      ]
  }
}

Another example query:

http://developer.echonest.com/api/v4/artist/similar?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0&bucket=id:7digital-US&bucket=id:CAXFDYO12E2688C130&limit=true

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "artists": [
        {
          "name": "Thom Yorke",
          "id": "ARH1N081187B9AC562"
          "foreign_ids": [
            {
              "catalog": "7digital-US",
              "foreign_id": "7digital-US:artist:26582"
            },
            {
              "catalog": "CAXFDYO12E2688C130",
              "foreign_id": "CAXFDYO12E2688C130:artist:item-2"
            },
          ]
        }
      ]
  }
}

suggest (beta)

Suggest artists based upon partial names. This method will return a list of potential artist matches based upon a query string. The method returns the most familiar best matching artist for the query.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
results no no 0 < results < 15, (Default=10) the number of results desired
name no no r, rad, radioh a partial artist name
q no no r, rad, radioh a partial artist name (an alias for 'name', to be jQuery friendly)

Example query:

http://developer.echonest.com/api/v4/artist/suggest?api_key=YOUR_API_KEY&name=rad&results=5

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
    "artists": {

      "artist": [
        {
            "id": "ARH6W4X1187B99274F",
            "name": "Radiohead"
        },
        {
            "id": "ARQCFYC12A10043E5B",
            "name": "Go Radio"
        },
        {
            "id": "AREKO1L1187B997EFE",
            "name": "The Radio Dept."
        },
        {
            "id": "AR0PK561187B9B9EF9",
            "name": "TV on the Radio"
        },
        {
            "id": "ARPCRYQ1187FB4ECB8",
            "name": "Joshua Radin"
        }
      ]
    }
  }
}

Another example query:

http://developer.echonest.com/api/v4/artist/suggest?api_key=YOUR_API_KEY&name=radioh

Here is the response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
    "artists": {
      "artist": [
        {
          "name": "Radiohead",
          "id": "ARH6W4X1187B99274F"
        }
      ]
    }
  }
}

Another example query:

http://developer.echonest.com/api/v4/artist/suggest?api_key=YOUR_API_KEY&name=beatl

Here is the response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
    "artists": {
      "artist": [
        {
            "id": "AR6XZ861187FB4CECD",
            "name": "The Beatles"
        },
        {
            "id": "ARELRHU11EBCD770AB",
            "name": "Beatles For Sale"
        },
        {
            "id": "ARYWEGG11F4C84036A",
            "name": "Beatles Tribute"
        },
        {
            "id": "ARAVEWW121318C55CB",
            "name": "The Beatles Tribute Band"
        },
        {
            "id": "ARPXGNH122CC3B2AB4",
            "name": "The Beatles Tribute Project"
        }
      ]
    }
  }
}

terms

Get a list of most descriptive terms for an artist

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
sort no no weight, frequency sort terms based upon weight or frequency

Example query:

http://developer.echonest.com/api/v4/artist/terms?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json

http://developer.echonest.com/api/v4/artist/terms?api_key=YOUR_API_KEY&name=radiohead&format=json

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "terms": [
        {
          "name": "alternative",
          "frequency": 1
          "weight": .78
        },
        {
          "name": "rock",
          "frequency": .98
          "weight": .79
        }
      ]
    }
  }
}

top_hottt

Return a list of the top hottt artists.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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
genre no yes jazz, rock, dance+pop the set of genres of interest. Genres are restricted to those returned via the list_genres call
bucket no yes biographies, blogs, doc_counts, familiarity, hotttnesss, images, artist_location, news, reviews, songs, terms, urls, video, years_active, id:Rosetta-space indicates what data should be returned with each artist
limit no no true, false if true artists will be limited to those that appear in any of the catalogs specified by the id: bucket

Warning

If limit is set to true, at least one idspace must also be provided in the bucket parameter.

Bucket: When specifying idspace buckets (those starting with "id:") the results will be returned in a "foreign_ids" key/element. See Project Rosetta Stone for more information on ID spaces.

Example query:

http://developer.echonest.com/api/v4/artist/top_hottt?api_key=YOUR_API_KEY&format=json&results=1&start=0&bucket=hotttnesss

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "artists": [
        {
          "id": "ARI3Y821187FB3649C",
          "hotttnesss": 0.9733418,
          "name": "MGMT"
        }
      ]
  }
}

Return the top dance pop artists:

http://developer.echonest.com/api/v4/artist/top_hottt?api_key=YOUR_API_KEY&format=json&genre=dance+pop

top_terms

Returns a list of the overall top terms.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
results no no 0 < results < 100, (Default=15) the number of results desired

Example query:

http://developer.echonest.com/api/v4/artist/top_terms?api_key=YOUR_API_KEY&format=json&results=15

Here is an example response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "terms": [{
            "frequency": 1.0,
            "name": "rock"
        },
        {
            "frequency": 0.98976921132935336,
            "name": "electronic"
        },
        {
            "frequency": 0.95841568834249724,
            "name": "hip hop"
        },
        {
            "frequency": 0.94310865392435783,
            "name": "pop rock"
        }]
    }
}

twitter

Gets the twitter handle for an artist

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles ,the+beatles^0.5 the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests

Example queries:

http://developer.echonest.com/api/v4/artist/twitter?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json

Here is an example response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "artist": {
            "id": "ARH6W4X1187B99274F",
            "name": "Radiohead"
            "twitter": "radiohead"
        }
    }
}

If the twitter handle for the artist cannot be found, the twitter field is omitted in the response:

{
    "response": {
        "status": {
            "version": "4.2",
            "code": 0,
            "message": "Success"
        },
        "artist": {
            "id": "ARH6W4X1187B99274F",
            "name": "Radiohead"
        }
    }
}

urls

Get links to the artist's official site, MusicBrainz site, MySpace site, Wikipedia article, Amazon list, and iTunes page.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests

Example query:

http://developer.echonest.com/api/v4/artist/urls?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
    "urls": {
        "lastfm_url": "http://www.last.fm/music/Radiohead",
        "aolmusic_url": "http://music.aol.com/artist/radiohead",
        "myspace_url": "http://www.myspace.com/radiohead",
        "amazon_url": "http://www.amazon.com/gp/search?ie=UTF8&keywords=Radiohead&tag=httpechonecom-20&index=music",
        "itunes_url": "http://itunes.com/Radiohead",
        "mb_url": "http://musicbrainz.org/artist/a74b1b7f-71a5-4011-9441-d0b5e4122711.html"
    }
  }
}

video

Get a list of video documents found on the web related to an artist.

Parameter Required? Multiple? Values Description
api_key yes no YOUR_API_KEY the developer API key
id one of id or name no ARH6W4X1187B99274F, 7digital-US:artist:304 the artist ID. An Echo Nest ID or a Rosetta ID (See Project Rosetta Stone)
name one of id or name no Weezer, the+beatles the artist name
format no no json, xml, jsonp the format of the response
callback Required if format is jsonp no MyJSFunc the callback function for JSONP requests
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/artist/video?api_key=YOUR_API_KEY&id=ARH6W4X1187B99274F&format=json&results=1&start=0

Here is an example response:

{
  "response": {
    "status": {
      "code": "0",
      "message": "Success",
      "version": "4.2"
    },
      "start": 0,
      "total": 121,
      "videos": [
        {
          "title": "Radiohead - Pyramid Song",
          "url": "http://youtube.com/watch?v=3M_Gg1xAHE4",
          "site": "youtube",
          "date_found": "2009-12-13T16:33:21",
          "image_url": "http://i4.ytimg.com/vi/3M_Gg1xAHE4/default.jpg",
          "id": "5da7ac8c7a1483af73eedf6f7f498307"
        }
      ]
    }
}

Table Of Contents

Previous topic

Echo Nest API Overview

Next topic

Song API Methods

Home | Developer | Account | Downloads | Forums | Blog | © 2010-2011, The Echo Nest.