The Spotify API for Crystal

Crystalize Logo

Crystalize is a Crystal library that adds support for the Spotify API.

Crystalize is still a WIP. It is usable, but doesn't cover all of the API and may not have a stable interface.


  1. Add the dependency to your shard.yml:

        github: t1ra/crystalize
  2. Run shards install


require "crystalize"


To use Crystalize, you first have to set credentials:

Crystalize.authenticate(id: "your-id", secret: "your-secret")

To get an ID and secret, create a new client using the Spotify Dashboard.

From there, you can send requests via the associated module:

album = Crystalize::Album.get("3ogb5zqMrLtSbT4HAvQhPc").not_nil! eq "Твой первый диск - моя кассета" eq "Tima Belorusskih"

Crystalize's API can be found at, and Spotify's API reference can be found at Using these, it shouldn't be difficult to thoroughly understand Crystalize.


  • Albums ✅
  • Artists ✅
  • Browse ✅
  • Tracks ✅

Coming Soon

  • Playlists (Partial?)
  • Users Profile (Partial?)

Long-Term Goals

  • Follow
  • Personalization
  • Player
  • Search

Why the long-term goals?

The long-term goal endpoints require authentication from a user, which, generally, requires a lot more setup to get than bot authentication. Until all of the bot-available endpoints are ready, there's no plan to implement user-based endpoints.

Users Profile can be partially implemented because some endpoints require user authentication (/v1/me), while others (/v1/users/{user_id}) don't.


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
    • If you're fixing a bug, confirm your changes fix the issue and ensure the library passes crystal spec
    • If you're adding a feature, write a new test. In the case of a new endpoint, make sure that the test at least ensures the endpoint is demarshalled correctly.
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


If you simply pull the repo and run crystal spec, tests will fail because Crystalize doesn't have any credentials to use. To add your own, create spec/ and add the following:

module Auth
  @@id = "YOUR-ID"
  @@secret = "YOUR-SECRET"


  def self.secret


Replacing @@id and @@secret with your own.

Github statistic:
  • 3
  • 0
  • 0
  • 1
  • 0
  • 12 days ago


MIT License