Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Python asked Songkick to the dance. Songkick said yes!

branch: master

Merge pull request #4 from mdgweb/master

Fixes incorrect "events" key in gigography API call
latest commit b5557966e2
Matt Dennewitz authored January 19, 2013
Octocat-spinner-32 docs added docs November 26, 2010
Octocat-spinner-32 songkick Bugfix when using MBZ ID January 19, 2013
Octocat-spinner-32 .gitignore initial import November 26, 2010
Octocat-spinner-32 AUTHORS initial import November 26, 2010
Octocat-spinner-32 README.rst Added ordering in the example January 19, 2013
Octocat-spinner-32 requirements.txt initial import November 26, 2010
Octocat-spinner-32 setup.py Decoupled the version string detection in setup.py from import to pre… June 16, 2012
README.rst

python-songkick

Wrapping Songkick's API since 2010.

More documentation forthcoming, but check out the example to get started.

Getting an API key

Visit http://www.songkick.com/api_key_requests/new to request an API key.

Usage

Using this wrapper is fairly straight-forward. Right now, events, gigographies and setlists are supported.

Getting a connection

songkick = Songkick(api_key=[YOUR API KEY])

Querying for events

Songkick.events provides access to Songkick's event search.

Event querying supports the following parameters:

  • artist_name
  • artist_id, the Songkick-given artist id
  • musicbrainz_id, a MusicBrainz id. If musicbrainz_id is given, no other artist-related query parameters are respected.
  • venue_id, the Songkick-given venue id. There is not currently a way to programmatically search for venues.
  • min_date, the earliest possible event date. Given as date.
  • max_date, the latest possible event date. Given as date.

Pagination is handled with the following parameters:

  • per_page, the number of objects per page. 50 max.
  • page, the page number you'd like.

See TODO for pagination plans.

# query for 10 coltrane motion events, no earlier than 1/1/2009
events = songkick.events.query(artist_name='coltrane motion',
                               per_page=10,
                               min_date=date(2009, 1, 1))

# iterate over the list of events
for event in events:
    print event.display_name        # Coltrane Motion at Arlene's Grocery (June 2, 2010)
    print event.location.city       # New York, NY, US
    print event.venue.display_name  # Arlene's Grocery

Querying for gigographies

Songkick.gigography provides access to Songkick's gigography search.

Gigography querying supports the following parameters:

  • artist_id, the Songkick-given artist id
  • musicbrainz_id, a MusicBrainz id. If musicbrainz_id is given, no other artist-related query parameters are respected.
  • order, the result ordering type, desc or asc (default value).

Pagination is handled with the following parameters:

  • per_page, the number of objects per page. 50 max.
  • page, the page number you'd like.

See TODO for pagination plans.

# query for latest Dropkick Musphys events
events = songkick.gigography.query(artist_id='211206', order='desc')

# iterate over the list of events
for event in events:
    print event.display_name
        print event.location.city
        print event.venue.display_name

Querying for setlists

Songkick.setlists provides access to Songkick's setlist catalog.

Right now, Songkick's setlist API only allows querying for setlists by event id.

# pull the setlist for event 786417, wilco @ the troxy
setlist = songkick.setlists.get(id=786417)

# check out whats inside
print setlist.display_name # Wilco at Troxy (25 Aug 09)

for song in setlist.setlist_items:
    print song.title # Wilco (The Song)

Note

Songkick's API documentation is fairly out of date. I've provided a few response examples in the data dir.

Requirements

  • python 2.6+
  • httplib2
  • sphinx (optional, to build docs)
  • python-dateutil

All covered in requirements.txt.

TODO

  • Support event location search
  • Pagination feels incomplete, so I'd like to add an optional cursor to allow transparent page fetching.
Something went wrong with that request. Please try again.