API Guide
TheAudioDB provides a free music API to use in test or development environments.
Most of the basic calls will work using the test API key of "2".
Rate Limit
Maximum 2 calls per second on all API methods
Upgrade
join our $8 Patreon for a full private API key with upgraded features to use in production.
Return Artist details from artist name
search.php?s={Artist name}
Example - theaudiodb.com/api/v1/json/2/search.php?s=coldplay *Limited to 'coldplay' test
Return all Album details from artist name
searchalbum.php?s={Artist name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/searchalbum.php?s=daft_punk*Patreon ONLY*
Return single album details from artist + album name
searchalbum.php?s={Artist name}&a={Album name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/searchalbum.php?s=daft_punk&a=Homework*Patreon ONLY*
Return track details from artist/track name
searchtrack.php?s={Artist_Name}&t={Single_Name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/searchtrack.php?s=coldplay&t=yellow*Patreon ONLY*
Return Discography for an Artist with Album names and year only
discography.php?s={Artist_Name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/discography.php?s=coldplay
Return Discography for an Artist with Album names and year only using known MBID
discography-mb.php?s={Music_Brainz_Artist_ID} *Patreon ONLY*
Return individul Artist details using known TADB_Artist_ID
artist.php?i={artistid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/artist.php?i=112024
Return individual Artist info using a known MusicBrainz_Artist_ID
artist-mb.php?i={mb_artist_id} *Patreon ONLY*
Return All Albums for an Artist using known TADB_Artist_ID
album.php?i={artistid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/album.php?i=112024
Return individual Album info using known TADB_Album_ID
album.php?m={albumid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/album.php?m=2115888
Return individual Album info using a known MusicBrainz_Release-Group_ID
album-mb.php?i={mb_release-group_id} *Patreon ONLY*
Return All Tracks for Album from known TADB_Album_ID
track.php?m={albumid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/track.php?m=2115888
Return individual track info using a known TADB_Track_ID
track.php?h={trackid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/track.php?h=32793500
Return individual track info using a known MusicBrainz_Recording_ID
track-mb.php?i={mb_recording_id} *Patreon ONLY*
Return all the Music videos for a known TADB_Artist_ID
mvid.php?i=(artistid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/mvid.php?i=112024
Return all the Music videos for a known Music_Brainz_ID
mvid-mb.php?i=(MbArtistID} *Patreon ONLY*
Return a Music DVD from artist/mdvd name
searchmdvd.php?s={Artist_Name}&a={Music_Dvd_Name} *Patreon ONLY*
Return The top 10 Most Loved tracks for an Artist Name *Patreon ONLY*
theaudiodb.com/api/v1/json/{APIKEY}/track-top10.php?s=(artistname}
Return The top 10 Most Loved tracks for an Artist Music Brainz ID *Patreon ONLY*
theaudiodb.com/api/v1/json/{APIKEY}/track-top10-mb.php?s=(Music_Brainz_Artist_ID}
Return The top 50 Most Loved Tracks of Alltime *Patreon ONLY*
theaudiodb.com/api/v1/json/2/mostloved.php?format=track
Return The top 10 Most Loved Albums of Alltime *Patreon ONLY*
theaudiodb.com/api/v1/json/2/mostloved.php?format=album
Preview Images
Most of the time you won't want to download the original large image, just get a small preview. This is possible simple by adding "/preview" onto the end URL. This will give you a small 200px version. This will work with TheAudioDB.com and Fanart.tv URL's in exactly the same way hopefully :)
Original Image - theaudiodb.com/images/media/artist/thumb/xxtwus1340291734.jpg
Small Image - theaudiodb.com/images/media/artist/thumb/xxtwus1340291734.jpg/preview
List every rating made by a user
theaudiodb.com/api/v1/json/{apikey}/ratings-album.php?user={username} *Patreon ONLY*
theaudiodb.com/api/v1/json/{apikey}/ratings-track.php?user={username} *Patreon ONLY*
Example
theaudiodb.com/api/v1/json/2/ratings-track.php?user=Arturo007
Submit Rating via API *Patreon ONLY*
theaudiodb.com/api/v1/json/{apikey}/submit-album.php?user={user}&artist={artist}&album={album}&rating={1-10}&api={apitoken}
theaudiodb.com/api/v1/json/{apikey}/submit-track.php?user={user}&artist={artist}&album={album}&track={track}&rating={1-10}&api={apitoken}
Example (with api token removed) *Patreon ONLY*
theaudiodb.com/api/v1/json/2/submit-album.php?user=zag&artist=Alison%20Krauss&album=Essential&rating=7&api=&api=
theaudiodb.com/api/v1/json/2/submit-track.php?user=zag&artist=Alison_Krauss&album=Essential&track=Restless&rating=7&api=
You can find the API token for on the user page, top right on the menu click on your username (it will only show up if you are logged in as yourself).
theaudiodb.com/user/username
API also provides a responses in JSON like this:
{"result":"SUCCESS New rating"}
{"result":"SUCCESS Updated rating"}
{"result":"ERROR No item found"}
{"result":"ERROR Missing input"}
theaudiodb.com/api/v1/json/2/trending.php?country=us&type=itunes&format=albums *Patreon ONLY*
theaudiodb.com/api/v1/json/2/trending.php?country=us&type=itunes&format=singles *Patreon ONLY*
Parameters:
type: itunes (only for now but will extend in future to more sources)
country: us, gb, de, fr, it
format: albums, singles
Most of the basic calls will work using the test API key of "2".
Rate Limit
Maximum 2 calls per second on all API methods
Upgrade
join our $8 Patreon for a full private API key with upgraded features to use in production.
General search calls
Return Artist details from artist namesearch.php?s={Artist name}
Example - theaudiodb.com/api/v1/json/2/search.php?s=coldplay *Limited to 'coldplay' test
Return all Album details from artist name
searchalbum.php?s={Artist name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/searchalbum.php?s=daft_punk*Patreon ONLY*
Return single album details from artist + album name
searchalbum.php?s={Artist name}&a={Album name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/searchalbum.php?s=daft_punk&a=Homework*Patreon ONLY*
Return track details from artist/track name
searchtrack.php?s={Artist_Name}&t={Single_Name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/searchtrack.php?s=coldplay&t=yellow*Patreon ONLY*
Return Discography for an Artist with Album names and year only
discography.php?s={Artist_Name}
Example - theaudiodb.com/api/v1/json/{APIKEY}/discography.php?s=coldplay
Return Discography for an Artist with Album names and year only using known MBID
discography-mb.php?s={Music_Brainz_Artist_ID} *Patreon ONLY*
Artist Data
Return individul Artist details using known TADB_Artist_IDartist.php?i={artistid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/artist.php?i=112024
Return individual Artist info using a known MusicBrainz_Artist_ID
artist-mb.php?i={mb_artist_id} *Patreon ONLY*
Album Data
Return All Albums for an Artist using known TADB_Artist_IDalbum.php?i={artistid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/album.php?i=112024
Return individual Album info using known TADB_Album_ID
album.php?m={albumid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/album.php?m=2115888
Return individual Album info using a known MusicBrainz_Release-Group_ID
album-mb.php?i={mb_release-group_id} *Patreon ONLY*
Track Data
Return All Tracks for Album from known TADB_Album_IDtrack.php?m={albumid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/track.php?m=2115888
Return individual track info using a known TADB_Track_ID
track.php?h={trackid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/track.php?h=32793500
Return individual track info using a known MusicBrainz_Recording_ID
track-mb.php?i={mb_recording_id} *Patreon ONLY*
Music Videos
Return all the Music videos for a known TADB_Artist_IDmvid.php?i=(artistid}
Example - theaudiodb.com/api/v1/json/{APIKEY}/mvid.php?i=112024
Return all the Music videos for a known Music_Brainz_ID
mvid-mb.php?i=(MbArtistID} *Patreon ONLY*
Return a Music DVD from artist/mdvd name
searchmdvd.php?s={Artist_Name}&a={Music_Dvd_Name} *Patreon ONLY*
Popularity
Return The top 10 Most Loved tracks for an Artist Name *Patreon ONLY*theaudiodb.com/api/v1/json/{APIKEY}/track-top10.php?s=(artistname}
Return The top 10 Most Loved tracks for an Artist Music Brainz ID *Patreon ONLY*
theaudiodb.com/api/v1/json/{APIKEY}/track-top10-mb.php?s=(Music_Brainz_Artist_ID}
Return The top 50 Most Loved Tracks of Alltime *Patreon ONLY*
theaudiodb.com/api/v1/json/2/mostloved.php?format=track
Return The top 10 Most Loved Albums of Alltime *Patreon ONLY*
theaudiodb.com/api/v1/json/2/mostloved.php?format=album
Images
Preview ImagesMost of the time you won't want to download the original large image, just get a small preview. This is possible simple by adding "/preview" onto the end URL. This will give you a small 200px version. This will work with TheAudioDB.com and Fanart.tv URL's in exactly the same way hopefully :)
Original Image - theaudiodb.com/images/media/artist/thumb/xxtwus1340291734.jpg
Small Image - theaudiodb.com/images/media/artist/thumb/xxtwus1340291734.jpg/preview
Listing user ratings via the api
List every rating made by a usertheaudiodb.com/api/v1/json/{apikey}/ratings-album.php?user={username} *Patreon ONLY*
theaudiodb.com/api/v1/json/{apikey}/ratings-track.php?user={username} *Patreon ONLY*
Example
theaudiodb.com/api/v1/json/2/ratings-track.php?user=Arturo007
Submitting user ratings via the api
Submit Rating via API *Patreon ONLY*theaudiodb.com/api/v1/json/{apikey}/submit-album.php?user={user}&artist={artist}&album={album}&rating={1-10}&api={apitoken}
theaudiodb.com/api/v1/json/{apikey}/submit-track.php?user={user}&artist={artist}&album={album}&track={track}&rating={1-10}&api={apitoken}
Example (with api token removed) *Patreon ONLY*
theaudiodb.com/api/v1/json/2/submit-album.php?user=zag&artist=Alison%20Krauss&album=Essential&rating=7&api=&api=
theaudiodb.com/api/v1/json/2/submit-track.php?user=zag&artist=Alison_Krauss&album=Essential&track=Restless&rating=7&api=
You can find the API token for on the user page, top right on the menu click on your username (it will only show up if you are logged in as yourself).
theaudiodb.com/user/username
API also provides a responses in JSON like this:
{"result":"SUCCESS New rating"}
{"result":"SUCCESS Updated rating"}
{"result":"ERROR No item found"}
{"result":"ERROR Missing input"}
Current Trending Music
theaudiodb.com/api/v1/json/2/trending.php?country=us&type=itunes&format=albums *Patreon ONLY*theaudiodb.com/api/v1/json/2/trending.php?country=us&type=itunes&format=singles *Patreon ONLY*
Parameters:
type: itunes (only for now but will extend in future to more sources)
country: us, gb, de, fr, it
format: albums, singles
Song Hash Lookup
theaudiodb.com/api/v1/json/{APIKEY}/search-hash.php?h1={Hash1}&h2={Hash2} *Patreon ONLY*
