Categorygithub.com/chew-z/spotify
modulepackage
0.0.21
Repository: https://github.com/chew-z/spotify.git
Documentation: pkg.go.dev

# README

Spotify

GoDoc Build status Build Status

This is a Go wrapper for working with Spotify's Web API.

It aims to support every task listed in the Web API Endpoint Reference, located here.

By using this library you agree to Spotify's Developer Terms of Use.

Installation

To install the library, simply

go get github.com/zmb3/spotify

Authentication

Spotify uses OAuth2 for authentication and authorization.
As of May 29, 2017 all Web API endpoints require an access token.

You can authenticate using a client credentials flow, but this does not provide any authorization to access a user's private data. For most use cases, you'll want to use the authorization code flow. This package includes an Authenticator type to handle the details for you.

Start by registering your application at the following page:

https://developer.spotify.com/my-applications/.

You'll get a client ID and secret key for your application. An easy way to provide this data to your application is to set the SPOTIFY_ID and SPOTIFY_SECRET environment variables. If you choose not to use environment variables, you can provide this data manually.

// the redirect URL must be an exact match of a URL you've registered for your application
// scopes determine which permissions the user is prompted to authorize
auth := spotify.NewAuthenticator(redirectURL, spotify.ScopeUserReadPrivate)

// if you didn't store your ID and secret key in the specified environment variables,
// you can set them manually here
auth.SetAuthInfo(clientID, secretKey)

// get the user to this URL - how you do that is up to you
// you should specify a unique state string to identify the session
url := auth.AuthURL(state)

// the user will eventually be redirected back to your redirect URL
// typically you'll have a handler set up like the following:
func redirectHandler(w http.ResponseWriter, r *http.Request) {
      // use the same state string here that you used to generate the URL
      token, err := auth.Token(state, r)
      if err != nil {
            http.Error(w, "Couldn't get token", http.StatusNotFound)
            return
      }
      // create a client using the specified token
      client := auth.NewClient(token)

      // the client can now be used to make authenticated requests
}

You may find the following resources useful:

  1. Spotify's Web API Authorization Guide: https://developer.spotify.com/web-api/authorization-guide/

  2. Go's OAuth2 package: https://godoc.org/golang.org/x/oauth2/google

Helpful Hints

Optional Parameters

Many of the functions in this package come in two forms - a simple version that omits optional parameters and uses reasonable defaults, and a more sophisticated version that accepts additional parameters. The latter is suffixed with Opt to indicate that it accepts some optional parameters.

Automatic Retries

The API will throttle your requests if you are sending them too rapidly. The client can be configured to wait and re-attempt the request. To enable this, set the AutoRetry field on the Client struct to true.

For more information, see Spotify rate-limits.

API Examples

Examples of the API can be found in the examples directory.

You may find tools such as Spotify's Web API Console or Rapid API valuable for experimenting with the API.

# Packages

No description provided by the author

# Functions

NewAuthenticator creates an authenticator which is used to implement the OAuth2 authorization flow.
NewTrackAttributes returns a new TrackAttributes instance with no attributes set.
NewTrackToRemove creates a new TrackToRemove object with the specified track ID and playlist locations.

# Constants

No description provided by the author
No description provided by the author
AlbumType values that can be used to filter which types of albums are searched for.
AlbumType values that can be used to filter which types of albums are searched for.
AlbumType values that can be used to filter which types of albums are searched for.
AlbumType values that can be used to filter which types of albums are searched for.
No description provided by the author
AuthURL is the URL to Spotify Accounts Service's OAuth2 endpoint.
No description provided by the author
No description provided by the author
No description provided by the author
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
ISO 3166-1 alpha 2 country codes.
No description provided by the author
No description provided by the author
DateLayout can be used with time.Parse to create time.Time values from Spotify date strings.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
MarketFromToken can be used in place of the Market parameter if the Client has a valid access token.
MaxNumberOfSeeds allowed by Spotify for a recommendation request.
No description provided by the author
ScopeImageUpload seeks permission to upload images to Spotify on your behalf.
ScopePlaylistModifyPrivate seeks write access to a user's private playlists.
ScopePlaylistModifyPublic seeks write access to a user's public playlists.
ScopePlaylistReadCollaborative seeks permission to access a user's collaborative playlists.
ScopePlaylistReadPrivate seeks permission to read a user's private playlists.
ScopeStreaming seeks permission to play music and control playback on your other devices.
ScopeUserFollowModify seeks write/delete access to the list of artists and other users that a user follows.
ScopeUserFollowRead seeks read access to the list of artists and other users that a user follows.
ScopeUserLibraryModify seeks write/delete access to a user's "Your Music" library.
ScopeUserLibraryRead seeks read access to a user's "Your Music" library.
ScopeUserModifyPlaybackState seeks write access to the user's current playback state.
ScopeUserReadCurrentlyPlaying seeks read access to a user's currently playing track.
ScopeUserReadEmail seeks read access to a user's email address.
ScopeUserReadPlaybackState seeks read access to the user's current playback state.
ScopeUserReadPrivate seeks read access to a user's subsription details (type of user account).
ScopeUserReadRecentlyPlayed allows access to a user's recently-played songs.
ScopeUserTopRead seeks read access to a user's top tracks and artists.
Search type values that can be passed to the Search function.
Search type values that can be passed to the Search function.
Search type values that can be passed to the Search function.
Search type values that can be passed to the Search function.
TimestampLayout can be used with time.Parse to create time.Time values from SpotifyTimestamp strings.
TokenURL is the URL to the Spotify Accounts Service's OAuth2 token endpoint.
Version is the version of this library.

# Variables

ErrNoMorePages is the error returned when you attempt to get the next (or previous) set of data but you've reached the end of the data set.

# Structs

AnalysisMeta describes details about Spotify's audio analysis of the track.
AnalysisTrack contains audio analysis data about the track as a whole.
AudioAnalysis contains a detailed audio analysis for a single track identified by its unique Spotify ID.
AudioFeatures contains various high-level acoustic attributes for a particular track.
Authenticator provides convenience functions for implementing the OAuth2 flow.
Category is used by Spotify to tag items in.
CategoryPage contains Category objects returned by the Web API.
Client is a client for working with the Spotify Web API.
Copyright contains the copyright statement associated with an album.
CurrentlyPlaying contains the information about currently playing items.
Cursor contains a key that can be used to find the next set of items.
Error represents an error returned by the Spotify Web API.
Followers contains information about the number of people following a particular artist or playlist.
FullAlbum provides extra album data in addition to the data provided by SimpleAlbum.
FullArtist provides extra artist data in addition to what is provided by SimpleArtist.
FullArtistCursorPage is a cursor-based paging object containing a set of FullArtist objects.
FullArtistPage contains FullArtists returned by the Web API.
FullPlaylist provides extra playlist data in addition to the data provided by SimplePlaylist.
FullTrack provides extra track data in addition to what is provided by SimpleTrack.
FullTrackPage contains FullTracks returned by the Web API.
Image identifies an image associated with an item.
Marker represents beats, bars, tatums and are used in segment and section descriptions.
Options contains optional parameters that can be provided to various API calls.
PlaybackContext is the playback context.
PlaybackOffset can be specified either by track URI OR Position.
PlayerDevice contains information about a device that a user can play music on.
PlayerState contains information about the current playback.
PlaylistOptions contains optional parameters that can be used when querying for featured playlists.
PlaylistReorderOptions is used with ReorderPlaylistTracks to reorder a track or group of tracks in a playlist.
PlaylistTrack contains info about a track in a playlist.
PlaylistTrackPage contains information about tracks in a playlist.
PlaylistTracks contains details about the tracks in a playlist.
No description provided by the author
PrivateUser contains additional information about a user.
No description provided by the author
RecentlyPlayedOptions describes options for the recently-played request.
No description provided by the author
Recommendations contains a list of recommended tracks based on seeds.
RecommendationSeed represents a recommendation seed after being processed by the Spotify API.
SavedAlbum provides info about an album saved to an user's account.
SavedAlbumPage contains SavedAlbums returned by the Web API.
SavedTrack provides info about a track saved to a user's account.
SavedTrackPage contains SavedTracks return by the Web API.
SearchResult contains the results of a call to Search.
Section represents a large variation in rhythm or timbre, e.g.
Seeds contains IDs of artists, genres and/or tracks to be used as seeds for recommendations.
Segment is characterized by it's perceptual onset and duration in seconds, loudness (dB), pitch and timbral content.
SimpleAlbum contains basic data about an album.
SimpleAlbumPage contains SimpleAlbums returned by the Web API.
SimpleArtist contains basic info about an artist.
SimplePlaylist contains basic info about a Spotify playlist.
SimplePlaylistPage contains SimplePlaylists returned by the Web API.
SimpleTrack contains basic info about a track.
SimpleTrackPage contains SimpleTracks returned by the Web API.
TrackAttributes contains various tuneable parameters that can be used for recommendations.
TrackToRemove specifies a track to be removed from a playlist.
User contains the basic, publicly available information about a Spotify user.

# Type aliases

AlbumType represents the type of an album.
ID is a base-62 identifier for an artist, track, album, etc.
Key represents a pitch using Pitch Class notation.
Mode indicates the modality (major or minor) of a track.
SearchType represents the type of a query used in the Search function.
URI identifies an artist, album, track, or category.