API Reference

A simple Python wrapper for the setlist.fm API

class setlipy.client.Setlipy(file_format: str = 'json', auth: Optional[str] = None)

Bases: object

Example usage:

from setlipy import client

sfm = client.Setlipy(auth=”YOUR_API_KEY”)

results = sfm.setlists(artist_name=”The Rolling Stones”, year=”2022”)

json_dump = (results.json())

for idx, setlists in enumerate(json_dump[“setlist”]):

print(idx, setlists)

__init__(file_format: str = 'json', auth: Optional[str] = None)

Creates a Setlipy client.

Parameters

  • file_format – defines the data interchange format

  • auth – Setlist.fm authentication id

artist_for_musicbrainz_id(mbid: str)

Returns an artist for a given Musicbrainz MBID

Parameters

mbid – a Musicbrainz MBID, e.g. 0bfba3d3-6a04-4779-bb0a-df07df5b0558

artist_setlists_for_musicbrainz_id(mbid: str, result_page_num: int = 1)

Get a list of an artist’s setlists.

Parameters

  • mbid – the Musicbrainz MBID of the artist

  • result_page_num – the number of the result page

artists(artist_mbid: str = '', artist_name: str = '', artist_tmid: Optional[int] = None, result_page_num: int = 1, sort_by: str = 'sortName')

Search for artists.

Parameters

  • artist_mbid – the artist’s Musicbrainz Identifier (mbid)

  • artist_name – the artist’s name

  • artist_tmid – the artist’s Ticketmaster Identifier (tmid)

  • result_page_num – the number of the result page you’d like to have

  • sort_by – the sort of the result, either sortName (default) or relevance

cities(country: str = '', name: str = '', result_page_num: int = 1, state: str = '', state_code: str = '')

Search for a city.

Parameters

  • country – the city’s country

  • name – name of the city

  • result_page_num – the number of the result page you’d like to have

  • state – state the city lies in

  • state_code – state code the city lies in

city(geo_id: str)

Get a city by its unique geoId.

Parameters

geo_id – the city’s geo id.

countries()

Get a complete list of all supported countries.

set_auth(auth: str)

Define the authentication id from Setlist.fm :param auth: Setlist.fm authentication id

setlist_by_id(setlist_id: str)

Returns the current version of a setlist. E.g. if you pass the id of a setlist that got edited since you last accessed it, you’ll get the current version.

Parameters

setlist_id – Setlist id.

setlist_version(version_id: str)

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.

Parameters

version_id – Setlist version Id.

setlists(artist_mbid: str = '', artist_name: str = '', artist_tmid: Optional[int] = None, city_id: str = '', city_name: str = '', country_code: str = '', date_of_event: str = '', last_fm: Optional[int] = None, last_updated: str = '', result_page_num: int = 1, state: str = '', state_code: str = '', tour_name: str = '', venue_id: str = '', venue_name: str = '', year: str = '')

Search for setlists.

Parameters

  • artist_mbid – the artist’s Musicbrainz Identifier (mbid)

  • artist_name – the artist’s name

  • artist_tmid – the artist’s Ticketmaster Identifier (tmid)

  • city_id – the city’s geoId

  • city_name – the name of the city

  • country_code – the country code

  • date_of_event – the date of the event (format dd-MM-yyyy)

  • last_fm – the event’s Last.fm Event ID (deprecated)

  • last_updated – the date and time (UTC) when this setlist was last updated (format yyyyMMddHHmmss) - either

  • date (edited or reverted. search will return setlists that were updated on or after this) –

  • result_page_num – the number of the result page

  • state – the state

  • state_code – the state code

  • tour_name –

  • venue_id – the venue id

  • venue_name – the name of the venue

  • year – the year of the event

setlists_for_venue(venue_id: str, result_page_num: int = 1)

Get setlists for a specific venue.

Parameters

  • venue_id – the id of the venue

  • result_page_num – the number of the result page.

user(user_id: str)

Get a user by userId. (deprecated) Note: This endpoint always returns a result, even if the user doesn’t exist

Parameters

user_id – the user’s userId

user_attended(user_id: str, result_page_num: int = 1)

Get a list of setlists of concerts attended by a user.

Parameters

  • user_id – the user’s userId.

  • result_page_num – the number of the result page.

user_edited(user_id: str, result_page_num: int = 1)

Get a list of setlists of concerts edited by a user. The list contains the current version, not the version edited.

Parameters

  • user_id – the user’s userId.

  • result_page_num – the number of the result page.

venue(venue_id: str)

Get a venue by its unique id.

Parameters

venue_id – the id of the venue

venues(city_id: str = '', city_name: str = '', country: str = '', name: str = '', result_page_num: int = 1, state: str = '', state_code: str = '')

Search for venues.

Parameters

  • city_id – the city’s geoId

  • city_name – name of the city where the venue is located

  • country – the city’s country

  • name – name of the venue

  • result_page_num – the number of the result page you’d like to have

  • state – the city’s state

  • state_code – the city’s state code

setlipy.string_encoding.check_for_special_chars(quote: str, encoding: str = 'utf-8') → str

Checks if a string contains a special character and converts it.

Parameters

  • quote – the text to check for a special character.

  • encoding – the encoding to be used.

Returns: encoded text