setlist.fm /1.0/artist/{mbid}/setlists API
The /1.0/artist/{mbid}/setlists API from setlist.fm — 1 operation(s) for /1.0/artist/{mbid}/setlists.
OpenAPI Specification
swagger: '2.0'
info:
description: '<p>
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 ...
<ol>
<li>... understand how setlist.fm works (the <a href="https://www.setlist.fm/faq">FAQ</a> and the
<a href="https://www.setlist.fm/guidelines">Guidelines</a> are a good starting point),</li>
<li>... read this documentation carefully and</li>
<li>... <a href="https://www.setlist.fm/settings/api">apply for an API key</a> (link for logged in users only) - if
you''re no registered user yet, then <a href="https://www.setlist.fm/signup">register first</a> (it''s free).</li>
</ol>
</p>
<p>
If this documentation isn''t enough or if you''ve got other things you''d like to tell us about the API, visit the
<a href="https://www.setlist.fm/forum/setlistfm/setlistfm-api">API Forum</a>.
</p>
<p>
Note that the setlist.fm API is, according to the <a href="https://www.setlist.fm/help/api-terms">API terms of
service</a>, only free for non-commercial projects. If you''re interested in using the API for commercial purposes,
<a href="https://www.setlist.fm/contact">contact us</a>.
</p>
<h2>About this Service</h2>
<p>
This service provides methods to get both setlists and components of setlists such as artists, cities, countries or
venues.
</p>
<h2>Supported Content Types</h2>
<p>
The REST service currently supports XML (default) and JSON content.
</p>
<p>
To receive a JSON response, set the <code>Accept</code>
<a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">header</a> to <em>application/json</em>.
</p>
<h2>Internationalization</h2>
<p>
<small>(Please note that this is an experimental feature and does not work for all cities!)</small>
</p>
<p>
Most of the featured methods honor the <code>Accept-Language</code>
<a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4">header</a>. 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).
</p>
<p>
E.g. if you search a setlist for a concert that took place in Vienna and you pass "de" as header, you''ll
get <em>"Wien, Österreich"</em> instead of <em>"Vienna, Austria"</em>.<br/>
This also works if you use a different language than the country''s native language.
</p>
<p>
E.g. for a concert in New York, you''ll get <em>"Nueva York, Estados Unidos"</em> instead of <em>"New
York, United States"</em> if you pass "es" as language.
</p>
<h2>API Keys</h2>
API keys (<a href="https://www.setlist.fm/settings/api">application form</a>) must be included in the request with
the <code>x-api-key</code> header.
<h2>Version History</h2>
<table class="table table-bordered table-versions">
<thead>
<tr>
<th>Version</th>
<th>Docs</th>
<th>End of Service</th>
</tr>
</thead> <tbody>
<tr>
<td><strong>1.0</strong></td>
<td><a href="/docs/1.0">Docs</a></td>
<td>-</li>
</tr>
<tr>
<td><strong>0.1</strong></td>
<td></td>
<td>December 31, 2017</li>
</tr>
</tbody>
</table>'
version: '1.0'
title: setlist.fm /1.0/artist/{mbid} /1.0/artist/{mbid} /1.0/artist/{mbid}/setlists API
basePath: /rest
schemes: []
tags:
- name: /1.0/artist/{mbid}/setlists
paths:
/1.0/artist/{mbid}/setlists:
get:
tags:
- /1.0/artist/{mbid}/setlists
summary: .
description: '<p>
Get a list of an artist''s setlists.
</p>'
operationId: resource__1.0_artist__mbid__setlists_getArtistSetlists_GET
produces:
- application/xml
- application/json
parameters:
- name: mbid
in: path
required: true
type: string
description: the Musicbrainz MBID of the artist
- name: p
in: query
default: '1'
type: integer
description: the number of the result page
responses:
'200':
schema:
description: ''
$ref: '#/definitions/json_Setlists'
headers: {}
examples:
application/json:
setlist:
- 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: {}
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: '...'
encore: 12345
song:
- {}
- {}
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
- artist:
mbid: '...'
name: '...'
sortName: '...'
disambiguation: '...'
url: '...'
venue:
city: {}
url: '...'
id: '...'
name: '...'
tour:
name: '...'
set:
- name: '...'
encore: 12345
song:
- {}
- {}
- name: '...'
encore: 12345
song:
- {}
- {}
info: '...'
url: '...'
id: '...'
versionId: '...'
eventDate: '...'
lastUpdated: '...'
total: 42
page: 1
itemsPerPage: 20
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. <em>"Madison Square Garden"</em> or
<em>"Royal Albert Hall"</em>'
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 <a href="https://www.setlist.fm/guidelines">setlist.fm
guidelines</a> 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 <a href="http://last.fm/">last.fm</a> (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
<a href="https://www.setlist.fm/">setlist.fm</a> 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. <em>"Acoustic set"</em> or <em>"Paul McCartney
solo"</em>'
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
<a href="https://www.setlist.fm/guidelines">Guidelines</a> or encores.'
json_Artist:
type: object
title: artist
properties:
mbid:
example: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d
description: unique Musicbrainz Identifier (MBID), e.g. <em>"b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d"</em>
type: string
tmid:
example: 735610
description: unique Ticket Master Identifier (TMID), e.g. <em>735610</em> (deprecated)
type: number
name:
example: The Beatles
description: the artist's name, e.g. <em>"The Beatles"</em>
type: string
sortName:
example: Beatles, The
description: the artist's sort name, e.g. <em>"Beatles, The"</em> or <em>"Springsteen, Bruce"</em>
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
<a href="http://wiki.musicbrainz.org/MBID">Musicbrainz Identifier</a> (MBID) with which the artist can be uniquely
identified.'
json_Country:
type: object
title: country
properties:
code:
example: US
description: 'The country''s <a href= "http://www.iso.org/iso/english_country_names_and_code_elements" >ISO code</a>. E.g.
<em>"ie"</em> for Ireland'
type: string
name:
example: United States
description: 'The country''s name. Can be a localized name - e.g. <em>"Austria"</em> or
<em>"Österreich"</em> 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. <em>"Müchen"</em> or
<em>Munich</em>'
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 <em>"CA"</em> or <em>"02"</em>
which in turn get uniquely identifiable when combined with the state''s country:
<em>"US.CA"</em> for California, United States or <em>"DE.02"</em> for Bavaria, Germany
For a complete list of available states (that aren''t necessarily used in this database) is available in
<a href= "http://download.geonames.org/export/dump/admin1CodesASCII.txt">a textfile on geonames.org</a>.
Note that this code is only unique combined with the city''s Country. The code alone is
<strong>not</strong> unique.'
type: string
state:
example: California
description: The name of city's state, e.g. <em>"Bavaria"</em> or <em>"Florida"</em>
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
<a href="http://geonames.org/">Geonames.org</a>.'
json_Setlists:
type: object
title: setlists
properties:
setlist:
description: result list of setlists
type: array
items:
$ref: '#/definitions/json_Setlist'
total:
example: 42
description: the total amount of items matching the query
type: number
page:
example: 1
description: the current page. starts at 1
type: number
itemsPerPage:
example: 20
description: the amount of items you get per page
type: number
example:
setlist:
- 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: {}
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: '...'
encore: 12345
song:
- {}
- {}
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
- artist:
mbid: '...'
name: '...'
sortName: '...'
disambiguation: '...'
url: '...'
venue:
city: {}
url: '...'
id: '...'
name: '...'
tour:
name: '...'
set:
- name: '...'
encore: 12345
song:
- {}
- {}
- name: '...'
encore: 12345
song:
- {}
- {}
info: '...'
url: '...'
id: '...'
versionId: '...'
eventDate: '...'
lastUpdated: '...'
total: 42
page: 1
itemsPerPage: 20
description: A Result consisting of a list of setlists.
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. <em>Yesterday</em> or <em>"Wish You Were Here"</em>
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 <a href="https://www.setlist.fm/guidelines">setlist.fm guidelines</a> 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
<a href="https://www.setlist.fm/guidelines#tape-songs">tape section of the guidelines</a> 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.