Retrieving the songs from a particular artist

This tutorial shows you how to retrieve the songs for a particular artist.

Getting a list of songs

Using the song/search API call, you can retrieve a list of songs that match particular criteria. The easiest way to do this is by searching for the songs by a single artist. In this case, you can use either the artist= or artist_id= parameter to restrict the results to one artist.

Example

Response

{
    "response": {
        "songs": [
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOVFTPB12B3A141C63", 
                "title": "Against All Odds (Take A Look At Me Now)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOAKMDU12A8C1346A9", 
                "title": "Such Great Heights"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOCIFMJ12B0B80C1A4", 
                "title": " We Will Become Silouettes (The Shins)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SONPLUD12A8C13BF4B", 
                "title": "Clark Gable (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOVDUUJ129F08266E0", 
                "title": "We Will Become Silhouettes"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SODJUMX12AF72A5EDD", 
                "title": "Suddenly Everything Has Changed"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOINKVP12A8C13BF5D", 
                "title": "Brand New Colony (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOIHXTH12AF729BD3D", 
                "title": "Grow Old With Me"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOHNOOC12A8C13BF35", 
                "title": "The District Sleeps Alone Tonight (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOZHJKI12A81C2248F", 
                "title": "We Will Become Silhouettes (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOHSHMS12A8C13BF58", 
                "title": "This Place is a Prison (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOZZFEV12A81C22496", 
                "title": "We Will Become Silhouettes (Matthew Dear) (Album Version)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOKNWRZ12A8C13BF62", 
                "title": "Natural Anthem (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOFWEQC12A8AE44D48", 
                "title": "Such Great Heights (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOPQQNK12A8C13BF46", 
                "title": "Recycled Air (Album)"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}
The response includes (by default) 15 songs by that artist, including the artist and song IDs, and the artist and song title.

As with other API calls, you can use the results= and start= parameters to control how much data you retrieve, and where you start, if you want to page through all of the songs in an artist's catalog.

Example

would return 50 songs from The Postal Service, rather than the default 15. Furthermore:

would return 25 songs, after skipping the first 50 &em; in this way you can paginate through all of the songs in an efficient manner.

Sorting the results

When returning songs, the Echo Nest sorts by relevance, in an attempt to give you the best possible matches first. In this case, all songs will have the same relevance, since they all match the search criterion (artist) 100% identically. Therefore, the results will be returned in what appears to be a random order. Of course, you can change this through the use of the sort= parameter.

One of the most useful sorts is that of song hotttnesss &em; the Echo Nest's determination of how hot the song is currently. To sort by that, use the sort=song_hotttness-asc or sort=song_hotttnesss-desc paramters (all of the sort parameters take an -asc or -desc at the end, to control ascending or descending sort.) Let's see the hotttessst songs by The Postal Service:

Response

{
    "response": {
        "songs": [
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOAKMDU12A8C1346A9", 
                "title": "Such Great Heights"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOFWEQC12A8AE44D48", 
                "title": "Such Great Heights (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOHNOOC12A8C13BF35", 
                "title": "The District Sleeps Alone Tonight (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOFCPOU12A8C13BF40", 
                "title": "Nothing Better (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOEGZHD12A8C13BF3D", 
                "title": "Sleeping In (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOZHJKI12A81C2248F", 
                "title": "We Will Become Silhouettes (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOINKVP12A8C13BF5D", 
                "title": "Brand New Colony (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SONPLUD12A8C13BF4B", 
                "title": "Clark Gable (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOPQQNK12A8C13BF46", 
                "title": "Recycled Air (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOHSHMS12A8C13BF58", 
                "title": "This Place is a Prison (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOKNWRZ12A8C13BF62", 
                "title": "Natural Anthem (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOVFTPB12B3A141C63", 
                "title": "Against All Odds (Take A Look At Me Now)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SONWFKM12A8AE44D40", 
                "title": "There's Never Enough Time (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SODJUMX12AF72A5EDD", 
                "title": "Suddenly Everything Has Changed"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOIHXTH12AF729BD3D", 
                "title": "Grow Old With Me"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}

And we can now see what the hotttessst songs are for that artist. You may be wondering how to prove it, since there's no way to tell from that result what each song's hotttnesss is. You can do that by adding a bucket= parameter. Buckets are the way to retrieve extra information in a request. We'll cover them in more detail later, but for now, adding bucket=song_hotttness will return the hotttnesss for each song, like this:

Response

{
    "response": {
        "songs": [
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOAKMDU12A8C1346A9", 
                "song_hotttnesss": 0.86564163199947186, 
                "title": "Such Great Heights"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOFWEQC12A8AE44D48", 
                "song_hotttnesss": 0.83851220358057199, 
                "title": "Such Great Heights (Album)"
            }, ...

Note that, in addition to the basic identifying information, each song now has a value for song_hotttnesss, which is a numeric representation of how current or trending the song is.

Other common sorts include some of the Echo Nest musical attributes for a song, like tempo, loudness, energy, duration, and danceability. The complete list is available in the API reference. But we can look at a few more examples. In each case, we will restrict the results to 1, and sort by a particular attribute. This will give us the song that has the highest (or lowest) value across each of these metrics. Additionally, we will add bucket=audio_summary to each of these calls, so you can see the underlying metric in question.

Example

Response

{
    "response": {
        "songs": [
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "audio_summary": {
                    "analysis_url": "https://echonest-analysis.s3.amazonaws.com:443/TR/TRVIOOB129CC96BE00/3/full.json?Signature=CJ7b%2Fs5a9fg84ljguID52qz616E%3D&Expires=1307890959&AWSAccessKeyId=AKIAJRDFEY23UEVW42BQ", 
                    "audio_md5": "7743229c4d448ffd1541f9e95c15c843", 
                    "danceability": 0.68410036340969893, 
                    "duration": 415.58159000000001, 
                    "energy": 0.58062874147026777, 
                    "key": 0, 
                    "loudness": -10.893000000000001, 
                    "mode": 1, 
                    "tempo": 141.93199999999999, 
                    "time_signature": 4
                }, 
                "id": "SOGHUFR12AF72A5EDB", 
                "title": "The District Sleeps Alone Tonight"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}

returns the longest song. Note the audio_summary bracket above; the duration of the song returned is 415 seconds.

Response

{
    "response": {
        "songs": [
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "audio_summary": {
                    "analysis_url": "https://echonest-analysis.s3.amazonaws.com:443/TR/TRFUYPH128F429617B/3/full.json?Signature=5fb71UX16WNITtsxJh57vt1x2jc%3D&Expires=1307891032&AWSAccessKeyId=AKIAJRDFEY23UEVW42BQ", 
                    "audio_md5": "9324101e4ce611a532bb9a0fdfce19c0", 
                    "danceability": 0.56868905894129773, 
                    "duration": 252.70812000000001, 
                    "energy": 0.39269954473864788, 
                    "key": 0, 
                    "loudness": -7.0860000000000003, 
                    "mode": 1, 
                    "tempo": 175.072, 
                    "time_signature": 4
                }, 
                "id": "SOINKVP12A8C13BF5D", 
                "title": "Brand New Colony (Album)"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}

returns the fastest song, in this case Brand New Colony with a temp of 175 BPM.

Filtering the results

Many of the attributes can be used as filters, as well. For instance, you may only want songs above a certain threshold of danceability, or within a range of tempos. Or you may be looking for particularly obscure or well-known songs. You can do this through the use of min_ and max_ parameters. Let's look at some examples.

To find songs with a range of tempos between 120 and 140 BPM (to make a running or workout playlist, for instance), you might issue the following call:

To find songs with a minimum of 0.7 danceability (that's pretty danceable!), try this:

Another common use case is returning just those songs that are available via a particular partner catalog. For instance, seeing all of the songs that are available on Rdio or 7digital. To do this, you must add a bucket= parameter, and name the catalog that you'd like the results from. Additionally, you can choose to restrict the results, only returning items available within that catalog. To do this, you must also add the limit=true parameter. Here are some examples:

(Note that the rdio-us-streaming song catalog used in this tutorial has been superceded by the rdio-US track catalog)

Return The Postal Service songs with Rdio IDs if they have any

Response

{
    "response": {
        "songs": [
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOVFTPB12B3A141C63", 
                "title": "Against All Odds (Take A Look At Me Now)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t4739479"
                    }
                ], 
                "id": "SOAKMDU12A8C1346A9", 
                "title": "Such Great Heights"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOCIFMJ12B0B80C1A4", 
                "title": " We Will Become Silouettes (The Shins)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t1190926"
                    }
                ], 
                "id": "SONPLUD12A8C13BF4B", 
                "title": "Clark Gable (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOVDUUJ129F08266E0", 
                "title": "We Will Become Silhouettes"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t2226511"
                    }
                ], 
                "id": "SODJUMX12AF72A5EDD", 
                "title": "Suddenly Everything Has Changed"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t1191076"
                    }
                ], 
                "id": "SOINKVP12A8C13BF5D", 
                "title": "Brand New Colony (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOIHXTH12AF729BD3D", 
                "title": "Grow Old With Me"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t2269161"
                    }
                ], 
                "id": "SOHNOOC12A8C13BF35", 
                "title": "The District Sleeps Alone Tonight (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t2230098"
                    }
                ], 
                "id": "SOZHJKI12A81C2248F", 
                "title": "We Will Become Silhouettes (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t1191034"
                    }
                ], 
                "id": "SOHSHMS12A8C13BF58", 
                "title": "This Place is a Prison (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOZZFEV12A81C22496", 
                "title": "We Will Become Silhouettes (Matthew Dear) (Album Version)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t1191131"
                    }
                ], 
                "id": "SOKNWRZ12A8C13BF62", 
                "title": "Natural Anthem (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "id": "SOFWEQC12A8AE44D48", 
                "title": "Such Great Heights (Album)"
            }, 
            {
                "artist_id": "AR4ZYGI1187B995AA2", 
                "artist_name": "The Postal Service", 
                "foreign_ids": [
                    {
                        "catalog": "rdio-us-streaming", 
                        "foreign_id": "rdio-us-streaming:song:t1190886"
                    }
                ], 
                "id": "SOPQQNK12A8C13BF46", 
                "title": "Recycled Air (Album)"
            }
        ], 
        "status": {
            "code": 0, 
            "message": "Success", 
            "version": "4.2"
        }
    }
}

Note that some of the songs returned have a foreign-id block, such as:

{
    "artist_id": "AR4ZYGI1187B995AA2", 
    "artist_name": "The Postal Service", 
    "foreign_ids": [
        {
            "catalog": "rdio-us-streaming", 
            "foreign_id": "rdio-us-streaming:song:t4739479"
        }
    ], 
    "id": "SOAKMDU12A8C1346A9", 
    "title": "Such Great Heights"
}, 
and some do not. To restrict to just those items that can be found in the Rdio catalog, add the limit=true parameter as well, like this:

In this case, each of the returned songs has a corresponding Rdio foreign ID, meaning that all of the results can be found in Rdio's catalog.