setlist.fm API

Data

  • Default Namespace
  • XML Schema File: ns0.xsd

The data in this namespace is divided into elements and types. Types define the structure of the data. Elements define specific instances of the types, and are therefore more relevant to REST endpoints, which generally consume and/or produce elements.

The following elements are members of this namespace:

The following types are members of this namespace:

Element 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.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <artist disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </artist>

Element artists

A Result consisting of a list of artists.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <artists total="..." page="..." itemsPerPage="..."> <artist disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </artist> <artist disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <!--...--> </artist> <!--...more "artist" elements...--> </artists>

Element cities

A Result consisting of a list of cities.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <cities total="..." page="..." itemsPerPage="..."> <cities id="..." name="..." state="..." stateCode="..."> <coords long="..." lat="..." /> <country name="..." code="..." /> </cities> <cities id="..." name="..." state="..." stateCode="..."> <!--...--> </cities> <!--...more "cities" elements...--> </cities>

Element city

This class represents a city where Venues are located. Most of the original city data was taken from Geonames.org.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <city id="..." name="..." state="..." stateCode="..."> <coords long="..." lat="..." /> <country name="..." code="..." /> </city>

Element countries

A Result consisting of a list of countries.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <countries total="..." page="..." itemsPerPage="..."> <country name="..." code="..." /> <country name="..." code="..."> <!--...--> </country> <!--...more "country" elements...--> </countries>

Element country

This class represents a country on earth.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <country name="..." code="..." />

Element 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.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <setlist id="..." eventDate="..." lastUpdated="..." versionId="..." tour="..." lastFmEventId="..."> <artist disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </artist> <venue id="..." name="..."> <city id="..." name="..." state="..." stateCode="..."> <coords long="..." lat="..." /> <country name="..." code="..." /> </city> <url>...</url> </venue> <sets> <set encore="..." name="..."> <song name="..." tape="..."> <with disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </with> <cover disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </cover> <info>...</info> </song> <song name="..." tape="..."> <!--...--> </song> <!--...more "song" elements...--> </set> <set encore="..." name="..."> <!--...--> </set> <!--...more "set" elements...--> </sets> <info>...</info> <url>...</url> </setlist>

Element setlists

A Result consisting of a list of setlists.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <setlists total="..." page="..." itemsPerPage="..."> <setlist id="..." eventDate="..." lastUpdated="..." versionId="..." tour="..." lastFmEventId="..."> <artist disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </artist> <venue id="..." name="..."> <city id="..." name="..." state="..." stateCode="..."> <coords long="..." lat="..." /> <country name="..." code="..." /> </city> <url>...</url> </venue> <sets> <set encore="..." name="..."> <song name="..." tape="..."> <with disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </with> <cover disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </cover> <info>...</info> </song> <song name="..." tape="..."> <!--...--> </song> <!--...more "song" elements...--> </set> <set encore="..." name="..."> <!--...--> </set> <!--...more "set" elements...--> </sets> <info>...</info> <url>...</url> </setlist> <setlist id="..." eventDate="..." lastUpdated="..." versionId="..." tour="..." lastFmEventId="..."> <!--...--> </setlist> <!--...more "setlist" elements...--> </setlists>

Element song

This class represents a song that is part of a Set.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <song name="..." tape="..."> <with disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </with> <cover disambiguation="..." mbid="..." tmid="..." name="..." sortName="..."> <url>...</url> </cover> <info>...</info> </song>

Element user

This class represents a user.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <user flickr="..." twitter="..." website="..." userId="..." lastFm="..." mySpace="..." fullname="..."> <about>...</about> <url>...</url> </user>

Element 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.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <venue id="..." name="..."> <city id="..." name="..." state="..." stateCode="..."> <coords long="..." lat="..." /> <country name="..." code="..." /> </city> <url>...</url> </venue>

Element venues

A Result consisting of a list of venues.

Example XML

<?xml version="1.0" encoding="UTF-8"?> <venues total="..." page="..." itemsPerPage="..."> <venue id="..." name="..."> <city id="..." name="..." state="..." stateCode="..."> <coords long="..." lat="..." /> <country name="..." code="..." /> </city> <url>...</url> </venue> <venue id="..." name="..."> <!--...--> </venue> <!--...more "venue" elements...--> </venues>

Type 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.

Attributes

name type description
disambiguation string disambiguation to distinguish between artists with same names
mbid string unique Musicbrainz Identifier (MBID), e.g. "b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d"
tmid int unique Ticket Master Identifier (TMID), e.g. 1953
name string the artist's name, e.g. "The Beatles"
sortName string the artist's sort name, e.g. "Beatles, The" or "Springsteen, Bruce"

Child Elements

name (type) min/max
occurs
description
url (string) 0/1 (no documentation provided)

Type artists

A Result consisting of a list of artists.

Child Elements

name (type) min/max
occurs
description
artist (artist) 0/unbounded result list of artists

Type cities

A Result consisting of a list of cities.

Child Elements

name (type) min/max
occurs
description
cities (city) 0/unbounded result list of cities

Type city

This class represents a city where Venues are located. Most of the original city data was taken from Geonames.org.

Attributes

name type description
id string unique identifier
name string the city's name, depending on the language valid values are e.g. "Müchen" or Munich
state string The name of city's state, e.g. "Bavaria" or "Florida"
stateCode string The code of the city's state. For most countries this 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.

Child Elements

name (type) min/max
occurs
description
coords (coords) 0/1 The city's coordinates. Usually the coordinates of the city centre are used.
country (country) 0/1 The city's country.

Type coords

Coordinates of a point on the globe. Mostly used for Cities.

Attributes

name type description
long double The longitude part of the coordinates.
lat double The latitude part of the coordinates.

Type countries

A Result consisting of a list of countries.

Child Elements

name (type) min/max
occurs
description
country (country) 0/unbounded result list of countries

Type country

This class represents a country on earth.

Attributes

name type description
name string The country's name. Can be a localized name - e.g. "Austria" or "Österreich" for Austria if the German name was requested.
code string The country's ISO code. E.g. "ie" for Ireland

Type 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.

Attributes

name type description
total int the total amount of items matching the query
page int the current page
itemsPerPage int the amount of items you get per page

Type set

A setlist consists of different (at least one) sets. Sets can either be sets as defined in the Guidelines or encores.

Attributes

name type description
encore int 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.
name string the description/name of the set. E.g. "Acoustic set" or "Paul McCartney solo"

Child Elements

name (type) min/max
occurs
description
song (song) 1/unbounded (no documentation provided)

Type 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.

Attributes

name type description
id string unique identifier
eventDate string date of the concert in the format "dd-MM-yyyy"
lastUpdated string date, time and time zone of the last update to this setlist in the format "yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ"
versionId string unique identifier of the version
tour string the setlist's tour
lastFmEventId int the id this event has on last.fm

Child Elements

name (type) min/max
occurs
description
artist (artist) 0/1 (no documentation provided)
venue (venue) 0/1 (no documentation provided)
sets/set (set) 0/unbounded (no documentation provided)
info (string) 0/1 (no documentation provided)
url (string) 0/1 (no documentation provided)

Type setlists

A Result consisting of a list of setlists.

Child Elements

name (type) min/max
occurs
description
setlist (setlist) 0/unbounded result list of setlists

Type song

This class represents a song that is part of a Set.

Attributes

name type description
name string The name of the song. E.g. Yesterday or "Wish You Were Here"
tape boolean The song came from tape rather than being performed live. See the tape section of the guidelines for valid usage.

Child Elements

name (type) min/max
occurs
description
with (artist) 0/1 A different Artist than the performing one that joined the stage for this song.
cover (artist) 0/1 The original Artist of this song, if different to the performing artist.
info (string) 0/1 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 user

This class represents a user.

Attributes

name type description
flickr string (no documentation provided)
twitter string (no documentation provided)
website string (no documentation provided)
userId string (no documentation provided)
lastFm string (no documentation provided)
mySpace string (no documentation provided)
fullname string (no documentation provided)

Child Elements

name (type) min/max
occurs
description
about (string) 0/1 (no documentation provided)
url (string) 0/1 (no documentation provided)

Type 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.

Attributes

name type description
id string unique identifier
name string the name of the venue, usually without city and country. E.g. "Madison Square Garden" or "Royal Albert Hall"

Child Elements

name (type) min/max
occurs
description
city (city) 0/1 the city in which the venue is located
url (string) 0/1 (no documentation provided)

Type venues

A Result consisting of a list of venues.

Child Elements

name (type) min/max
occurs
description
venue (venue) 0/unbounded result list of venues