The cl-lastfm Reference Manual

Table of Contents

The cl-lastfm Reference Manual

This is the cl-lastfm Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 09:47:51 2021 GMT+0.

1 Introduction

cl-lastfm

A Common Lisp wrapper around Last.fm 2.0 web service.

Intallation

Add the projet and load it using Quicklisp:

CL-USER> (push #p"/projects/cl-lastfm/" asdf:*central-registry*)
CL-USER> (ql:quickload "cl-lastfm")

Hacking

Fork, hack and run unit tests:

CL-USER> (setq lisp-unit:*print-failures* t)
CL-USER> (setq lisp-unit:*print-errors* t)
CL-USER> (setq lisp-unit:*print-summary* t)
CL-USER> (setf cl-lastfm-test::*api-key* "xxxx")
CL-USER> (lisp-unit:run-tests :all :cl-lastfm-test)

Usage

Get a LastFM API Key and make some requests:

CL-USER> (setq *api-key* "xxxxx")
CL-USER> (cl-lastfm:artist-get-info *api-key* :artist-name "U2")

API

The Last.fm Web Services API is described here :

http://www.lastfm.fr/api

cl-lastfm implements theses features :

Album

[ ] album.addTags
[x] album.getInfo
[ ] album.getTags
[ ] album.removeTag
[x] album.search

Artist

[ ] artist.addTags
[x] artist.getEvents
[x] artist.getInfo
[x] artist.getSimilar
[ ] artist.getTags
[x] artist.getTopAlbums
[x] artist.getTopFans
[x] artist.getTopTags
[x] artist.getTopTracks
[ ] artist.removeTag
[x] artist.search
[ ] artist.share

Auth

[ ] auth.getMobileSession
[ ] auth.getSession
[ ] auth.getToken
[ ] auth.getWebSession

Event

[ ] event.attend
[x] event.getInfo
[ ] event.getShouts
[ ] event.share

Geo

[x] geo.getEvents
[x] geo.getTopArtists
[x] geo.getTopTracks

Group

[x] group.getmembers
[x] group.getWeeklyAlbumChart
[x] group.getWeeklyArtistChart
[x] group.getWeeklyChartList
[x] group.getWeeklyTrackChart

Library

[ ] library.addAlbum
[ ] library.addArtist
[ ] library.addTrack
[x] library.getAlbums
[x] library.getArtists
[x] library.getTracks

Playlist

[ ] playlist.addTrack
[ ] playlist.create
[ ] playlist.fetch

Tag

[x] tag.getSimilar
[x] tag.getTopAlbums
[x] tag.getTopArtists
[x] tag.getTopTags
[x] tag.getTopTracks
[x] tag.getWeeklyArtistChart
[x] tag.getWeeklyChartList
[x] tag.search

Tasteometer

[x] tasteometer.compare

Track

[ ] track.addTags
[ ] track.ban
[x] track.getInfo
[x] track.getSimilar
[x] track.getTags
[x] track.getTopFans
[x] track.getTopTags
[ ] track.love
[ ] track.removeTag
[x] track.search
[ ] track.share

User

[x] user.getEvents
[x] user.getFriends
[ ] user.getInfo
[x] user.getLovedTracks
[x] user.getNeighbours
[ ] user.getPastEvents
[ ] user.getPlaylists
[x] user.getRecentTracks
[ ] user.getRecommendedEvents
[x] user.getShouts
[x] user.getTopAlbums
[x] user.getTopArtists
[x] user.getTopTags
[x] user.getTopTracks
[x] user.getWeeklyAlbumChart
[x] user.getWeeklyArtistChart
[x] user.getWeeklyChartList
[x] user.getWeeklyTrackChart

Changelog

A changelog is available here.

Contact

Nicolas Lamirault nicolas.lamirault@gmail.com

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-lastfm

Maintainer

Nicolas Lamirault <nicolas.lamirault@gmail.com>

Author

Nicolas Lamirault <nicolas.lamirault@gmail.com>

License

MIT License

Description

Common Lisp wrapper for the Last.fm web service.

Version

0.1

Dependencies

• drakma
• cxml-stp
• url-rewrite
• trivial-utf-8

Source

cl-lastfm.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 cl-lastfm/src

Parent

cl-lastfm (system)

Location

src/

Components

• package.lisp (file)
• conditions.lisp (file)
• specials.lisp (file)
• tools.lisp (file)
• lastfm.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 cl-lastfm.asd

Location

cl-lastfm.asd

Systems

cl-lastfm (system)

4.1.2 cl-lastfm/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

cl-lastfm

4.1.3 cl-lastfm/src/conditions.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/conditions.lisp

Exported Definitions

• error-message-of (method)
• lastfm-error (condition)
• lastfm-protocol-error (condition)
• lastfm-request-error (condition)
• request-error-code-of (method)

4.1.4 cl-lastfm/src/specials.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/specials.lisp

Exported Definitions

*debug* (special variable)

Internal Definitions

• *api-key* (special variable)
• *api-secret-key* (special variable)
• +album-get-info+ (constant)
• +album-search+ (constant)
• +artist-get-events+ (constant)
• +artist-get-info+ (constant)
• +artist-get-similar+ (constant)
• +artist-get-top-albums+ (constant)
• +artist-get-top-fans+ (constant)
• +artist-get-top-tags+ (constant)
• +artist-get-top-tracks+ (constant)
• +artist-search+ (constant)
• +event-get-info+ (constant)
• +event-get-shouts+ (constant)
• +geo-get-events+ (constant)
• +geo-top-artists+ (constant)
• +geo-top-tracks+ (constant)
• +group-get-members+ (constant)
• +group-get-weekly-album-chart+ (constant)
• +group-get-weekly-artist-chart+ (constant)
• +group-get-weekly-chart-list+ (constant)
• +group-get-weekly-track-chart+ (constant)
• +last-fm-ws+ (constant)
• +library-get-albums+ (constant)
• +library-get-artists+ (constant)
• +library-get-tracks+ (constant)
• +tag-get-similar+ (constant)
• +tag-get-top-albums+ (constant)
• +tag-get-top-artists+ (constant)
• +tag-get-top-tags+ (constant)
• +tag-get-top-tracks+ (constant)
• +tag-get-weekly-artist-chart+ (constant)
• +tag-get-weekly-chart-list+ (constant)
• +tag-search+ (constant)
• +tasteometer-compare+ (constant)
• +track-get-info+ (constant)
• +track-get-similar+ (constant)
• +track-get-top-fans+ (constant)
• +track-get-top-tags+ (constant)
• +track-search+ (constant)
• +user-get-events (constant)
• +user-get-friends+ (constant)
• +user-get-loved-tracks+ (constant)
• +user-get-neighbours+ (constant)
• +user-get-recent-tracks+ (constant)
• +user-get-shouts+ (constant)
• +user-get-top-albums+ (constant)
• +user-get-top-artists+ (constant)
• +user-get-top-tags+ (constant)
• +user-get-top-tracks+ (constant)
• +user-get-weekly-album-chart+ (constant)
• +user-get-weekly-artist-chart+ (constant)
• +user-get-weekly-chart-list+ (constant)
• +user-get-weekly-track-chart+ (constant)
• def-lastfm-uri (macro)

4.1.5 cl-lastfm/src/tools.lisp

Dependencies

• specials.lisp (file)
• conditions.lisp (file)

Parent

src (module)

Location

src/tools.lisp

Internal Definitions

• extract-lastfm-xml-error (function)
• get-current-date (function)
• get-date-formated (function)
• get-timestamp (function)
• perform-lastfm-query (function)
• unix-timestamp (function)
• url-encode-utf8 (function)

4.1.6 cl-lastfm/src/lastfm.lisp

Dependency

tools.lisp (file)

Parent

src (module)

Location

src/lastfm.lisp

Exported Definitions

• album-get-info (function)
• album-search (function)
• artist-get-events (function)
• artist-get-info (function)
• artist-get-similar (function)
• artist-get-top-albums (function)
• artist-get-top-fans (function)
• artist-get-top-tags (function)
• artist-get-top-tracks (function)
• artist-search (function)
• event-get-info (function)
• event-get-shouts (function)
• geo-get-events (function)
• geo-top-artists (function)
• geo-top-tracks (function)
• group-get-members (function)
• group-get-weekly-album-chart (function)
• group-get-weekly-artist-chart (function)
• group-get-weekly-chart-list (function)
• group-get-weekly-track-chart (function)
• library-get-albums (function)
• library-get-artists (function)
• library-get-tracks (function)
• tag-get-similar (function)
• tag-get-top-albums (function)
• tag-get-top-artists (function)
• tag-get-top-tags (function)
• tag-get-top-tracks (function)
• tag-get-weekly-artist-chart (function)
• tag-get-weekly-chart-list (function)
• tag-search (function)
• tasteometer-compare (function)
• track-get-info (function)
• track-get-similar (function)
• track-get-top-fans (function)
• track-get-top-tags (function)
• track-search (function)
• user-get-events (function)
• user-get-friends (function)
• user-get-loved-tracks (function)
• user-get-neighbours (function)
• user-get-recent-tracks (function)
• user-get-shouts (function)
• user-get-top-albums (function)
• user-get-top-artists (function)
• user-get-top-tags (function)
• user-get-top-tracks (function)
• user-get-weekly-album-chart (function)
• user-get-weekly-artist-chart (function)
• user-get-weekly-chart-list (function)
• user-get-weekly-track-chart (function)

Internal Definitions

with-lastfm-stream (macro)

5 Packages

Packages are listed by definition order.

5.1 cl-lastfm

Common Lisp wrapper to Last.fm web service.
See more explanation from the @a[http://www.lastfm.fr/api]{website}. It has been tested under @a[http://www.sbcl.org]{SBCL}

@begin[Albums]{section}
@aboutfun{album-get-info}
@aboutfun{album-search}
@end{section}

@begin[Artists]{section}
@aboutfun{artist-get-events}
@aboutfun{artist-get-info}
@aboutfun{artist-get-similar}
@aboutfun{artist-get-top-albums}
@aboutfun{artist-get-top-fans}
@aboutfun{artist-get-top-tags}
@aboutfun{artist-get-top-tracks}
@aboutfun{artist-search}
@end{section}

@begin[Geo]{section}
@aboutfun{geo-get-events}
@aboutfun{geo-top-artists}
@aboutfun{geo-top-tracks}
@end{section}

@begin[User]{section}
@aboutfun{user-get-events}
@aboutfun{user-get-friends}
@aboutfun{user-get-loved-tracks}
@aboutfun{user-get-neighbours}
@aboutfun{user-get-top-albums}
@aboutfun{user-get-top-artists}
@aboutfun{user-get-top-tags}
@aboutfun{user-get-top-tracks}
@aboutfun{user-get-recent-tracks}
@aboutfun{user-get-shouts} @aboutfun{user-get-weekly-album-chart} @aboutfun{user-get-weekly-artist-chart} @aboutfun{user-get-weekly-chart-list} @aboutfun{user-get-weekly-track-chart}
@end{section}

@begin[Group]{section}
@aboutfun{group-get-members} @aboutfun{group-get-weekly-album-chart} @aboutfun{group-get-weekly-artist-chart} @aboutfun{group-get-weekly-chart-list} @aboutfun{group-get-weekly-track-chart}
@end{section}

@begin[Library]{section}
@aboutfun{library-get-albums}
@aboutfun{library-get-artists}
@aboutfun{library-get-tracks}
@end{section}

@begin[Tag]{section}
@aboutfun{tag-get-similar}
@aboutfun{tag-get-similar}
@aboutfun{tag-get-top-albums}
@aboutfun{tag-get-top-artists}
@aboutfun{tag-get-top-tracks}
@aboutfun{tag-get-top-tags} @aboutfun{tag-get-weekly-artist-chart} @aboutfun{tag-get-weekly-chart-list}
@aboutfun{tag-search}
@end{section}

@begin[Track]{section}
@aboutfun{track-get-info}
@aboutfun{track-get-similar}
@aboutfun{track-get-top-fans}
@aboutfun{track-get-top-tags}
@aboutfun{track-search}
@end{section}

@begin[Events]{section}
@aboutfun{event-get-info}
@aboutfun{event-get-shouts}
@end{section}

@begin[TasteOMeter]{section}
@aboutfun{tasteometer-compare}
@end{section}

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• *debug* (special variable)
• album-get-info (function)
• album-search (function)
• artist-get-events (function)
• artist-get-info (function)
• artist-get-similar (function)
• artist-get-top-albums (function)
• artist-get-top-fans (function)
• artist-get-top-tags (function)
• artist-get-top-tracks (function)
• artist-search (function)
• error-message-of (generic function)
• error-message-of (method)
• event-get-info (function)
• event-get-shouts (function)
• geo-get-events (function)
• geo-top-artists (function)
• geo-top-tracks (function)
• group-get-members (function)
• group-get-weekly-album-chart (function)
• group-get-weekly-artist-chart (function)
• group-get-weekly-chart-list (function)
• group-get-weekly-track-chart (function)
• lastfm-error (condition)
• lastfm-protocol-error (condition)
• lastfm-request-error (condition)
• library-get-albums (function)
• library-get-artists (function)
• library-get-tracks (function)
• request-error-code-of (generic function)
• request-error-code-of (method)
• tag-get-similar (function)
• tag-get-top-albums (function)
• tag-get-top-artists (function)
• tag-get-top-tags (function)
• tag-get-top-tracks (function)
• tag-get-weekly-artist-chart (function)
• tag-get-weekly-chart-list (function)
• tag-search (function)
• tasteometer-compare (function)
• track-get-info (function)
• track-get-similar (function)
• track-get-top-fans (function)
• track-get-top-tags (function)
• track-search (function)
• user-get-events (function)
• user-get-friends (function)
• user-get-loved-tracks (function)
• user-get-neighbours (function)
• user-get-recent-tracks (function)
• user-get-shouts (function)
• user-get-top-albums (function)
• user-get-top-artists (function)
• user-get-top-tags (function)
• user-get-top-tracks (function)
• user-get-weekly-album-chart (function)
• user-get-weekly-artist-chart (function)
• user-get-weekly-chart-list (function)
• user-get-weekly-track-chart (function)

Internal Definitions

• *api-key* (special variable)
• *api-secret-key* (special variable)
• +album-get-info+ (constant)
• +album-search+ (constant)
• +artist-get-events+ (constant)
• +artist-get-info+ (constant)
• +artist-get-similar+ (constant)
• +artist-get-top-albums+ (constant)
• +artist-get-top-fans+ (constant)
• +artist-get-top-tags+ (constant)
• +artist-get-top-tracks+ (constant)
• +artist-search+ (constant)
• +event-get-info+ (constant)
• +event-get-shouts+ (constant)
• +geo-get-events+ (constant)
• +geo-top-artists+ (constant)
• +geo-top-tracks+ (constant)
• +group-get-members+ (constant)
• +group-get-weekly-album-chart+ (constant)
• +group-get-weekly-artist-chart+ (constant)
• +group-get-weekly-chart-list+ (constant)
• +group-get-weekly-track-chart+ (constant)
• +last-fm-ws+ (constant)
• +library-get-albums+ (constant)
• +library-get-artists+ (constant)
• +library-get-tracks+ (constant)
• +tag-get-similar+ (constant)
• +tag-get-top-albums+ (constant)
• +tag-get-top-artists+ (constant)
• +tag-get-top-tags+ (constant)
• +tag-get-top-tracks+ (constant)
• +tag-get-weekly-artist-chart+ (constant)
• +tag-get-weekly-chart-list+ (constant)
• +tag-search+ (constant)
• +tasteometer-compare+ (constant)
• +track-get-info+ (constant)
• +track-get-similar+ (constant)
• +track-get-top-fans+ (constant)
• +track-get-top-tags+ (constant)
• +track-search+ (constant)
• +user-get-events (constant)
• +user-get-friends+ (constant)
• +user-get-loved-tracks+ (constant)
• +user-get-neighbours+ (constant)
• +user-get-recent-tracks+ (constant)
• +user-get-shouts+ (constant)
• +user-get-top-albums+ (constant)
• +user-get-top-artists+ (constant)
• +user-get-top-tags+ (constant)
• +user-get-top-tracks+ (constant)
• +user-get-weekly-album-chart+ (constant)
• +user-get-weekly-artist-chart+ (constant)
• +user-get-weekly-chart-list+ (constant)
• +user-get-weekly-track-chart+ (constant)
• def-lastfm-uri (macro)
• extract-lastfm-xml-error (function)
• get-current-date (function)
• get-date-formated (function)
• get-timestamp (function)
• perform-lastfm-query (function)
• unix-timestamp (function)
• url-encode-utf8 (function)
• with-lastfm-stream (macro)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *debug*

If T activate some logs.

Package

cl-lastfm

Source

specials.lisp (file)

6.1.2 Functions

Function: album-get-info API-KEY &key ARTIST-NAME ALBUM-NAME MBID LANG

@short{Get the metadata for an album on Last.fm using the album name or a musicbrainz id. See @fun{playlist-fetch} on how to get the album playlist. This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question}
@arg[album-name]{The album name in question}
@arg[mbid]{The musicbrainz id for the album}
@arg[lang]{The language to return the biography in, expressed as an ISO 639 alpha-2 code}
@see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: album-search API-KEY ALBUM-NAME &key LIMIT PAGE

@short{Search for an album by name. Returns album matches sorted by relevance. This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[album-name]{The album name in question}
@arg[limit]{Limit the number of albums returned at one time. Default (maximum) is 30}
@arg[page]{Scan into the results by specifying a page number. Defaults to first page}
@see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-get-events API-KEY ARTIST-NAME

@short{Get a list of upcoming events for this artist. Easily integratable into calendars, using the ical standard.
This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-get-info API-KEY &key ARTIST-NAME MBID LANG

@short{Get the metadata for an artist on Last.fm. Includes biography. . This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question}
@arg[mbid]{The musicbrainz id for the artist}
@arg[lang]{The language to return the biography in, expressed as an ISO 639 alpha-2 code}
@see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-get-similar API-KEY ARTIST-NAME &optional LIMIT

@short{Get all the artists similar to this artist. This service does not require authentication.} @arg[api-key]{A Last.fm API key} @arg[artist-name]{The artist name in question} @arg[limit]{Limit the number of similar artists returned} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-get-top-albums API-KEY ARTIST-NAME

@short{Get the top albums for an artist on Last.fm, ordered by popularity. This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-get-top-fans API-KEY ARTIST-NAME

@short{Get the top fans for an artist on Last.fm, based on listening data. This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-get-top-tags API-KEY ARTIST-NAME

@short{Get the top tags for an artist on Last.fm, ordered by popularity. This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-get-top-tracks API-KEY ARTIST-NAME

@short{Get the top tracks by an artist on Last.fm, ordered by popularity This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: artist-search API-KEY ARTIST-NAME &key LIMIT PAGE

@short{Search for an artist by name. Returns artist matches sorted by relevance.
This service does not require authentication.}
@arg[api-key]{A Last.fm API key}
@arg[artist-name]{The artist name in question}
@arg[limit]{Limit the number of artists returned at one time. Default (maximum) is 30}
@arg[page]{Scan into the results by specifying a page number. Defaults to first page}
@see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: event-get-info API-KEY EVENTID

@short{Get the metadata for an event on Last.fm. Includes attendance and lineup information}
@arg[api_key]{A Last.fm API key}
@arg[eventid]{The numeric Last.fm event id} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: event-get-shouts API-KEY EVENTID

@short{Get shouts for this event} @arg[api_key]{A Last.fm API key} @arg[eventid]{The numeric Last.fm event id} @see-condition{lastfm-request-error} @return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: geo-get-events API-KEY &key LOCATION LAT LONG PAGE DISTANCE

@short{Get all events in a specific location by country or city name.
This service does not require authentication}
@arg[api_key]{A Last.fm API key}
@arg[location]{Specifies a location to retrieve events for (service returns nearby events by default}
@arg[lat]{Specifies a latitude value to retrieve events for (service returns nearby events by default}
@arg[long]{Specifies a longitude value to retrieve events for (service returns nearby events by default)}
@arg[page]{Display more results by pagination}
@arg[distance]{Find events within a specified distance} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: geo-top-artists API-KEY COUNTRY-NAME

@short{Get the most popular artists on Last.fm by country.
This service does not require authentication}
@arg[api_key]{A Last.fm API key}
@arg[country-name]{A country name, as defined by the ISO 3166-1 country names standard}
@see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: geo-top-tracks API-KEY COUNTRY-NAME &optional LOCATION

@short{Get the most popular tracks on Last.fm by country .
This service does not require authentication}
@arg[api_key]{A Last.fm API key}
@arg[country-name]{A country name, as defined by the ISO 3166-1 country names standard}
@arg[location]{A metro name, to fetch the charts for (must be within the country specified)}
@see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: group-get-members API-KEY GROUP

@short{Get a list of members for this group. This service does not require authentication} @arg[api_key]{A Last.fm API key} @arg[group]{The group name to fetch the members of} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: group-get-weekly-album-chart API-KEY GROUP &key FROM TO

@short{Get an album chart for a group, for a given date range. If no date range is supplied, it will return the most recent album chart for this group.} @arg[api_key]{A Last.fm API key}
@arg[group]{The last.fm group name to fetch the charts of}
@arg[from]{The date at which the chart should start from}
@arg[to]{The date at which the chart should end on} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: group-get-weekly-artist-chart API-KEY GROUP &key FROM TO

@short{Get an artist chart for a group, for a given date range. If no date range is supplied, it will return the most recent album chart for this group} @arg[api_key]{A Last.fm API key}
@arg[group]{The last.fm group name to fetch the charts of}
@arg[from]{The date at which the chart should start from}
@arg[to]{The date at which the chart should end on} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: group-get-weekly-chart-list API-KEY GROUP

@short{Get a list of available charts for this group, expressed as date ranges which can be sent to the chart services}
@arg[api_key]{A Last.fm API key}
@arg[group]{The last.fm group name to fetch the charts list for} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: group-get-weekly-track-chart API-KEY GROUP &key FROM TO

@short{Get a track chart for a group, for a given date range. If no date range is supplied, it will return the most recent album chart for this group} @arg[api_key]{A Last.fm API key}
@arg[group]{The last.fm group name to fetch the charts of}
@arg[from]{The date at which the chart should start from}
@arg[to]{The date at which the chart should end on} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: library-get-albums API-KEY USER &key PAGE LIMIT

@short{A paginated list of all the albums in a user’s library, with play counts and tag counts}
@arg[api_key]{A Last.fm API key}
@arg[user]{The user whose library you want to fetch} @arg[limit]{Limit the amount of albums returned}
@arg[page]{The page number you wish to scan to} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: library-get-artists API-KEY USER &key PAGE LIMIT

@short{A paginated list of all the artists in a user’s library, with play counts and tag counts}
@arg[api_key]{A Last.fm API key}
@arg[user]{The user whose library you want to fetch}
@arg[limit]{Limit the amount of artists returned}
@arg[page]{The page number you wish to scan to} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: library-get-tracks API-KEY USER &key PAGE LIMIT

@short{A paginated list of all the tracks in a user’s library, with play counts and tag counts. }
@arg[api_key]{A Last.fm API key}
@arg[user]{The user whose library you want to fetch} @arg[limit]{Limit the amount of tracks returned}
@arg[page]{The page number you wish to scan to} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-get-similar API-KEY TAG

@short{Search for tags similar to this one. Returns tags ranked by similarity, based on listening data}
@arg[api_key]{A Last.fm API key}
@arg[tag]{The tag name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-get-top-albums API-KEY TAG

@short{Get the top albums tagged by this tag, ordered by tag count} @arg[api_key]{A Last.fm API key}
@arg[tag]{The tag name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-get-top-artists API-KEY TAG

@short{Get the top artists tagged by this tag, ordered by tag count} @arg[api_key]{A Last.fm API key}
@arg[tag]{The tag name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-get-top-tags API-KEY

@short{Fetches the top global tags on Last.fm, sorted by popularity (number of times used).}
@arg[api_key]{A Last.fm API key} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-get-top-tracks API-KEY TAG

@short{Get the top tracks tagged by this tag, ordered by tag count} @arg[api_key]{A Last.fm API key}
@arg[tag]{The tag name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-get-weekly-artist-chart API-KEY TAG &key FROM TO LIMIT

@short{Get an artist chart for a tag, for a given date range.
If no date range is supplied, it will return the most recent artist chart for this tag}
@arg[api_key]{A Last.fm API key}
@arg[tag]{The tag name in question}
@arg[from]{The date at which the chart should start from}
@arg[to]{The date at which the chart should end on}
@arg[limit]{The number of chart items to return} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-get-weekly-chart-list API-KEY TAG

@short{Get a list of available charts for this tag, expressed as date ranges which can be sent to the chart services}
@arg[api_key]{A Last.fm API key}
@arg[tag]{The tag name in question} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tag-search API-KEY TAG &key PAGE LIMIT

@short{Search for a tag by name. Returns matches sorted by relevance} @arg[api_key]{A Last.fm API key}
@arg[tag]{The tag name in question}
@arg[limit]{Limit the number of tags returned at one time} @arg[page]{Scan into the results by specifying a page number} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: tasteometer-compare API-KEY FIRST-TYPE SECOND-TYPE FIRST-VALUE SECOND-VALUE &key LIMIT

@short{Get a Tasteometer score from two inputs, along with a list of shared artists. If the input is a User or a Myspace URL, some additional information is returned.}
@arg[api_key]{A Last.fm API key}
@arg[fisrt-type]{Must be user, artists or myspace}
@arg[second-type]{Must be user, artists or myspace}
@arg[first-value]{Must be : Last.fm username or comma-separated artist names or a MySpace profile URL}
@arg[second-value]{Must be : Last.fm username or comma-separated artist names or a MySpace profile URL}
@arg[limit]{How many shared artists to display} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: track-get-info API-KEY &key ARTIST TRACK MBID

@short{Get the metadata for a track on Last.fm using the artist/track name or a musicbrainz id}
@arg[api-key]{A Last.fm API key}
@arg[artist]{The artist name in question}
@arg[track]{The track name in question}
@arg[mbid]{The musicbrainz id for the track} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: track-get-similar API-KEY &key ARTIST TRACK MBID

@short{Get the similar tracks for this track on Last.fm, based on listening data}
@arg[api-key]{A Last.fm API key}
@arg[artist]{The artist name in question}
@arg[track]{The track name in question}
@arg[mbid]{The musicbrainz id for the track} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: track-get-top-fans API-KEY &key ARTIST TRACK MBID

@short{Get the top fans for this track on Last.fm, based on listening data. Supply either track & artist name or musicbrainz id}
@arg[api-key]{A Last.fm API key}
@arg[artist]{The artist name in question}
@arg[track]{The track name in question}
@arg[mbid]{The musicbrainz id for the track} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: track-get-top-tags API-KEY &key ARTIST TRACK MBID

@short{Get the top tags for this track on Last.fm, ordered by tag count. Supply either track & artist name or mbid}
@arg[api-key]{A Last.fm API key}
@arg[artist]{The artist name in question}
@arg[track]{The track name in question}
@arg[mbid]{The musicbrainz id for the track} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: track-search API-KEY TRACK &key ARTIST PAGE LIMIT

@short{Search for a track by track name. Returns track matches sorted by relevance}
@arg[api-key]{A Last.fm API key}
@arg[track]{The track name in question}
@arg[limit]{The number of tracks returned at one time} @arg[page]{Scan into the results by specifying a page number} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-events API-KEY USER

@short{Get a list of upcoming events that this user is attending. Easily integratable into calendars, using the ical standard. This service does not require authentication}
@arg[api_key]{A Last.fm API key}
@arg[user]{The user to fetch the events for} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-friends API-KEY USER &key LIMIT PAGE RECENTTRACKS

@short{Get a list of the user’s friends on Last.fm
This service does not require authentication}
@arg[api_key]{A Last.fm API key}
@arg[user]{The last.fm username to fetch the friends of}
@arg[limit]{An integer used to limit the number of friends returned} @arg[page]{An integer representing the page number to fetch. Defaults to first page} @arg[recenttracks]{Whether or not to include information about friends’ recent listening in the response}
@see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-loved-tracks API-KEY USER &key LIMIT PAGE

@short{Get the last 50 tracks loved by a user.
This service does not require authentication}
@arg[api_key]{A Last.fm API key}
@arg[user]{The user name to fetch the loved tracks for}
@arg[limit]{An integer representing the number of results to fetch per page. Defaults to 50} @arg[page]{An integer representing the page number to fetch. Defaults to first page} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-neighbours API-KEY USER &key LIMIT

@short{Get a list of a user’s neighbours on Last.fm
This service does not require authentication}
@arg[api_key]{A Last.fm API key}
@arg[user]{The last.fm username to fetch the neighbours of} @arg[limit]{An integer used to limit the number of neighbours returned} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-recent-tracks API-KEY USER &key LIMIT

@short{Get a list of the recent tracks listened to by this user. Indicates now playing track if the user is currently listening}
@arg[api_key]{A Last.fm API key}
@arg[user]{The user name to fetch the recent tracks of}
@arg[limit]{An integer used to limit the number of tracks returned} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-shouts API-KEY USER

@short{Get shouts for this user} @arg[api_key]{A Last.fm API key} @arg[user]{The user name to fetch shouts for} @see-condition{lastfm-request-error} @return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-top-albums API-KEY USER &key PERIOD LIMIT PAGE

@short{Get the top albums listened to by a user. You can stipulate a time period. Sends the overall chart by default}
@arg[api_key]{A Last.fm API key}
@arg[user]{The user name to fetch top albums for}
@arg[period]{overall | 3month | 6month | 12month - The time period over which to retrieve top albums for.}
@arg[limit]{The number of results to fetch per page. Defaults to 50} @arg[page]{The page number to fetch. Defaults to first page} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-top-artists API-KEY USER &key PERIOD LIMIT PAGE

@short{Get the top artists listened to by a user. You can stipulate a time period. Sends the overall chart by default.}
@arg[api_key]{A Last.fm API key}
@arg[user]{The user name to fetch top artists for}
@arg[period]{overall | 3month | 6month | 12month - The time period over which to retrieve top albums for.}
@arg[limit]{The number of results to fetch per page. Defaults to 50} @arg[page]{The page number to fetch. Defaults to first page} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-top-tags API-KEY USER &key LIMIT

@short{Get the top tags used by this user} @arg[api_key]{A Last.fm API key} @arg[user]{The user name} @arg[limit]{The number of tags returned} @see-condition{lastfm-request-error} @return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-top-tracks API-KEY USER &key PERIOD LIMIT PAGE

@short{Get the top tracks listened to by a user. You can stipulate a time period. Sends the overall chart by default. }
@arg[api_key]{A Last.fm API key}
@arg[user]{The user name to fetch top tracks for}
@arg[period]{overall | 3month | 6month | 12month - The time period over which to retrieve top tracks for.}
@arg[limit]{The number of results to fetch per page. Defaults to 50} @arg[page]{The page number to fetch. Defaults to first page} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-weekly-album-chart API-KEY USER &key FROM TO

@short{Get an album chart for a user profile, for a given date range.
If no date range is supplied, it will return the most recent album chart for this user.}
@arg[api_key]{A Last.fm API key}
@arg[user]{The last.fm username to fetch the charts of}
@arg[from]{The date at which the chart should start from}
@arg[to]{The date at which the chart should end on} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-weekly-artist-chart API-KEY USER &key FROM TO

@short{Get an artist chart for a user profile, for a given date range.
If no date range is supplied, it will return the most recent artist chart for this user.}
@arg[api_key]{A Last.fm API key}
@arg[user]{The last.fm username to fetch the charts of}
@arg[from]{The date at which the chart should start from}
@arg[to]{The date at which the chart should end on} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-weekly-chart-list API-KEY USER

@short{Get a list of available charts for this user, expressed as date ranges which can be sent to the chart services}
@arg[api_key]{A Last.fm API key}
@arg[user]{The last.fm username to fetch the charts list for} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

Function: user-get-weekly-track-chart API-KEY USER &key FROM TO

@short{Get a track chart for a user profile, for a given date range. If no date range is supplied, it will return the most recent track chart for this user}
@arg[api_key]{A Last.fm API key}
@arg[user]{The last.fm username to fetch the charts of} @arg[from]{The date at which the chart should start from} @arg[to]{The date at which the chart should end on} @see-condition{lastfm-request-error}
@return{An XML stream}

Package

cl-lastfm

Source

lastfm.lisp (file)

6.1.3 Generic functions

Generic Function: error-message-of CONDITION

Package

cl-lastfm

Methods

Method: error-message-of (CONDITION lastfm-error)

Source

conditions.lisp (file)

Generic Function: request-error-code-of CONDITION

Package

cl-lastfm

Methods

Method: request-error-code-of (CONDITION lastfm-request-error)

Source

conditions.lisp (file)

6.1.4 Conditions

Condition: lastfm-error ()

Main Lastfm error.

Package

cl-lastfm

Source

conditions.lisp (file)

Direct superclasses

simple-error (condition)

Direct subclasses

• lastfm-request-error (condition)
• lastfm-protocol-error (condition)

Direct methods

error-message-of (method)

Direct slots

Slot: message

Explanation message.

Initargs

:message

Readers

error-message-of (generic function)

Condition: lastfm-protocol-error ()

Lastfm protocol error.

Package

cl-lastfm

Source

conditions.lisp (file)

Direct superclasses

lastfm-error (condition)

Condition: lastfm-request-error ()

Condition raised when an invalide request to the
Lastfm web services is performed.
Available codes are :
@pre{
* 2 : Invalid service -This service does not exist
* 3 : Invalid Method - No method with that name in this package
* 4 : Authentication Failed - You do not have permissions to access the service * 5 : Invalid format - This service doesn’t exist in that format
* 6 : Invalid parameters - Your request is missing a required parameter
* 7 : Invalid resource specified
* 9 : Invalid session key - Please re-authenticate
* 10 : Invalid API key - You must be granted a valid key by last.fm
* 11 : Service Offline - This service is temporarily offline. Try again later.
* 12 : Subscribers Only - This service is only available to paid last.fm subscribers }

Package

cl-lastfm

Source

conditions.lisp (file)

Direct superclasses

lastfm-error (condition)

Direct methods

request-error-code-of (method)

Direct slots

Slot: code

The error code.

Initargs

:code

Readers

request-error-code-of (generic function)

6.2 Internal definitions

6.2.1 Constants

Constant: +album-get-info+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +album-search+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-get-events+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-get-info+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-get-similar+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-get-top-albums+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-get-top-fans+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-get-top-tags+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-get-top-tracks+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +artist-search+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +event-get-info+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +event-get-shouts+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +geo-get-events+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +geo-top-artists+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +geo-top-tracks+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +group-get-members+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +group-get-weekly-album-chart+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +group-get-weekly-artist-chart+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +group-get-weekly-chart-list+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +group-get-weekly-track-chart+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +last-fm-ws+

The LastFM web service.

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +library-get-albums+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +library-get-artists+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +library-get-tracks+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-get-similar+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-get-top-albums+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-get-top-artists+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-get-top-tags+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-get-top-tracks+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-get-weekly-artist-chart+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-get-weekly-chart-list+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tag-search+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +tasteometer-compare+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +track-get-info+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +track-get-similar+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +track-get-top-fans+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +track-get-top-tags+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +track-search+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-events

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-friends+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-loved-tracks+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-neighbours+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-recent-tracks+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-shouts+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-top-albums+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-top-artists+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-top-tags+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-top-tracks+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-weekly-album-chart+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-weekly-artist-chart+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-weekly-chart-list+

Package

cl-lastfm

Source

specials.lisp (file)

Constant: +user-get-weekly-track-chart+

Package

cl-lastfm

Source

specials.lisp (file)

6.2.2 Special variables

Special Variable: *api-key*

Package

cl-lastfm

Source

specials.lisp (file)

Special Variable: *api-secret-key*

Package

cl-lastfm

Source

specials.lisp (file)

6.2.3 Macros

Macro: def-lastfm-uri NAME URI

Package

cl-lastfm

Source

specials.lisp (file)

Macro: with-lastfm-stream STREAM &body BODY

Macro which creates an HTTP url, add parameters executing body, and performs the HTTP request defined by uri.

Package

cl-lastfm

Source

lastfm.lisp (file)

6.2.4 Functions

Function: extract-lastfm-xml-error XML

Extract a LastFM error from a ‘XML’ message. Returns an error code and an error message.

Package

cl-lastfm

Source

tools.lisp (file)

Function: get-current-date ()

Get current date in YYYY-MM-DD hh:mm:ss format.

Package

cl-lastfm

Source

tools.lisp (file)

Function: get-date-formated CONTROL-STRING

Get current date in CONTROL-STRING format.

Package

cl-lastfm

Source

tools.lisp (file)

Function: get-timestamp ()

Get current date in YYYYMMDDHHMMSS format.

Package

cl-lastfm

Source

tools.lisp (file)

Function: perform-lastfm-query QUERY &key PARAMETERS METHOD

Retreive informations from LastFM Web Service.
‘QUERY’ is the HTTP request.
‘PARAMETERS’ is a list of assoc list which specify HTTP parameters. ‘METHOD’ is the HTTP method used to perform the HTTP call.

Package

cl-lastfm

Source

tools.lisp (file)

Function: unix-timestamp ()

Get the Unix timestamp : seconds since Jan 01 1970.

Package

cl-lastfm

Source

tools.lisp (file)

Function: url-encode-utf8 SEQUENCE

URL encode in UTF-8 the sequence.

Package

cl-lastfm

Source

tools.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types