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:

artist
artists
cities
city
countries
country
setlist
setlists
song
user
venue
venues

The following types are members of this namespace:

artist
artists
cities
city
coords
countries
country
result
set
setlist
setlists
song
user
venue
venues

Element artist

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.

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<artist disambiguation="..." mbid="..." name="..." sortName="...">
  <url>
    <!--content of type 'string'-->
    ...
  </url>
</artist>

Example JSON

{
  "disambiguation" : "...",
  "mbid" : "...",
  "name" : "...",
  "sortName" : "...",
  "url" : "..."
}

Element artists

Type: artists

A Result consisting of a list of artists.

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<artists>
  <artist disambiguation="..." mbid="..." name="..." sortName="...">
    <!--content of type 'artist'-->
    <url>
      <!--content of type 'string'-->
      ...
    </url>
  </artist>
  <artist>
    <!--(another 'artist' type)-->
  </artist>
  <!--...more "artist" elements...-->
</artists>

Example JSON

{
  "artist" : [ {
    "disambiguation" : "...",
    "mbid" : "...",
    "name" : "...",
    "sortName" : "...",
    "url" : "..."
  }, ... ]
}

Element cities

Type: cities

A Result consisting of a list of cities.

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<cities>
  <cities id="..." name="..." state="..." stateCode="...">
    <!--content of type 'city'-->
    <coords long="..." lat="...">
      <!--content of type 'coords'-->
    </coords>
    <country name="..." code="...">
      <!--content of type 'country'-->
    </country>
  </cities>
  <cities>
    <!--(another 'city' type)-->
  </cities>
  <!--...more "cities" elements...-->
</cities>

Example JSON

{
  "cities" : [ {
    "id" : "...",
    "name" : "...",
    "state" : "...",
    "stateCode" : "...",
    "coords" : {
      "long" : ...,
      "lat" : ...
    },
    "country" : {
      "name" : "...",
      "code" : "..."
    }
  }, ... ]
}

Element city

Type: 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="...">
    <!--content of type 'coords'-->
  </coords>
  <country name="..." code="...">
    <!--content of type 'country'-->
  </country>
</city>

Example JSON

{
  "id" : "...",
  "name" : "...",
  "state" : "...",
  "stateCode" : "...",
  "coords" : {
    "long" : ...,
    "lat" : ...
  },
  "country" : {
    "name" : "...",
    "code" : "..."
  }
}

Element countries

Type: countries

A Result consisting of a list of countries.

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<countries>
  <country name="..." code="...">
    <!--content of type 'country'-->
  </country>
  <country>
    <!--(another 'country' type)-->
  </country>
  <!--...more "country" elements...-->
</countries>

Example JSON

{
  "country" : [ {
    "name" : "...",
    "code" : "..."
  }, ... ]
}

Element country

Type: country

This class represents a country on earth.

Example XML

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

Example JSON

{
  "name" : "...",
  "code" : "..."
}

Element setlist

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.

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<setlist id="..." eventDate="..." versionId="..." tour="..." lastFmEventId="...">
  <artist disambiguation="..." mbid="..." name="..." sortName="...">
    <!--content of type 'artist'-->
    <url>
      <!--content of type 'string'-->
      ...
    </url>
  </artist>
  <venue id="..." name="...">
    <!--content of type 'venue'-->
    <city id="..." name="..." state="..." stateCode="...">
      <!--content of type 'city'-->
      <coords long="..." lat="...">
        <!--content of type 'coords'-->
      </coords>
      <country name="..." code="...">
        <!--content of type 'country'-->
      </country>
    </city>
    <url>
      <!--content of type 'string'-->
      ...
    </url>
  </venue>
  <sets>
    <set name="...">
      <!--content of type 'set'-->
      <song name="...">
        <!--content of type 'song'-->
        <with disambiguation="..." mbid="..." name="..." sortName="...">
          <!--content of type 'artist'-->
          <url>
            <!--content of type 'string'-->
            ...
          </url>
        </with>
        <cover disambiguation="..." mbid="..." name="..." sortName="...">
          <!--content of type 'artist'-->
          <url>
            <!--content of type 'string'-->
            ...
          </url>
        </cover>
        <info>
          <!--content of type 'string'-->
          ...
        </info>
      </song>
      <song>
        <!--(another 'song' type)-->
      </song>
      <!--...more "song" elements...-->
    </set>
    <set>
      <!--(another 'set' type)-->
    </set>
    <!--...more "set" elements...-->
  </sets>
  <info>
    <!--content of type 'string'-->
    ...
  </info>
  <url>
    <!--content of type 'string'-->
    ...
  </url>
</setlist>

Example JSON

{
  "id" : "...",
  "eventDate" : "...",
  "versionId" : "...",
  "tour" : "...",
  "lastFmEventId" : ...,
  "artist" : {
    "disambiguation" : "...",
    "mbid" : "...",
    "name" : "...",
    "sortName" : "...",
    "url" : "..."
  },
  "venue" : {
    "id" : "...",
    "name" : "...",
    "city" : {
      "id" : "...",
      "name" : "...",
      "state" : "...",
      "stateCode" : "...",
      "coords" : {
        "long" : ...,
        "lat" : ...
      },
      "country" : {
        "name" : "...",
        "code" : "..."
      }
    },
    "url" : "..."
  },
  "sets" : [ {
    "name" : "...",
    "song" : [ {
      "name" : "...",
      "with" : {
        "disambiguation" : "...",
        "mbid" : "...",
        "name" : "...",
        "sortName" : "...",
        "url" : "..."
      },
      "cover" : {
        "disambiguation" : "...",
        "mbid" : "...",
        "name" : "...",
        "sortName" : "...",
        "url" : "..."
      },
      "info" : "..."
    }, ... ]
  }, ... ],
  "info" : "...",
  "url" : "..."
}

Element setlists

Type: setlists

A Result consisting of a list of setlists.

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<setlists>
  <setlist id="..." eventDate="..." versionId="..." tour="..." lastFmEventId="...">
    <!--content of type 'setlist'-->
    <artist disambiguation="..." mbid="..." name="..." sortName="...">
      <!--content of type 'artist'-->
      <url>
        <!--content of type 'string'-->
        ...
      </url>
    </artist>
    <venue id="..." name="...">
      <!--content of type 'venue'-->
      <city id="..." name="..." state="..." stateCode="...">
        <!--content of type 'city'-->
        <coords long="..." lat="...">
          <!--content of type 'coords'-->
        </coords>
        <country name="..." code="...">
          <!--content of type 'country'-->
        </country>
      </city>
      <url>
        <!--content of type 'string'-->
        ...
      </url>
    </venue>
    <sets>
      <set name="...">
        <!--content of type 'set'-->
        <song name="...">
          <!--content of type 'song'-->
          <with disambiguation="..." mbid="..." name="..." sortName="...">
            <!--content of type 'artist'-->
            <url>
              <!--content of type 'string'-->
              ...
            </url>
          </with>
          <cover disambiguation="..." mbid="..." name="..." sortName="...">
            <!--content of type 'artist'-->
            <url>
              <!--content of type 'string'-->
              ...
            </url>
          </cover>
          <info>
            <!--content of type 'string'-->
            ...
          </info>
        </song>
        <song>
          <!--(another 'song' type)-->
        </song>
        <!--...more "song" elements...-->
      </set>
      <set>
        <!--(another 'set' type)-->
      </set>
      <!--...more "set" elements...-->
    </sets>
    <info>
      <!--content of type 'string'-->
      ...
    </info>
    <url>
      <!--content of type 'string'-->
      ...
    </url>
  </setlist>
  <setlist>
    <!--(another 'setlist' type)-->
  </setlist>
  <!--...more "setlist" elements...-->
</setlists>

Example JSON

{
  "setlist" : [ {
    "id" : "...",
    "eventDate" : "...",
    "versionId" : "...",
    "tour" : "...",
    "lastFmEventId" : ...,
    "artist" : {
      "disambiguation" : "...",
      "mbid" : "...",
      "name" : "...",
      "sortName" : "...",
      "url" : "..."
    },
    "venue" : {
      "id" : "...",
      "name" : "...",
      "city" : {
        "id" : "...",
        "name" : "...",
        "state" : "...",
        "stateCode" : "...",
        "coords" : {
          "long" : ...,
          "lat" : ...
        },
        "country" : {
          "name" : "...",
          "code" : "..."
        }
      },
      "url" : "..."
    },
    "sets" : [ {
      "name" : "...",
      "song" : [ {
        "name" : "...",
        "with" : {
          "disambiguation" : "...",
          "mbid" : "...",
          "name" : "...",
          "sortName" : "...",
          "url" : "..."
        },
        "cover" : {
          "disambiguation" : "...",
          "mbid" : "...",
          "name" : "...",
          "sortName" : "...",
          "url" : "..."
        },
        "info" : "..."
      }, ... ]
    }, ... ],
    "info" : "...",
    "url" : "..."
  }, ... ]
}

Element song

Type: song

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

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<song name="...">
  <with disambiguation="..." mbid="..." name="..." sortName="...">
    <!--content of type 'artist'-->
    <url>
      <!--content of type 'string'-->
      ...
    </url>
  </with>
  <cover disambiguation="..." mbid="..." name="..." sortName="...">
    <!--content of type 'artist'-->
    <url>
      <!--content of type 'string'-->
      ...
    </url>
  </cover>
  <info>
    <!--content of type 'string'-->
    ...
  </info>
</song>

Example JSON

{
  "name" : "...",
  "with" : {
    "disambiguation" : "...",
    "mbid" : "...",
    "name" : "...",
    "sortName" : "...",
    "url" : "..."
  },
  "cover" : {
    "disambiguation" : "...",
    "mbid" : "...",
    "name" : "...",
    "sortName" : "...",
    "url" : "..."
  },
  "info" : "..."
}

Element user

Type: user

This class represents a user.

Example XML

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

Example JSON

{
  "flickr" : "...",
  "twitter" : "...",
  "website" : "...",
  "userId" : "...",
  "lastFm" : "...",
  "mySpace" : "...",
  "fullname" : "...",
  "about" : "...",
  "url" : "..."
}

Element venue

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.

Example XML

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

Example JSON

{
  "id" : "...",
  "name" : "...",
  "city" : {
    "id" : "...",
    "name" : "...",
    "state" : "...",
    "stateCode" : "...",
    "coords" : {
      "long" : ...,
      "lat" : ...
    },
    "country" : {
      "name" : "...",
      "code" : "..."
    }
  },
  "url" : "..."
}

Element venues

Type: venues

A Result consisting of a list of venues.

Example XML

<?xml version="1.0" encoding="UTF-8"?>
<venues>
  <venue id="..." name="...">
    <!--content of type 'venue'-->
    <city id="..." name="..." state="..." stateCode="...">
      <!--content of type 'city'-->
      <coords long="..." lat="...">
        <!--content of type 'coords'-->
      </coords>
      <country name="..." code="...">
        <!--content of type 'country'-->
      </country>
    </city>
    <url>
      <!--content of type 'string'-->
      ...
    </url>
  </venue>
  <venue>
    <!--(another 'venue' type)-->
  </venue>
  <!--...more "venue" elements...-->
</venues>

Example JSON

{
  "venue" : [ {
    "id" : "...",
    "name" : "...",
    "city" : {
      "id" : "...",
      "name" : "...",
      "state" : "...",
      "stateCode" : "...",
      "coords" : {
        "long" : ...,
        "lat" : ...
      },
      "country" : {
        "name" : "...",
        "code" : "..."
      }
    },
    "url" : "..."
  }, ... ]
}

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"
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

Extends: result

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

Extends: result

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

Extends: result

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
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"
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)
set (set)	0/unbounded	(no documentation provided)
info (string)	0/1	(no documentation provided)
url (string)	0/1	(no documentation provided)

Type setlists

Extends: result

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"

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

Extends: result

A Result consisting of a list of venues.

Child Elements

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

setlist.fm API

Data

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Example XML

Example JSON

Attributes

Child Elements

Child Elements

Child Elements

Attributes

Child Elements

Attributes

Child Elements

Attributes

Attributes

Attributes

Child Elements

Attributes

Child Elements

Child Elements

Attributes

Child Elements

Attributes

Child Elements

Attributes

Child Elements

Child Elements

Home

REST Endpoints

XML Data Elements

XML Data Types