setlist.fm /1.0/artist/{mbid}/setlists API

openapi: 3.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 &quot;de&quot; as header, you''ll

    get <em>&quot;Wien, &Ouml;sterreich&quot;</em> instead of <em>&quot;Vienna, Austria&quot;</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>&quot;Nueva York, Estados Unidos&quot;</em> instead of <em>&quot;New

    York, United States&quot;</em> if you pass &quot;es&quot; 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 /1.0/artist/{mbid}/setlists API
servers:
- url: /rest
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
      parameters:
      - name: mbid
        in: path
        required: true
        description: the Musicbrainz MBID of the artist
        schema:
          type: string
      - name: p
        in: query
        description: the number of the result page
        schema:
          type: integer
          default: '1'
      responses:
        '200':
          headers: {}
          description: Success
          content:
            application/xml:
              schema:
                description: ''
                $ref: '#/components/schemas/json_Setlists'
            application/json:
              schema:
                description: ''
                $ref: '#/components/schemas/json_Setlists'
              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
components:
  schemas:
    json_Setlist:
      type: object
      title: setlist
      properties:
        artist:
          description: the setlist's artist
          $ref: '#/components/schemas/json_Artist'
        venue:
          description: the setlist's venue
          $ref: '#/components/schemas/json_Venue'
        tour:
          description: the setlist's tour
          $ref: '#/components/schemas/json_Tour'
        set:
          description: all sets of this setlist
          type: array
          items:
            $ref: '#/components/schemas/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 &quot;dd-MM-yyyy&quot;
          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

            &quot;yyyy-MM-dd''T''HH:mm:ss.SSSZZZZZ&quot;'
          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_Setlists:
      type: object
      title: setlists
      properties:
        setlist:
          description: result list of setlists
          type: array
          items:
            $ref: '#/components/schemas/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_Set:
      type: object
      title: set
      properties:
        name:
          description: 'the description/name of the set. E.g. <em>&quot;Acoustic set&quot;</em> or <em>&quot;Paul McCartney

            solo&quot;</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: '#/components/schemas/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_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>&quot;Wish You Were Here&quot;</em>
          type: string
        with:
          description: A different Artist than the performing one that joined the stage for this song.
          $ref: '#/components/schemas/json_Artist'
        cover:
          description: The original Artist of this song, if different to the performing artist.
          $ref: '#/components/schemas/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_Venue:
      type: object
      title: venue
      properties:
        city:
          description: the city in which the venue is located
          $ref: '#/components/schemas/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>&quot;Madison Square Garden&quot;</em> or

            <em>&quot;Royal Albert Hall&quot;</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_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>&quot;M&uuml;chen&quot;</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>&quot;CA&quot;</em> or <em>&quot;02&quot;</em>


            which in turn get uniquely identifiable when combined with the state''s country:


            <em>&quot;US.CA&quot;</em> for California, United States or <em>&quot;DE.02&quot;</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>&quot;Bavaria&quot;</em> or <em>&quot;Florida&quot;</em>
          type: string
        coords:
          description: The city's coordinates. Usually the coordinates of the city centre are used.
          $ref: '#/components/schemas/json_Coords'
        country:
          description: The city's country.
          $ref: '#/components/schemas/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_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>&quot;ie&quot;</em> for Ireland'
          type: string
        name:
          example: United States
          description: 'The country''s name. Can be a localized name - e.g. <em>&quot;Austria&quot;</em> or

            <em>&quot;&Ouml;sterreich&quot;</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_Artist:
      type: object
      title: artist
      properties:
        mbid:
          example: b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d
          description: unique Musicbrainz Identifier (MBID), e.g. <em>&quot;b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d&quot;</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>&quot;The Beatles&quot;</em>
          type: string
        sortName:
          example: Beatles, The
          description: the artist's sort name, e.g. <em>&quot;Beatles, The&quot;</em> or <em>&quot;Springsteen, Bruce&quot;</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_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.