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 ...
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.
This service provides methods to get both setlists and components of setlists such as artists, cities, countries or venues.
The REST service currently supports XML (default) and JSON content.
To receive a JSON response, set the Accept
header to application/json.
(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.
x-api-key header.
| Version | Docs | End of Service |
|---|---|---|
| 1.0 | Docs | - |
| 0.1 | December 31, 2017 |
Deprecated - always returns Not Found (404)
Returns a setlist for the given versionId. The setlist returned isn''t necessarily the most recent version. E.g. if you pass the versionId of a setlist that got edited since you last accessed it, you''ll get the same version as last time.
' operationId: resource__1.0_setlist_version__versionId__getSetlistVersion_GET produces: - application/xml - application/json parameters: - name: versionId in: path required: true type: string description: the version id responses: '200': schema: description: '' $ref: '#/definitions/json_Setlist' headers: {} examples: application/json: artist: mbid: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d name: The Beatles sortName: Beatles, The disambiguation: John, Paul, George and Ringo url: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html venue: city: id: '5357527' name: Hollywood stateCode: CA state: California coords: {} country: {} url: https://www.setlist.fm/venue/compaq-center-san-jose-ca-usa-6bd6ca6e.html id: 6bd6ca6e name: Compaq Center tour: name: North American Tour 1964 set: - name: '...' encore: 12345 song: - name: Yesterday with: {} cover: {} info: '...' tape: false - name: '...' with: {} cover: {} info: '...' tape: true - name: '...' encore: 12345 song: - name: '...' with: {} cover: {} info: '...' tape: true - name: '...' with: {} cover: {} info: '...' tape: true info: Recorded and published as 'The Beatles at the Hollywood Bowl' url: https://www.setlist.fm/setlist/the-beatles/1964/hollywood-bowl-hollywood-ca-63de4613.html id: 63de4613 versionId: 7be1aaa0 eventDate: 23-08-1964 lastUpdated: 2013-10-20T05:18:08.000+0000 description: Success definitions: json_Venue: type: object title: venue properties: city: description: the city in which the venue is located $ref: '#/definitions/json_City' url: example: https://www.setlist.fm/venue/compaq-center-san-jose-ca-usa-6bd6ca6e.html description: the attribution url type: string id: example: 6bd6ca6e description: unique identifier type: string name: example: Compaq Center description: 'the name of the venue, usually without city and country. E.g. "Madison Square Garden" or "Royal Albert Hall"' type: string example: city: id: '5357527' name: Hollywood stateCode: CA state: California coords: long: -118.3267434 lat: 34.0983425 country: code: US name: United States url: https://www.setlist.fm/venue/compaq-center-san-jose-ca-usa-6bd6ca6e.html id: 6bd6ca6e name: Compaq Center description: '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.' json_Setlist: type: object title: setlist properties: artist: description: the setlist's artist $ref: '#/definitions/json_Artist' venue: description: the setlist's venue $ref: '#/definitions/json_Venue' tour: description: the setlist's tour $ref: '#/definitions/json_Tour' set: description: all sets of this setlist type: array items: $ref: '#/definitions/json_Set' info: example: Recorded and published as 'The Beatles at the Hollywood Bowl' description: 'additional information on the concert - see the setlist.fm guidelines for a complete list of allowed content.' type: string url: example: https://www.setlist.fm/setlist/the-beatles/1964/hollywood-bowl-hollywood-ca-63de4613.html description: the attribution url to which you have to link to wherever you use data from this setlist in your application type: string id: example: 63de4613 description: unique identifier type: string versionId: example: 7be1aaa0 description: unique identifier of the version type: string lastFmEventId: example: 1164056 description: the id this event has on last.fm (deprecated) type: number eventDate: example: 23-08-1964 description: date of the concert in the format "dd-MM-yyyy" type: string lastUpdated: example: 2013-10-20T05:18:08.000+0000 description: 'date, time and time zone of the last update to this setlist in the format "yyyy-MM-dd''T''HH:mm:ss.SSSZZZZZ"' type: string example: artist: mbid: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d name: The Beatles sortName: Beatles, The disambiguation: John, Paul, George and Ringo url: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html venue: city: id: '5357527' name: Hollywood stateCode: CA state: California coords: {} country: {} url: https://www.setlist.fm/venue/compaq-center-san-jose-ca-usa-6bd6ca6e.html id: 6bd6ca6e name: Compaq Center tour: name: North American Tour 1964 set: - name: '...' encore: 12345 song: - name: Yesterday with: {} cover: {} info: '...' tape: false - name: '...' with: {} cover: {} info: '...' tape: true - name: '...' encore: 12345 song: - name: '...' with: {} cover: {} info: '...' tape: true - name: '...' with: {} cover: {} info: '...' tape: true info: Recorded and published as 'The Beatles at the Hollywood Bowl' url: https://www.setlist.fm/setlist/the-beatles/1964/hollywood-bowl-hollywood-ca-63de4613.html id: 63de4613 versionId: 7be1aaa0 eventDate: 23-08-1964 lastUpdated: 2013-10-20T05:18:08.000+0000 description: '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.' json_Set: type: object title: set properties: name: description: 'the description/name of the set. E.g. "Acoustic set" or "Paul McCartney solo"' type: string encore: description: 'if the set is an encore, this is the number of the encore, starting with 1 for the first encore, 2 for the second and so on.' type: number song: description: this set's songs type: array items: $ref: '#/definitions/json_Song' example: name: '...' encore: 12345 song: - name: Yesterday with: mbid: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d name: The Beatles sortName: Beatles, The disambiguation: John, Paul, George and Ringo url: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html cover: mbid: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d name: The Beatles sortName: Beatles, The disambiguation: John, Paul, George and Ringo url: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html info: '...' tape: false - name: '...' with: mbid: '...' name: '...' sortName: '...' disambiguation: '...' url: '...' cover: mbid: '...' name: '...' sortName: '...' disambiguation: '...' url: '...' info: '...' tape: true description: 'A setlist consists of different (at least one) sets. Sets can either be sets as defined in the Guidelines or encores.' json_Artist: type: object title: artist properties: mbid: example: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d description: unique Musicbrainz Identifier (MBID), e.g. "b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d" type: string tmid: example: 735610 description: unique Ticket Master Identifier (TMID), e.g. 735610 (deprecated) type: number name: example: The Beatles description: the artist's name, e.g. "The Beatles" type: string sortName: example: Beatles, The description: the artist's sort name, e.g. "Beatles, The" or "Springsteen, Bruce" type: string disambiguation: example: John, Paul, George and Ringo description: disambiguation to distinguish between artists with same names type: string url: example: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html description: the attribution url type: string example: mbid: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d name: The Beatles sortName: Beatles, The disambiguation: John, Paul, George and Ringo url: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html description: '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.' json_Country: type: object title: country properties: code: example: US description: 'The country''s ISO code. E.g. "ie" for Ireland' type: string name: example: United States description: 'The country''s name. Can be a localized name - e.g. "Austria" or "Österreich" for Austria if the German name was requested.' type: string example: code: US name: United States description: This class represents a country on earth. json_City: type: object title: city properties: id: example: '5357527' description: unique identifier type: string name: example: Hollywood description: 'the city''s name, depending on the language valid values are e.g. "Müchen" or Munich' type: string stateCode: example: CA description: 'The code of the city''s state. For most countries this is a two-digit numeric code, with which the state can be identified uniquely in the specific Country. The code can also be a String for other cities. Valid examples are "CA" or "02" which in turn get uniquely identifiable when combined with the state''s country: "US.CA" for California, United States or "DE.02" for Bavaria, Germany For a complete list of available states (that aren''t necessarily used in this database) is available in a textfile on geonames.org. Note that this code is only unique combined with the city''s Country. The code alone is not unique.' type: string state: example: California description: The name of city's state, e.g. "Bavaria" or "Florida" type: string coords: description: The city's coordinates. Usually the coordinates of the city centre are used. $ref: '#/definitions/json_Coords' country: description: The city's country. $ref: '#/definitions/json_Country' example: id: '5357527' name: Hollywood stateCode: CA state: California coords: long: -118.3267434 lat: 34.0983425 country: code: US name: United States description: 'This class represents a city where Venues are located. Most of the original city data was taken from Geonames.org.' json_Coords: type: object title: coords properties: long: example: -118.3267434 description: The longitude part of the coordinates. type: number lat: example: 34.0983425 description: The latitude part of the coordinates. type: number example: long: -118.3267434 lat: 34.0983425 description: Coordinates of a point on the globe. Mostly used for Cities. json_Song: type: object title: song properties: name: example: Yesterday description: The name of the song. E.g. Yesterday or "Wish You Were Here" type: string with: description: A different Artist than the performing one that joined the stage for this song. $ref: '#/definitions/json_Artist' cover: description: The original Artist of this song, if different to the performing artist. $ref: '#/definitions/json_Artist' info: description: 'Special incidents or additional information about the way the song was performed at this specific concert. See the setlist.fm guidelines for a complete list of allowed content.' type: string tape: example: false description: 'The song came from tape rather than being performed live. See the tape section of the guidelines for valid usage.' type: boolean example: name: Yesterday with: mbid: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d name: The Beatles sortName: Beatles, The disambiguation: John, Paul, George and Ringo url: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html cover: mbid: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d name: The Beatles sortName: Beatles, The disambiguation: John, Paul, George and Ringo url: https://www.setlist.fm/setlists/the-beatles-23d6a88b.html info: '...' tape: false description: This class represents a song that is part of a Set. json_Tour: type: object title: tour properties: name: example: North American Tour 1964 description: The name of the tour. type: string example: name: North American Tour 1964 description: The tour a setlist was a part of.