Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zmb3/spotify

A Go wrapper for the Spotify Web API
https://github.com/zmb3/spotify

Last synced: 25 days ago
JSON representation

A Go wrapper for the Spotify Web API

Awesome Lists containing this project

README

        

Spotify
=======

[![GoDoc](https://godoc.org/github.com/zmb3/spotify?status.svg)](http://godoc.org/github.com/zmb3/spotify)

This is a Go wrapper for working with Spotify's
[Web API](https://developer.spotify.com/web-api/).

It aims to support every task listed in the Web API Endpoint Reference,
located [here](https://developer.spotify.com/web-api/endpoint-reference/).

By using this library you agree to Spotify's
[Developer Terms of Use](https://developer.spotify.com/developer-terms-of-use/).

## Installation

To install the library, simply

`go get github.com/zmb3/spotify/v2`

## 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.

````Go
// 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 := spotifyauth.New(spotifyauth.WithRedirectURL(redirectURL), spotifyauth.WithScopes(spotifyauth.ScopeUserReadPrivate))

// 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(r.Context(), state, r)
if err != nil {
http.Error(w, "Couldn't get token", http.StatusNotFound)
return
}
// create a client using the specified token
client := spotify.New(auth.Client(r.Context(), 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

### 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](https://developer.spotify.com/documentation/web-api/concepts/rate-limits).

## API Examples

Examples of the API can be found in the [examples](examples) directory.

You may find tools such as [Spotify's Web API Console](https://developer.spotify.com/web-api/console/)
or [Rapid API](https://rapidapi.com/package/SpotifyPublicAPI/functions?utm_source=SpotifyGitHub&utm_medium=button&utm_content=Vendor_GitHub)
valuable for experimenting with the API.

### Missing data in responses

It's extremely common that when there is no market information available in your
request, that the Spotify API will simply return null for details about a track
or episode.

This typically occurs when you are just using an application's auth token, and
aren't impersonating a user via oauth. As when you are using a token associated
with a user, the user's market seems to be extracted from their profile and
used when producing the response.