The setlist.fm API has been designed to give you easy access to setlist data in order to build fancy websites and other applications. Before starting to use the API, be sure to ...

  1. ... understand how setlist.fm works (the FAQ and the Guidelines are a good starting point),
  2. ... read this documentation carefully and
  3. ... apply for an API key (link for logged in users only) - if you're no registered user yet, then register first (it's free).

If this documentation isn't enough or if you've got other things you'd like to tell us about the API, visit the API Forum.

Note that the setlist.fm API is, according to the API terms of service, only free for non-commercial projects. If you're interested in using the API for commercial purposes, contact us.

About this Service

This service provides methods to get both setlists and components of setlists such as artists, cities, countries or venues.

Supported Content Types

The REST service currently supports XML (default) and JSON content.

To receive a JSON response, set the Accept header to application/json.

Internationalization

(Please note that this is an experimental feature and does not work for all cities!)

Most of the featured methods honor the Accept-Language header. This header is used for localizing cities and countries. The default language is English (en), but you can provide any of the languages Spanish (es), French (fr), German (de), Portuguese (pt), Turkish (tr), Italian (it) or Polish (pl).

E.g. if you search a setlist for a concert that took place in Vienna and you pass "de" as header, you'll get "Wien, Österreich" instead of "Vienna, Austria".
This also works if you use a different language than the country's native language.

E.g. for a concert in New York, you'll get "Nueva York, Estados Unidos" instead of "New York, United States" if you pass "es" as language.

API Keys

API keys (application form) must be included in the request with the x-api-key header.

Version History

Version Docs End of Service
1.0 Docs -
0.1 December 31, 2017

Resources

You may also enjoy the interactive interface provided for this API by Swagger.

Try it out!

path methods description
  • /1.0/artist/{mbid}
  • GET
 
  • /1.0/artist/{mbid}/setlists
  • GET
 
  • /1.0/city/{geoId}
  • GET
 
  • /1.0/search/artists
  • GET
 
  • /1.0/search/cities
  • GET
 
  • /1.0/search/countries
  • GET
 
  • /1.0/search/setlists
  • GET
 
  • /1.0/search/venues
  • GET
 
  • /1.0/setlist/version/{versionId}
  • GET
 
  • /1.0/setlist/{setlistId}
  • GET
 
  • /1.0/user/{userId}
  • GET
 
  • /1.0/user/{userId}/attended
  • GET
 
  • /1.0/user/{userId}/edited
  • GET
 
  • /1.0/venue/{venueId}
  • GET
 
  • /1.0/venue/{venueId}/setlists
  • GET
 

Data Types

JSON

type description
artist This class represents an artist. An artist is a musician or a group of musicians. Each artist has a definite Musicbrainz Identifier (MBID) with which the artist can be uniquely identified.
artists A Result consisting of a list of artists.
cities A Result consisting of a list of cities.
city This class represents a city where Venues are located. Most of the original city data was taken from Geonames.org.
coords Coordinates of a point on the globe. Mostly used for Cities.
countries A Result consisting of a list of countries.
country This class represents a country on earth.
error Returned in case of an error.
set A setlist consists of different (at least one) sets. Sets can either be sets as defined in the Guidelines or encores.
setlist Setlists, that's what it's all about. So if you're trying to use this API without knowing what a setlist is then you're kinda wrong on this page ;-). A setlist can be distinguished from other setlists by its unique id. But as setlist.fm works the wiki way, there can be different versions of one setlist (each time a user updates a setlist a new version gets created). These different versions have a unique id on its own. So setlists can have the same id although they differ as far as the content is concerned - thus the best way to check if two setlists are the same is to compare their versionIds.
setlists A Result consisting of a list of setlists.
song This class represents a song that is part of a Set.
tour The tour a setlist was a part of.
user This class represents a user.
venue Venues are places where concerts take place. They usually consist of a venue name and a city - but there are also some venues that do not have a city attached yet. In such a case, the city simply isn't set and the city and country may (but do not have to) be in the name.
venues A Result consisting of a list of venues.

XML

Default Namespace
type description
artist This class represents an artist. An artist is a musician or a group of musicians. Each artist has a definite Musicbrainz Identifier (MBID) with which the artist can be uniquely identified.
artists A Result consisting of a list of artists.
cities A Result consisting of a list of cities.
city This class represents a city where Venues are located. Most of the original city data was taken from Geonames.org.
coords Coordinates of a point on the globe. Mostly used for Cities.
countries A Result consisting of a list of countries.
country This class represents a country on earth.
error Returned in case of an error.
result

If a request returns a list of items they're always wrapped into a Result. As there is a maximum amount of items to be returned at once a Result consists of the total amount of items (total), how many items per page you get (itemsPerPage), the current page (page) and the current list of items.

E.g. if there are 35 items, itemsPerPage is 10 and the current page is 2, then items 11 to 20 are in the list.

set A setlist consists of different (at least one) sets. Sets can either be sets as defined in the Guidelines or encores.
setlist Setlists, that's what it's all about. So if you're trying to use this API without knowing what a setlist is then you're kinda wrong on this page ;-). A setlist can be distinguished from other setlists by its unique id. But as setlist.fm works the wiki way, there can be different versions of one setlist (each time a user updates a setlist a new version gets created). These different versions have a unique id on its own. So setlists can have the same id although they differ as far as the content is concerned - thus the best way to check if two setlists are the same is to compare their versionIds.
setlists A Result consisting of a list of setlists.
song This class represents a song that is part of a Set.
tour The tour a setlist was a part of.
user This class represents a user.
venue Venues are places where concerts take place. They usually consist of a venue name and a city - but there are also some venues that do not have a city attached yet. In such a case, the city simply isn't set and the city and country may (but do not have to) be in the name.
venues A Result consisting of a list of venues.