golastfmclient

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2026 License: MIT Imports: 13 Imported by: 0

README

go-lastfm-client

Go Version License Go Report Card Go Reference CI

A professional, feature-rich, and idiomatic Go client for the Last.fm API.

Built with scalability and resilience in mind, this library handles the complexities of the Last.fm API—like its polymorphic JSON responses—so you can focus on building your application.

✨ Features

  • Full Service Coverage: Implementation for Album, Artist, Track, User, Tag, Geo, Chart, and Library services.
  • Polymorphic JSON Resilience: Automatically handles Last.fm's "object or array" response inconsistency using custom unmarshaling logic.
  • Context Support: Every API call supports context.Context for proper timeout and cancellation management.
  • Authentication: Easy-to-use support for both Desktop (Token-based) and Mobile (Credentials-based) authentication flows.
  • Functional Options: Clean client initialization using the functional options pattern.
  • Request Signing: Automatic generation of api_sig for all authenticated methods.
  • Modern Go: Leverages Go 1.26.3 features and follows standard project layout conventions.

🚀 Installation

go get github.com/mrcl29/go-lastfm-client

🛠️ Quick Start

1. Unauthenticated Metadata Retrieval
package main

import (
    "context"
    "fmt"
    "github.com/mrcl29/go-lastfm-client"
)

func main() {
    // API Secret is optional for unauthenticated calls
    client := golastfmclient.New("YOUR_API_KEY", "")
    ctx := context.Background()

    // Search for an artist
    res, err := client.Artist.Search(ctx, "Cher", nil)
    if err != nil {
        panic(err)
    }
    
    for _, artist := range res.Results.ArtistMatches.Artist {
        fmt.Printf("Artist: %s (Listeners: %s)\n", artist.Name, artist.Listeners.String())
    }
}
2. Authenticated Operations (Scrobbling)
package main

import (
    "context"
    "time"
    "github.com/mrcl29/go-lastfm-client"
)

func main() {
    // Initialize with a session key
    client := golastfmclient.New("API_KEY", "API_SECRET", golastfmclient.WithSessionKey("USER_SESSION_KEY"))
    ctx := context.Background()

    // Update Now Playing
    _, err := client.Track.UpdateNowPlaying(ctx, "Daft Punk", "Around the World", nil)
    if err != nil {
        panic(err)
    }

    // Send Scrobble
    timestamp := time.Now().Unix()
    _, err = client.Track.Scrobble(ctx, "Daft Punk", "Around the World", timestamp, nil)
    if err != nil {
        panic(err)
    }
}

🏗️ Architecture & Design

Polymorphic JSON Handling

Last.fm's API is known for returning a single object when there is one result and an array when there are many. This library solves this globally using a custom internal/jsonutil package that ensures your code always receives a slice, regardless of the raw JSON structure.

Service-Oriented Design

The client is organized into domain-specific services, accessible directly from the main Client struct:

  • client.Album: Metadata, tags, search.
  • client.Artist: Bio, similar artists, top albums/tracks.
  • client.Track: Scrobbling, "Now Playing", corrections, similarity.
  • client.User: Profile, recent tracks, loved tracks, personal tags, weekly charts.
  • client.Tag: Tag metadata, top artists/tracks by tag.
  • client.Library: User library discovery.
  • client.Chart: Global charts for artists, tracks, and tags.
  • client.Geo: Top artists and tracks by country.
  • client.Auth: Token and Session management.

📚 Examples

Check the examples/ directory for more detailed use cases:

🧪 Testing

The library is designed with testability as a core principle. All services use an APIClient interface, allowing for easy mocking.

Run tests:

go test ./...

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

Constants

View Source 
const (
	// DefaultBaseURL is the default Last.fm API base URL.
	DefaultBaseURL = "https://ws.audioscrobbler.com/2.0/"
	// DefaultUserAgent is the default User-Agent header used by the client.
	DefaultUserAgent = "go-lastfm-client/0.1.0 (github.com/mrcl29/go-lastfm-client)"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIClient 

type APIClient interface {
	Call(ctx context.Context, httpMethod string, apiMethod string, params url.Values, target interface{}) error
}

APIClient defines the interface required by the services.

type APIError 

type APIError struct {
	Code    int    `json:"error"`
	Message string `json:"message"`
}

APIError represents a Last.fm API error.

func (*APIError) Error 

func (e *APIError) Error() string

type Album 

type Album struct {
	Name        string      `json:"name,omitempty"`
	Title       string      `json:"title,omitempty"`  // Some endpoints use "title"
	Text        string      `json:"#text,omitempty"`  // Some endpoints use "#text" for name
	Artist      interface{} `json:"artist,omitempty"` // Can be string or Artist struct
	ID          string      `json:"id,omitempty"`
	MBID        string      `json:"mbid,omitempty"`
	URL         string      `json:"url,omitempty"`
	ReleaseDate string      `json:"releasedate,omitempty"`
	Image       []Image     `json:"image,omitempty"`
	Listeners   string      `json:"listeners,omitempty"`
	Playcount   json.Number `json:"playcount,omitempty"`
	TopTags     *TopTags    `json:"toptags,omitempty"`
	Tracks      *Tracks     `json:"tracks,omitempty"`
	Wiki        *Wiki       `json:"wiki,omitempty"`
	Streamable  string      `json:"streamable,omitempty"`
	Rank        json.Number `json:"rank,omitempty"`
}

Album represents a Last.fm album.

type AlbumList 

type AlbumList []Album

AlbumList is a slice of Album that handles both a single object and an array in JSON.

func (*AlbumList) UnmarshalJSON 

func (a *AlbumList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type AlbumService 

type AlbumService struct {
	// contains filtered or unexported fields
}

AlbumService handles API calls related to albums.

func NewAlbumService 

func NewAlbumService(client APIClient) *AlbumService

NewAlbumService creates a new album service.

func (*AlbumService) AddTags 

func (s *AlbumService) AddTags(ctx context.Context, artist, album, tags string) error

AddTags tags an album using a list of user supplied tags. See: http://www.last.fm/api/show/album.addTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • album: The album name.
  • tags: A comma-separated list of tags to apply.

Returns:

  • error: Error if the request fails.

func (*AlbumService) GetInfo 

func (s *AlbumService) GetInfo(ctx context.Context, artist, album string, options url.Values) (*Album, error)

GetInfo gets the metadata and tracklist for an album. See: http://www.last.fm/api/show/album.getInfo

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • album: The album name.
  • options: Additional options (e.g. lang, mbid, username).

Returns:

  • *Album: The album details.
  • error: Error if the request fails.

func (*AlbumService) GetTags 

func (s *AlbumService) GetTags(ctx context.Context, artist, album string, options url.Values) (TagList, error)

GetTags gets the tags applied by an individual user to an album. See: http://www.last.fm/api/show/album.getTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • album: The album name.
  • options: Additional options (e.g. user, mbid).

Returns:

  • TagList: A slice of tags applied by the user.
  • error: Error if the request fails.

func (*AlbumService) GetTopTags 

func (s *AlbumService) GetTopTags(ctx context.Context, artist, album string, options url.Values) (TagList, error)

GetTopTags gets the top tags for an album. See: http://www.last.fm/api/show/album.getTopTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • album: The album name.
  • options: Additional options (e.g. mbid).

Returns:

  • TagList: A slice of top tags for the album.
  • error: Error if the request fails.

func (*AlbumService) RemoveTag 

func (s *AlbumService) RemoveTag(ctx context.Context, artist, album, tag string) error

RemoveTag removes a user supplied tag from an album. See: http://www.last.fm/api/show/album.removeTag

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • album: The album name.
  • tag: A single tag to remove.

Returns:

  • error: Error if the request fails.

func (*AlbumService) Search 

func (s *AlbumService) Search(ctx context.Context, album string, options url.Values) (AlbumList, error)

Search searches for an album by name. See: http://www.last.fm/api/show/album.search

Parameters:

  • ctx: Context for the request.
  • album: The album name to search for.
  • options: Additional options (e.g. page, limit).

Returns:

  • AlbumList: A slice of albums matching the search.
  • error: Error if the request fails.

type Artist 

type Artist struct {
	Name       string      `json:"name"`
	MBID       string      `json:"mbid"`
	URL        string      `json:"url,omitempty"`
	Image      []Image     `json:"image,omitempty"`
	Streamable string      `json:"streamable,omitempty"`
	Stats      *Stats      `json:"stats,omitempty"`
	Similar    *Similar    `json:"similar,omitempty"`
	Tags       *Tags       `json:"tags,omitempty"`
	Bio        *Bio        `json:"bio,omitempty"`
	Match      float64     `json:"match,string,omitempty"`
	Listeners  json.Number `json:"listeners,omitempty"`
	Playcount  json.Number `json:"playcount,omitempty"`
	Tagcount   json.Number `json:"tagcount,omitempty"`
	Rank       json.Number `json:"rank,omitempty"`
}

Artist represents a Last.fm artist.

type ArtistList 

type ArtistList []Artist

ArtistList is a slice of Artist that handles both a single object and an array in JSON.

func (*ArtistList) UnmarshalJSON 

func (a *ArtistList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type ArtistService 

type ArtistService struct {
	// contains filtered or unexported fields
}

ArtistService handles API calls related to artists.

func NewArtistService 

func NewArtistService(client APIClient) *ArtistService

NewArtistService creates a new artist service.

func (*ArtistService) AddTags 

func (s *ArtistService) AddTags(ctx context.Context, artist, tags string) error

AddTags tags an artist using a list of user supplied tags. See: http://www.last.fm/api/show/artist.addTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • tags: A comma-separated list of tags to apply.

Returns:

  • error: Error if the request fails.

func (*ArtistService) GetCorrection 

func (s *ArtistService) GetCorrection(ctx context.Context, artist string) (*Artist, error)

GetCorrection checks whether the supplied artist has a correction to a canonical artist. See: http://www.last.fm/api/show/artist.getCorrection

Parameters:

  • ctx: Context for the request.
  • artist: The artist name to correct.

Returns:

  • *Artist: The corrected artist details.
  • error: Error if the request fails.

func (*ArtistService) GetInfo 

func (s *ArtistService) GetInfo(ctx context.Context, artist string, options url.Values) (*Artist, error)

GetInfo gets the metadata for an artist. See: http://www.last.fm/api/show/artist.getInfo

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • options: Additional options (e.g. lang, mbid, username, autocorrect).

Returns:

  • *Artist: The artist details.
  • error: Error if the request fails.

func (*ArtistService) GetSimilar 

func (s *ArtistService) GetSimilar(ctx context.Context, artist string, options url.Values) (ArtistList, error)

GetSimilar gets all the artists similar to this artist. See: http://www.last.fm/api/show/artist.getSimilar

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • options: Additional options (e.g. limit, mbid, autocorrect).

Returns:

  • ArtistList: A slice of similar artists.
  • error: Error if the request fails.

func (*ArtistService) GetTags 

func (s *ArtistService) GetTags(ctx context.Context, artist string, options url.Values) (TagList, error)

GetTags gets the tags applied by an individual user to an artist. See: http://www.last.fm/api/show/artist.getTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • options: Additional options (e.g. user, mbid, autocorrect).

Returns:

  • TagList: A slice of tags applied by the user.
  • error: Error if the request fails.

func (*ArtistService) GetTopAlbums 

func (s *ArtistService) GetTopAlbums(ctx context.Context, artist string, options url.Values) (AlbumList, *Attr, error)

GetTopAlbums gets the top albums for an artist on Last.fm, ordered by popularity. See: http://www.last.fm/api/show/artist.getTopAlbums

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • options: Additional options (e.g. page, limit, mbid, autocorrect).

Returns:

  • AlbumList: A slice of top albums for the artist.
  • *Attr: Pagination and metadata.
  • error: Error if the request fails.

func (*ArtistService) GetTopTags 

func (s *ArtistService) GetTopTags(ctx context.Context, artist string, options url.Values) (TagList, error)

GetTopTags gets the top tags for an artist. See: http://www.last.fm/api/show/artist.getTopTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • options: Additional options (e.g. mbid, autocorrect).

Returns:

  • TagList: A slice of top tags for the artist.
  • error: Error if the request fails.

func (*ArtistService) GetTopTracks 

func (s *ArtistService) GetTopTracks(ctx context.Context, artist string, options url.Values) (TrackList, *Attr, error)

GetTopTracks gets the top tracks by an artist on Last.fm, ordered by popularity. See: http://www.last.fm/api/show/artist.getTopTracks

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • options: Additional options (e.g. page, limit, mbid, autocorrect).

Returns:

  • TrackList: A slice of top tracks for the artist.
  • *Attr: Pagination and metadata.
  • error: Error if the request fails.

func (*ArtistService) RemoveTag 

func (s *ArtistService) RemoveTag(ctx context.Context, artist, tag string) error

RemoveTag removes a user supplied tag from an artist. See: http://www.last.fm/api/show/artist.removeTag

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • tag: A single tag to remove.

Returns:

  • error: Error if the request fails.

func (*ArtistService) Search 

func (s *ArtistService) Search(ctx context.Context, artist string, options url.Values) (ArtistList, error)

Search searches for an artist by name. See: http://www.last.fm/api/show/artist.search

Parameters:

  • ctx: Context for the request.
  • artist: The artist name to search for.
  • options: Additional options (e.g. page, limit).

Returns:

  • ArtistList: A slice of artists matching the search.
  • error: Error if the request fails.

type Attr 

type Attr struct {
	Page       json.Number `json:"page,omitempty"`
	PerPage    json.Number `json:"perPage,omitempty"`
	TotalPages json.Number `json:"totalPages,omitempty"`
	Total      json.Number `json:"total,omitempty"`
	User       string      `json:"user,omitempty"`
	Country    string      `json:"country,omitempty"`
	Artist     string      `json:"artist,omitempty"`
	Tag        string      `json:"tag,omitempty"`
	From       string      `json:"from,omitempty"`
	To         string      `json:"to,omitempty"`
}

Attr represents metadata for responses.

type AuthService 

type AuthService struct {
	// contains filtered or unexported fields
}

AuthService handles authentication-related API calls.

func (*AuthService) AuthURL 

func (s *AuthService) AuthURL(token string) string

AuthURL returns the URL the user should be redirected to for authorization. For Web applications, token can be empty. For Desktop, it should be the token from GetToken.

func (*AuthService) GetMobileSession 

func (s *AuthService) GetMobileSession(ctx context.Context, username, password string) (Session, error)

GetMobileSession fetches a session key for a mobile application using credentials. Note: This method uses a POST request over HTTPS as required by Last.fm.

func (*AuthService) GetSession 

func (s *AuthService) GetSession(ctx context.Context, token string) (Session, error)

GetSession fetches a web service session for a user. The token should be the one received after user authorization.

func (*AuthService) GetToken 

func (s *AuthService) GetToken(ctx context.Context) (string, error)

GetToken fetches a request token for the Desktop authentication flow.

type Bio 

type Bio struct {
	Published string `json:"published"`
	Summary   string `json:"summary"`
	Content   string `json:"content"`
}

Bio represents biography information for an artist.

type Chart 

type Chart struct {
	Text string `json:"#text"`
	From string `json:"from"`
	To   string `json:"to"`
}

Chart represents a weekly chart entry.

type ChartList 

type ChartList []Chart

ChartList is a slice of Chart that handles both a single object and an array in JSON.

func (*ChartList) UnmarshalJSON 

func (c *ChartList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type ChartService 

type ChartService struct {
	// contains filtered or unexported fields
}

ChartService handles API calls related to charts.

func NewChartService 

func NewChartService(client APIClient) *ChartService

NewChartService creates a new chart service.

func (*ChartService) GetTopArtists 

func (s *ChartService) GetTopArtists(ctx context.Context, options url.Values) (ArtistList, *Attr, error)

GetTopArtists gets the top artists chart. See: http://www.last.fm/api/show/chart.getTopArtists

Parameters:

  • ctx: Context for the request.
  • options: Additional options (e.g. page, limit).

Returns:

  • ArtistList: A slice of top artists.
  • *Attr: Pagination and metadata.
  • error: Error if the request fails.

func (*ChartService) GetTopTags 

func (s *ChartService) GetTopTags(ctx context.Context, options url.Values) (TagList, *Attr, error)

GetTopTags gets the top tags chart. See: http://www.last.fm/api/show/chart.getTopTags

Parameters:

  • ctx: Context for the request.
  • options: Additional options (e.g. page, limit).

Returns:

  • TagList: A slice of top tags.
  • *Attr: Pagination and metadata.
  • error: Error if the request fails.

func (*ChartService) GetTopTracks 

func (s *ChartService) GetTopTracks(ctx context.Context, options url.Values) (TrackList, *Attr, error)

GetTopTracks gets the top tracks chart. See: http://www.last.fm/api/show/chart.getTopTracks

Parameters:

  • ctx: Context for the request.
  • options: Additional options (e.g. page, limit).

Returns:

  • TrackList: A slice of top tracks.
  • *Attr: Pagination and metadata.
  • error: Error if the request fails.

type Client 

type Client struct {
	Auth    *AuthService
	Track   *TrackService
	Artist  *ArtistService
	Album   *AlbumService
	User    *UserService
	Chart   *ChartService
	Geo     *GeoService
	Tag     *TagService
	Library *LibraryService
	// contains filtered or unexported fields
}

Client is a Last.fm API client.

func New 

func New(apiKey string, apiSecret string, opts ...Option) *Client

New creates a new Last.fm API client.

func (*Client) Call 

func (c *Client) Call(ctx context.Context, httpMethod string, apiMethod string, params url.Values, target interface{}) error

Call performs a request to the Last.fm API.

type Date 

type Date struct {
	UnixTime json.Number `json:"unixtime"`
	Text     json.Number `json:"#text"`
}

Date represents a Last.fm date response.

type Friend 

type Friend struct {
	Name       string  `json:"name"`
	RealName   string  `json:"realname"`
	Image      []Image `json:"image"`
	URL        string  `json:"url"`
	Country    string  `json:"country"`
	Registered Date    `json:"registered"`
}

Friend represents a Last.fm user's friend.

type FriendList 

type FriendList []Friend

FriendList is a slice of Friend that handles both a single object and an array in JSON.

func (*FriendList) UnmarshalJSON 

func (f *FriendList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type GeoService 

type GeoService struct {
	// contains filtered or unexported fields
}

GeoService handles API calls related to geography.

func NewGeoService 

func NewGeoService(client APIClient) *GeoService

NewGeoService creates a new geo service.

func (*GeoService) GetTopArtists 

func (s *GeoService) GetTopArtists(ctx context.Context, country string, options url.Values) (ArtistList, *Attr, error)

GetTopArtists gets the most popular artists on Last.fm by country. See: http://www.last.fm/api/show/geo.getTopArtists

Parameters:

  • ctx: Context for the request.
  • country: A country name, as defined by the ISO 3166-1 country names standard.
  • options: Additional options (e.g. page, limit).

Returns:

  • ArtistList: A slice of top artists.
  • *Attr: Pagination and metadata.
  • error: Error if the request fails.

func (*GeoService) GetTopTracks 

func (s *GeoService) GetTopTracks(ctx context.Context, country string, options url.Values) (TrackList, *Attr, error)

GetTopTracks gets the most popular tracks on Last.fm last week by country. See: http://www.last.fm/api/show/geo.getTopTracks

Parameters:

  • ctx: Context for the request.
  • country: A country name, as defined by the ISO 3166-1 country names standard.
  • options: Additional options (e.g. page, limit, location).

Returns:

  • TrackList: A slice of top tracks.
  • *Attr: Pagination and metadata.
  • error: Error if the request fails.

type Image 

type Image struct {
	Text string `json:"#text"`
	Size string `json:"size"`
}

Image represents a Last.fm image.

type LibraryService 

type LibraryService struct {
	// contains filtered or unexported fields
}

LibraryService handles API calls related to a user's library.

func NewLibraryService 

func NewLibraryService(client APIClient) *LibraryService

NewLibraryService creates a new library service.

func (*LibraryService) GetArtists 

func (s *LibraryService) GetArtists(ctx context.Context, user string, options url.Values) (ArtistList, *Attr, error)

GetArtists gets a paginated list of all the artists in a user's library. See: http://www.last.fm/api/show/library.getArtists

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. page, limit).

Returns:

  • ArtistList: A slice of artists in the user's library.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

type Option 

type Option func(*Client)

Option is a functional option for configuring the client.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL sets a custom base URL.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithSessionKey 

func WithSessionKey(sessionKey string) Option

WithSessionKey sets the session key for authenticated requests.

func WithUserAgent 

func WithUserAgent(userAgent string) Option

WithUserAgent sets a custom User-Agent header.

type ScrobbleResult 

type ScrobbleResult struct {
	Artist    trackCorrectionEntity `json:"artist"`
	Album     trackCorrectionEntity `json:"album"`
	Track     trackCorrectionEntity `json:"track"`
	Timestamp string                `json:"timestamp"`
}

ScrobbleResult represents the result of a single scrobble.

type ScrobbleResults 

type ScrobbleResults = Scrobbles

ScrobbleResults is an alias for Scrobbles for backward compatibility or clarity.

type Scrobbles added in v1.0.2 

type Scrobbles []ScrobbleResult

Scrobbles is a slice of ScrobbleResult that handles both a single object and an array in JSON.

func (*Scrobbles) UnmarshalJSON added in v1.0.2 

func (s *Scrobbles) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Session 

type Session struct {
	Name       string      `json:"name"`
	Key        string      `json:"key"`
	Subscriber json.Number `json:"subscriber"`
}

Session represents a Last.fm user session.

type Similar 

type Similar struct {
	Artist ArtistList `json:"artist,omitempty"`
	Tag    TagList    `json:"tag,omitempty"`
}

Similar represents similar artists or tags.

type Stats 

type Stats struct {
	Listeners json.Number `json:"listeners"`
	Playcount json.Number `json:"playcount"`
}

Stats represents statistics for an artist.

type Streamable 

type Streamable struct {
	Text      string `json:"#text"`
	FullTrack string `json:"fulltrack"`
}

Streamable represents streamable status.

type Tag 

type Tag struct {
	Name       string      `json:"name"`
	URL        string      `json:"url"`
	Count      json.Number `json:"count,omitempty"`
	Reach      json.Number `json:"reach,omitempty"`
	Taggings   json.Number `json:"taggings,omitempty"`
	Streamable string      `json:"streamable,omitempty"`
	Wiki       *Wiki       `json:"wiki,omitempty"`
}

Tag represents a Last.fm tag.

type TagList 

type TagList []Tag

TagList is a slice of Tag that handles both a single object and an array in JSON.

func (*TagList) UnmarshalJSON 

func (t *TagList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type TagService 

type TagService struct {
	// contains filtered or unexported fields
}

TagService handles API calls related to tags.

func NewTagService 

func NewTagService(client APIClient) *TagService

NewTagService creates a new tag service.

func (*TagService) GetInfo 

func (s *TagService) GetInfo(ctx context.Context, tag string, options url.Values) (*Tag, error)

GetInfo gets the metadata for a tag. See: http://www.last.fm/api/show/tag.getInfo

Parameters:

  • ctx: Context for the request.
  • tag: The tag name.
  • options: Additional options (e.g. lang).

Returns:

  • *Tag: The tag details.
  • error: Error if the request fails.

func (*TagService) GetSimilar 

func (s *TagService) GetSimilar(ctx context.Context, tag string, options url.Values) (TagList, error)

GetSimilar gets all the tags similar to this tag. See: http://www.last.fm/api/show/tag.getSimilar

Parameters:

  • ctx: Context for the request.
  • tag: The tag name.
  • options: Additional options.

Returns:

  • TagList: A slice of similar tags.
  • error: Error if the request fails.

func (*TagService) GetTopAlbums 

func (s *TagService) GetTopAlbums(ctx context.Context, tag string, options url.Values) (AlbumList, *Attr, error)

GetTopAlbums gets the top albums for a tag. See: http://www.last.fm/api/show/tag.getTopAlbums

Parameters:

  • ctx: Context for the request.
  • tag: The tag name.
  • options: Additional options (e.g. page, limit).

Returns:

  • AlbumList: A slice of top albums for the tag.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*TagService) GetTopArtists 

func (s *TagService) GetTopArtists(ctx context.Context, tag string, options url.Values) (ArtistList, *Attr, error)

GetTopArtists gets the top artists for a tag. See: http://www.last.fm/api/show/tag.getTopArtists

Parameters:

  • ctx: Context for the request.
  • tag: The tag name.
  • options: Additional options (e.g. page, limit).

Returns:

  • ArtistList: A slice of top artists for the tag.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*TagService) GetTopTags 

func (s *TagService) GetTopTags(ctx context.Context, options url.Values) (TagList, error)

GetTopTags gets the top tags on Last.fm. See: http://www.last.fm/api/show/tag.getTopTags

Parameters:

  • ctx: Context for the request.
  • options: Additional options (e.g. page, limit).

Returns:

  • TagList: A slice of top tags.
  • error: Error if the request fails.

func (*TagService) GetTopTracks 

func (s *TagService) GetTopTracks(ctx context.Context, tag string, options url.Values) (TrackList, *Attr, error)

GetTopTracks gets the top tracks for a tag. See: http://www.last.fm/api/show/tag.getTopTracks

Parameters:

  • ctx: Context for the request.
  • tag: The tag name.
  • options: Additional options (e.g. page, limit).

Returns:

  • TrackList: A slice of top tracks for the tag.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*TagService) GetWeeklyChartList 

func (s *TagService) GetWeeklyChartList(ctx context.Context, tag string, options url.Values) (ChartList, error)

GetWeeklyChartList gets a list of available charts for this tag. See: http://www.last.fm/api/show/tag.getWeeklyChartList

Parameters:

  • ctx: Context for the request.
  • tag: The tag name.
  • options: Additional options.

Returns:

  • ChartList: A slice of available charts.
  • error: Error if the request fails.

type Tags 

type Tags struct {
	Tag TagList `json:"tag"`
}

Tags represents tags for an artist.

type TopTags 

type TopTags struct {
	Tag TagList `json:"tag"`
}

TopTags represents top tags for an entity.

type Track 

type Track struct {
	Name       string      `json:"name"`
	Duration   json.Number `json:"duration,omitempty"`
	MBID       string      `json:"mbid"`
	URL        string      `json:"url"`
	Streamable interface{} `json:"streamable,omitempty"` // Can be string or Streamable struct
	Artist     interface{} `json:"artist,omitempty"`     // Can be string or Artist struct
	Album      interface{} `json:"album,omitempty"`      // Can be string or Album struct
	Rank       json.Number `json:"rank,omitempty"`
	Playcount  json.Number `json:"playcount,omitempty"`
	Listeners  json.Number `json:"listeners,omitempty"`
	Image      []Image     `json:"image,omitempty"`
	TopTags    *TopTags    `json:"toptags,omitempty"`
	Wiki       *Wiki       `json:"wiki,omitempty"`
	Date       *Date       `json:"date,omitempty"`
	Attr       *TrackAttr  `json:"@attr,omitempty"`
}

Track represents a Last.fm track.

type TrackAttr 

type TrackAttr struct {
	NowPlaying string      `json:"nowplaying"`
	Rank       json.Number `json:"rank,omitempty"`
}

TrackAttr represents metadata for a track (e.g. nowplaying).

type TrackList 

type TrackList []Track

TrackList is a slice of Track that handles both a single object and an array in JSON.

func (*TrackList) UnmarshalJSON 

func (t *TrackList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type TrackService 

type TrackService struct {
	// contains filtered or unexported fields
}

TrackService handles API calls related to tracks.

func NewTrackService 

func NewTrackService(client APIClient) *TrackService

NewTrackService creates a new track service.

func (*TrackService) AddTags 

func (s *TrackService) AddTags(ctx context.Context, artist, track, tags string) error

AddTags tags a track using a list of user supplied tags. See: http://www.last.fm/api/show/track.addTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • tags: A comma-separated list of tags to apply.

Returns:

  • error: Error if the request fails.

func (*TrackService) GetCorrection 

func (s *TrackService) GetCorrection(ctx context.Context, artist, track string) (*Track, error)

GetCorrection gets the corrected artist/track names. See: http://www.last.fm/api/show/track.getCorrection

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.

Returns:

  • *Track: The corrected track details.
  • error: Error if the request fails.

func (*TrackService) GetInfo 

func (s *TrackService) GetInfo(ctx context.Context, artist, track string, options url.Values) (*Track, error)

GetInfo gets the metadata for a track. See: http://www.last.fm/api/show/track.getInfo

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • options: Additional options (e.g. mbid, username, autocorrect).

Returns:

  • *Track: The track details.
  • error: Error if the request fails.

func (*TrackService) GetSimilar 

func (s *TrackService) GetSimilar(ctx context.Context, artist, track string, options url.Values) (TrackList, error)

GetSimilar gets similar tracks. See: http://www.last.fm/api/show/track.getSimilar

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • options: Additional options (e.g. limit, mbid, autocorrect).

Returns:

  • TrackList: A slice of similar tracks.
  • error: Error if the request fails.

func (*TrackService) GetTags 

func (s *TrackService) GetTags(ctx context.Context, artist, track string, options url.Values) (TagList, error)

GetTags gets the tags applied by an individual user to a track. See: http://www.last.fm/api/show/track.getTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • options: Additional options (e.g. user, mbid, autocorrect).

Returns:

  • TagList: A slice of tags applied by the user.
  • error: Error if the request fails.

func (*TrackService) GetTopTags 

func (s *TrackService) GetTopTags(ctx context.Context, artist, track string, options url.Values) (TagList, error)

GetTopTags gets the top tags for a track. See: http://www.last.fm/api/show/track.getTopTags

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • options: Additional options (e.g. mbid, autocorrect).

Returns:

  • TagList: A slice of top tags for the track.
  • error: Error if the request fails.

func (*TrackService) Love 

func (s *TrackService) Love(ctx context.Context, artist, track string) error

Love loves a track. See: http://www.last.fm/api/show/track.love

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.

Returns:

  • error: Error if the request fails.

func (*TrackService) RemoveTag 

func (s *TrackService) RemoveTag(ctx context.Context, artist, track, tag string) error

RemoveTag removes a user supplied tag from a track. See: http://www.last.fm/api/show/track.removeTag

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • tag: A single tag to remove.

Returns:

  • error: Error if the request fails.

func (*TrackService) Scrobble 

func (s *TrackService) Scrobble(ctx context.Context, artist, track string, timestamp int64, options url.Values) (ScrobbleResults, error)

Scrobble adds a track-play to a user's profile. See: http://www.last.fm/api/show/track.scrobble

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • timestamp: The time the track started playing (Unix timestamp).
  • options: Additional options (e.g. album, trackNumber, context, streamId, albumArtist).

Returns:

  • ScrobbleResults: Results of the scrobble request.
  • error: Error if the request fails.

func (*TrackService) Search 

func (s *TrackService) Search(ctx context.Context, track string, options url.Values) (TrackList, error)

Search searches for a track by name. See: http://www.last.fm/api/show/track.search

Parameters:

  • ctx: Context for the request.
  • track: The track name to search for.
  • options: Additional options (e.g. artist, page, limit).

Returns:

  • TrackList: A slice of tracks matching the search.
  • error: Error if the request fails.

func (*TrackService) Unlove 

func (s *TrackService) Unlove(ctx context.Context, artist, track string) error

Unlove unloves a track. See: http://www.last.fm/api/show/track.unlove

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.

Returns:

  • error: Error if the request fails.

func (*TrackService) UpdateNowPlaying 

func (s *TrackService) UpdateNowPlaying(ctx context.Context, artist, track string, options url.Values) (*ScrobbleResult, error)

UpdateNowPlaying notifies Last.fm that a user has started listening to a track. See: http://www.last.fm/api/show/track.updateNowPlaying

Parameters:

  • ctx: Context for the request.
  • artist: The artist name.
  • track: The track name.
  • options: Additional options (e.g. album, trackNumber, context, albumArtist).

Returns:

  • *ScrobbleResult: Result of the now playing update.
  • error: Error if the request fails.

type Tracks 

type Tracks struct {
	Track TrackList `json:"track"`
}

Tracks represents the tracklist of an album.

type User 

type User struct {
	Name       string      `json:"name"`
	RealName   string      `json:"realname"`
	Image      []Image     `json:"image"`
	URL        string      `json:"url"`
	Country    string      `json:"country"`
	Age        json.Number `json:"age"`
	Gender     string      `json:"gender"`
	Subscriber json.Number `json:"subscriber"`
	Playcount  json.Number `json:"playcount"`
	Playlists  json.Number `json:"playlists"`
	Bootstrap  json.Number `json:"bootstrap"`
	Registered Date        `json:"registered"`
}

User represents a Last.fm user.

type UserService 

type UserService struct {
	// contains filtered or unexported fields
}

UserService handles API calls related to users.

func NewUserService 

func NewUserService(client APIClient) *UserService

NewUserService creates a new user service.

func (*UserService) GetFriends 

func (s *UserService) GetFriends(ctx context.Context, user string, options url.Values) (FriendList, *Attr, error)

GetFriends gets the friends for a user. See: http://www.last.fm/api/show/user.getFriends

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. recenttracks, page, limit).

Returns:

  • FriendList: A slice of friends.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*UserService) GetInfo 

func (s *UserService) GetInfo(ctx context.Context, user string, options url.Values) (*User, error)

GetInfo gets the metadata for a user. See: http://www.last.fm/api/show/user.getInfo

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options.

Returns:

  • *User: The user details.
  • error: Error if the request fails.

func (*UserService) GetLovedTracks 

func (s *UserService) GetLovedTracks(ctx context.Context, user string, options url.Values) (TrackList, *Attr, error)

GetLovedTracks gets the loved tracks for a user. See: http://www.last.fm/api/show/user.getLovedTracks

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. page, limit).

Returns:

  • TrackList: A slice of loved tracks.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*UserService) GetPersonalTags 

func (s *UserService) GetPersonalTags(ctx context.Context, user, tag, taggingType string, options url.Values) (*UserTaggings, *Attr, error)

GetPersonalTags gets the user's personal tags. See: http://www.last.fm/api/show/user.getPersonalTags

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • tag: The tag name.
  • taggingType: The type of items to return (artist, album, or track).
  • options: Additional options (e.g. page, limit).

Returns:

  • *UserTaggings: The tagged items.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*UserService) GetRecentTracks 

func (s *UserService) GetRecentTracks(ctx context.Context, user string, options url.Values) (TrackList, *Attr, error)

GetRecentTracks gets a list of the recent tracks listened to by this user. See: http://www.last.fm/api/show/user.getRecentTracks

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. page, limit, from, to).

Returns:

  • TrackList: A slice of recent tracks.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*UserService) GetTopAlbums 

func (s *UserService) GetTopAlbums(ctx context.Context, user string, options url.Values) (AlbumList, *Attr, error)

GetTopAlbums gets the top albums listened to by a user. See: http://www.last.fm/api/show/user.getTopAlbums

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. period, page, limit).

Returns:

  • AlbumList: A slice of top albums.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*UserService) GetTopArtists 

func (s *UserService) GetTopArtists(ctx context.Context, user string, options url.Values) (ArtistList, *Attr, error)

GetTopArtists gets the top artists listened to by a user. See: http://www.last.fm/api/show/user.getTopArtists

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. period, page, limit).

Returns:

  • ArtistList: A slice of top artists.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*UserService) GetTopTags 

func (s *UserService) GetTopTags(ctx context.Context, user string, options url.Values) (TagList, error)

GetTopTags gets the top tags for a user. See: http://www.last.fm/api/show/user.getTopTags

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options.

Returns:

  • TagList: A slice of top tags.
  • error: Error if the request fails.

func (*UserService) GetTopTracks 

func (s *UserService) GetTopTracks(ctx context.Context, user string, options url.Values) (TrackList, *Attr, error)

GetTopTracks gets the top tracks listened to by a user. See: http://www.last.fm/api/show/user.getTopTracks

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. period, page, limit).

Returns:

  • TrackList: A slice of top tracks.
  • *Attr: Pagination metadata.
  • error: Error if the request fails.

func (*UserService) GetWeeklyAlbumChart 

func (s *UserService) GetWeeklyAlbumChart(ctx context.Context, user string, options url.Values) (AlbumList, *Attr, error)

GetWeeklyAlbumChart gets the weekly album chart for a user. See: http://www.last.fm/api/show/user.getWeeklyAlbumChart

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. from, to).

Returns:

  • AlbumList: A slice of albums in the chart.
  • *Attr: Metadata (user, from, to).
  • error: Error if the request fails.

func (*UserService) GetWeeklyArtistChart 

func (s *UserService) GetWeeklyArtistChart(ctx context.Context, user string, options url.Values) (ArtistList, *Attr, error)

GetWeeklyArtistChart gets the weekly artist chart for a user. See: http://www.last.fm/api/show/user.getWeeklyArtistChart

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. from, to).

Returns:

  • ArtistList: A slice of artists in the chart.
  • *Attr: Metadata (user, from, to).
  • error: Error if the request fails.

func (*UserService) GetWeeklyChartList 

func (s *UserService) GetWeeklyChartList(ctx context.Context, user string) (ChartList, error)

GetWeeklyChartList gets a list of available weekly charts for a user. See: http://www.last.fm/api/show/user.getWeeklyChartList

Parameters:

  • ctx: Context for the request.
  • user: The user name.

Returns:

  • ChartList: A slice of available charts.
  • error: Error if the request fails.

func (*UserService) GetWeeklyTrackChart 

func (s *UserService) GetWeeklyTrackChart(ctx context.Context, user string, options url.Values) (TrackList, *Attr, error)

GetWeeklyTrackChart gets the weekly track chart for a user. See: http://www.last.fm/api/show/user.getWeeklyTrackChart

Parameters:

  • ctx: Context for the request.
  • user: The user name.
  • options: Additional options (e.g. from, to).

Returns:

  • TrackList: A slice of tracks in the chart.
  • *Attr: Metadata (user, from, to).
  • error: Error if the request fails.

type UserTaggings added in v1.0.2 

type UserTaggings struct {
	Artists ArtistList
	Albums  AlbumList
	Tracks  TrackList
}

UserTaggings represents the results of a personal tags request.

type Wiki 

type Wiki struct {
	Published string `json:"published,omitempty"`
	Summary   string `json:"summary,omitempty"`
	Content   string `json:"content,omitempty"`
}

Wiki represents the wiki information for an entity.

Source Files

View all Source files

Directories

Path Synopsis
examples
auth_desktop command
auth_mobile command
music_discovery command
scrobble_and_love command
internal
api
jsonutil

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.