Installation •
Usage Example •
Optional Parameters •
Spotify API Reference •
Recommendations
Laravel-Spotify makes working with the Spotify Web API a breeze. It provides straight forward methods for each endpoint and a fluent interface for optional parameters.
The package supports all Spotify Web API endpoints that are accessible with the Client Credentials Flow.
Install the package using Composer. The package will automatically register itself.
composer require aerni/laravel-spotify
Publish the config of the package.
php artisan vendor:publish --provider="Aerni\Spotify\Providers\SpotifyServiceProvider"
The following config will be published to config/spotify.php
.
return [
/*
|--------------------------------------------------------------------------
| Authentication
|--------------------------------------------------------------------------
|
| The Client ID and Client Secret of your Spotify App.
|
*/
'auth' => [
'client_id' => env('SPOTIFY_CLIENT_ID'),
'client_secret' => env('SPOTIFY_CLIENT_SECRET'),
],
/*
|--------------------------------------------------------------------------
| Default Config
|--------------------------------------------------------------------------
|
| You may provide a default config which will be used for every API request.
|
*/
'default_config' => [
'country' => env('SPOTIFY_DEFAULT_COUNTRY'),
'locale' => env('SPOTIFY_DEFAULT_LOCALE'),
'market' => env('SPOTIFY_DEFAULT_MARKET'),
],
];
Set the Client ID
and Client Secret
of your Spotify App in your .env
file.
SPOTIFY_CLIENT_ID=********************************
SPOTIFY_CLIENT_SECRET=********************************
Optionally, you may also specify default values for the country
, locale
and market
parameter. The defaults will be passed to every endpoint that supports the corresponding parameter.
SPOTIFY_DEFAULT_COUNTRY=US
SPOTIFY_DEFAULT_LOCALE=en_US
SPOTIFY_DEFAULT_MARKET=US
Import the package at the top of your file. All of the following examples use the Facade.
use Spotify;
Search for tracks with the name Closed on Sunday
.
Spotify::searchTracks('Closed on Sunday')->get();
Important: The get()
method acts as the final method of the fluent interface. Make sure to always call it last in the method chain to execute a request to the Spotify Web API.
You may pass optional parameters to your requests using the fluent interface provided by this package. A common use case is to set a limit
and offset
to your request.
Spotify::searchTracks('Closed on Sunday')->limit(50)->offset(50)->get();
Consult the Spotify Web API Reference Documentation to check which parameters are available to what endpoint.
// Limit the response to a particular geographical market.
Spotify::artistAlbums('artist_id')->country('US')->get();
// Filter the query using the provided string.
Spotify::playlist('playlist_id')->fields('description, uri')->get();
// Include any relevant content that is hosted externally.
Spotify::searchTracks('query')->includeExternal('audio')->get();
// Filter the response using the provided string.
Spotify::artistAlbums('artist_id')->includeGroups('album, single, appears_on, compilation')->get();
// Set the number of track objects to be returned.
Spotify::searchTracks('query')->limit(10)->get();
// Set the index of the first track to be returned.
Spotify::searchTracks('query')->offset(10)->get();
// Limit the response to a particular geographical market.
Spotify::searchAlbums('query')->market('US')->get();
// Limit the response to a particular language.
Spotify::category('category_id')->locale('en_US')->get();
// Get results based on a specific date and time.
Spotify::featuredPlaylists()->timestamp('2020-03-02T09:00:00')->get();
You may want to reset the default setting of country
, locale
or market
for a given request. You may do so by calling the corresponding parameter method with an empty argument.
// This will reset the default market to nothing.
Spotify::searchTracks('query')->market()->get();
Some API responses are wrapped in a top level object like artists
or tracks
. If you want to directly access the content of a given top level object, you may do so by passing its key as a string to the get()
method.
// This will return the content of the tracks object.
Spotify::searchTracks('query')->get('tracks');
Note: Any parameter that accepts multiple values can either receive a string with comma-separated values or an array of values.
// Pass a string with comma-separated values
Spotify::albums('album_id, album_id_2, album_id_3')->get();
// Or pass an array of values
Spotify::albums(['album_id', 'album_id_2', 'album_id_3'])->get();
Spotify Web API Reference on Albums
// Get an album by ID.
Spotify::album('album_id')->get();
// Get several albums by IDs. Provide a string or array of IDs.
Spotify::albums('album_id, album_id_2, album_id_3')->get();
// Get the tracks of an album by ID.
Spotify::albumTracks('album_id')->get();
Spotify Web API Reference on Artists
// Get an artist by ID.
Spotify::artist('artist_id')->get();
// Get several artists by IDs. Provide a string or array of IDs.
Spotify::artists('artist_id, artist_id_2, artist_id_3')->get();
// Get albums of an artist by ID.
Spotify::artistAlbums('artist_id')->get();
// Get the artist's top tracks by ID.
Spotify::artistTopTracks('artist_id')->get();
// Get an artist's related artists by ID.
Spotify::artistRelatedArtists('artist_id')->get();
Spotify Web API Reference on Browse
// Get a category by ID.
Spotify::category('category_id')->get();
// Get a category's playlists by ID.
Spotify::categoryPlaylists('category_id')->get();
// Get a list of categories.
Spotify::categories()->get();
// Get a list of featured playlists.
Spotify::featuredPlaylists()->get();
// Get a list of new releases.
Spotify::newReleases()->get();
// Get available genre seeds.
Spotify::availableGenreSeeds()->get();
// Get recommendations based on a seed.
Spotify::recommendations($seed)->get();
Spotify Web API Reference on Playlists
// Get a playlist by ID.
Spotify::playlist('playlist_id')->get();
// Get a playlist's tracks by ID.
Spotify::playlistTracks('playlist_id')->get();
// Get a playlist's cover image by ID.
Spotify::playlistCoverImage('playlist_id')->get();
Spotify Web API Reference on Search
// Search items by query. Provide a string or array to the second parameter.
Spotify::searchItems('query', 'album, artist, playlist, track')->get();
// Search albums by query.
Spotify::searchAlbums('query')->get();
// Search artists by query.
Spotify::searchArtists('query')->get();
// Search playlists by query.
Spotify::searchPlaylists('query')->get();
// Search tracks by query.
Spotify::searchTracks('query')->get();
Spotify Web API Reference on Tracks
// Get a track by ID.
Spotify::track('track_id')->get();
// Get several tracks by IDs. Provide a string or array of IDs.
Spotify::tracks('track_id, track_id_2, track_id_3')->get();
// Get audio analysis for a track by ID.
Spotify::audioAnalysisForTrack('track_id')->get();
// Get audio features for a track by ID.
Spotify::audioFeaturesForTrack('track_id')->get();
// Get audio features for several tracks by ID. Provide a string or array of IDs.
Spotify::audioFeaturesForTracks('track_id, track_id_2, track_id_3')->get();
You can get personalized tracks using the recommendations endpoint by seeding artists, genres and tracks along with a bunch of adjustable properties such as energy, key and danceability.
Import the SpotifySeed
class. All of the following examples use the Facade.
use SpotifySeed;
Build your personalized $seed
. You may chain as many methods as you want.
$seed = SpotifySeed::setGenres(['gospel', 'pop', 'funk'])
->setTargetValence(1.00)
->setSpeechiness(0.3, 0.9)
->setLiveness(0.3, 1.0);
Get your personalized tracks by passing the $seed
to the recommendations()
method.
Spotify::recommendations($seed)->get();
Note: Any parameter that accepts multiple values can either receive a string with comma-separated values or an array of values.
Add artists, genres and tracks to your seed:
// Add an artist by ID.
SpotifySeed::addArtist('artist_id');
// Add several artists by IDs. Provide a string or array of IDs.
SpotifySeed::addArtists('artist_id_1, artist_id_2, artist_id_3');
// Set artists by IDs. Provide a string or array of IDs. This overwrites previously added artists.
SpotifySeed::setArtists('artist_id_1, artist_id_2, artist_id_3');
// Add a genre by ID.
SpotifySeed::addGerne('gerne_id');
// Add several genres by IDs. Provide a string or array of IDs.
SpotifySeed::addGenres('gerne_id_1, gerne_id_2, gerne_id_3');
// Set gernes by IDs. Provide a string or array of IDs. This overwrites previously added genres.
SpotifySeed::setGenres('genre_id_1, genre_id_2, genre_id_3');
// Add a track by ID.
SpotifySeed::addTrack('track_id');
// Add several tracks by IDs. Provide a string or array of IDs.
SpotifySeed::addTracks('track_id_1, track_id_2, track_id_3');
// Set tracks by IDs. Provide a string or array of IDs. This overwrites previously added tracks.
SpotifySeed::setTracks('track_id_1, track_id_2, track_id_3');
Add tunable properties to your seed:
SpotifySeed::setAcousticness(float $min, float $max);
SpotifySeed::setTargetAcousticness(float $target);
SpotifySeed::setDanceability(float $min, float $max);
SpotifySeed::setTargetDanceability(float $target);
SpotifySeed::setDuration(int $min, int $max);
SpotifySeed::setTargetDuration(int $target);
SpotifySeed::setEnergy(float $min, float $max);
SpotifySeed::setTargetEnergy(float $target);
SpotifySeed::setInstrumentalness(float $min, float $max);
SpotifySeed::setTargetInstrumentalness(float $target);
SpotifySeed::setKey(int $min, int $max);
SpotifySeed::setTargetKey(int $target);
SpotifySeed::setLiveness(float $min, float $max);
SpotifySeed::setTargetLiveness(float $target);
SpotifySeed::setLoudness(float $min, float $max);
SpotifySeed::setTargetLoudness(float $target);
SpotifySeed::setMode(int $min, int $max);
SpotifySeed::setTargetMode(int $target);
SpotifySeed::setPopularity(float $min, float $max);
SpotifySeed::setTargetPopularity(float $target);
SpotifySeed::setSpeechiness(float $min, float $max);
SpotifySeed::setTargetSpeechiness(float $target);
SpotifySeed::setTempo(int $min, int $max);
SpotifySeed::setTargetTempo(int $target);
SpotifySeed::setTimeSignature(int $min, int $max);
SpotifySeed::setTargetTimeSignature(int $target);
SpotifySeed::setValence(float $min, float $max);
SpotifySeed::setTargetValence(float $target);
Run the tests like this:
vendor/bin/phpunit