| You and me |
|---|
| Spotify has a history of pushing considerable breaking changes to their API and documentation without prior notice. Additionally, Spotify is known for not responding to developers' inquiries. This can suddenly render development on top of their platform useless, reportedly putting university projects and job applications at risk. Be encouraged to share your feedback with Spotify on a platform of your choice. [1] [2] |
| Android Developers |
|---|
| You cannot use this library for Android app development. Have a look at adamint/spotify-web-api-kotlin, kaaes/spotify-web-api-android and Spotify's Android SDK and see why. |
This is a Java wrapper/client for the Spotify Web API.
The artifact is available through Maven Central via Sonatype. Or to use a snapshot of the latest commit you can use jitpack.io as described further down below.
The library requires Java 9 or later. It is an explicit Java module named se.michaelthelin.spotify, so on the module path add requires se.michaelthelin.spotify; to your module-info.java; on the classpath nothing is needed.
Latest official release:
<dependency>
<groupId>se.michaelthelin.spotify</groupId>
<artifactId>spotify-web-api-java</artifactId>
<version>10.1.0</version>
</dependency>Latest snapshot:
<dependency>
<groupId>com.github.spotify-web-api-java</groupId>
<artifactId>spotify-web-api-java</artifactId>
<version>main-SNAPSHOT</version>
</dependency>Latest official release:
implementation 'se.michaelthelin.spotify:spotify-web-api-java:10.1.0'Latest snapshot:
implementation 'com.github.spotify-web-api-java:spotify-web-api-java:main-SNAPSHOT'In order to use Jitpack you need to add their repository to your build:
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}See this project's Javadoc.
A huge thanks to c-schuhmann for his amazing work on the documentation!
Upgrading from an earlier major version? See the migration guide.
// For all requests an access token is needed
SpotifyApi spotifyApi = new SpotifyApi.Builder()
.setAccessToken("taHZ2SdB-bPA3FsK3D7ZN5npZS47cMy-IEySVEGttOhXmqaVAIo0ESvTCLjLBifhHOHOIuhFUKPW1WMDP7w6dj3MAZdWT8CLI2MkZaXbYLTeoDvXesf2eeiLYPBGdx8tIwQJKgV8XdnzH_DONk")
.build();
// Create a request object with the optional parameter "market"
final GetSomethingRequest getSomethingRequest = spotifyApi.getSomething("qKRpDADUKrFeKhFHDMdfcu")
.market(CountryCode.SE)
.build();
void getSomething_Sync() {
try {
// Execute the request synchronous
final Something something = getSomethingRequest.execute();
// Print something's name
System.out.println("Name: " + something.getName());
} catch (Exception e) {
System.out.println("Something went wrong!\n" + e.getMessage());
}
}
void getSomething_Async() {
try {
// Execute the request asynchronous
final CompletableFuture<Something> somethingFuture = getSomethingRequest.executeAsync();
// Do other things...
// Wait for the request to complete
final Something something = somethingFuture.get();
// Print something's name
System.out.println("Name: " + something.getName());
} catch (Exception e) {
System.out.println("Something went wrong!\n" + e.getMessage());
}
}Please see Spotify's authorization guide too!
For authorization requests the API object requires at least to have your application's client ID and client secret set as its properties. When using the authorization code flow, the application's redirect URI is required too. Those properties will then be automatically used by functions that depend on them.
SpotifyApi spotifyApi = new SpotifyApi.Builder()
.setClientId("<your_client_id>")
.setClientSecret("<your_client_secret>")
.setRedirectUri("<your_redirect_uri>")
.build();There are three ways to retrieving an access token:
Use the client credentials flow when the requests don't require permission from a specific user. This flow doesn't return a refresh token and is useful for simple requests, like fetching albums or searching for tracks.
Example: ClientCredentialsExample.java
Using the authorization code flow to retrieve an access token is necessary if the requests are bound to a specific user. Using this flow returns a refresh token, which can be used to renew the access token before it expires. This is how it works:
-
The authorization code flow requires a code, which is part of the
redirectUri's query parameters when the user has opened a custom URL in a browser and authorized the application.Example: AuthorizationCodeUriExample.java
-
When the code has been retrieved, it can be used in another request to get an access token as well as a refresh token.
Example: AuthorizationCodeExample.java
-
Now, the refresh token in turn can be used in a loop to retrieve new access and refresh tokens.
Example: AuthorizationCodeRefreshExample.java
When you've fetched an access and refresh token, you have to add them to your API properties for automatic usage in requests. The implementer has to handle the access token's expiration.
spotifyApi.setAccessToken("<your_access_token>");
spotifyApi.setRefreshToken("<your_refresh_token>");The authorization code flow with PKCE is quite like the Authorization Code Flow except that no client secret is necessary (therefore, it is a good option for mobile and desktop applications). Instead, your application should generate a code verifier and a code challenge before each authentication request.
The code verifier is a cryptographically random string between 43 and 128 characters in length. It can contain letters, digits, underscores, periods, hyphens, or tildes. To generate the code challenge, your app should hash the code verifier using the SHA256 algorithm. Then, base64url encode the hash that you generated.
This flow provides your app with an access token which can be refreshed, too. The steps are similar as above:
-
The authorization code flow with PKCE requires a code, which is part of the
redirectUri's query parameters when the user has opened a custom URL in a browser and authorized the application. The code challenge is supplied to this request as a query parameter.Example: AuthorizationCodePKCEUriExample.java
-
When the code has been retrieved, it can be used in another request to get an access token as well as a refresh token. The code verifier is supplied to this request a query parameter.
Example: AuthorizationCodePKCEExample.java
-
Now, the refresh token in turn can be used in a loop to retrieve new access and refresh tokens.
When you have fetched an access and refresh token, you have to add them to your API properties for automatic usage in requests. The implementer must handle the access token's expiration. The refresh token can be exchanged for an access token only once, after which it becomes invalid.
Endpoints that Spotify deprecated are marked with
⚠️ . They keep working for clients whose credentials still reach them and none of them are scheduled for removal. See the@deprecatedJavadoc tag on the corresponding request class for the recommended alternative.
-
Albums
-
Artists
-
Audiobooks
-
Browsing & Discovery
-
Chapters
-
Episodes
-
Library (Unified Save/Remove/Check API)
-
Personalization
-
Player
-
Playlists
- Get a Playlist
- Get Current User's Playlists
⚠️ Get a User's Playlists- Create a Playlist
⚠️ Create a Playlist for a User- Get a Playlist's Items
- Get a Playlist Cover Image
- Add Items to a Playlist
- Remove Items from a Playlist
- Update Playlist Details
- Reorder Playlist Items
- Replace Playlist Items
- Upload Playlist Cover Image
- Legacy
/trackspath
-
Search
- Search for Item
- Simplified (Direct Type Search)
-
Shows
-
Tracks
-
User's Profile & Following
Please ask questions about using the library in help networks like
StackOverflow with the tag spotify-web-api-java,
where they get quick and helpful answers.
Issues are for bug reports and for questions about this project's source code.
Contributions are very welcome. CONTRIBUTING.md describes how the code is organized, how to build and test it, and what a pull request needs to be accepted.