Crystalize is a Crystal shard that adds support for the Spotify API. It is usable, but doesn't cover most of the API and may not have a stable interface.

Programming language: Crystal
Tags: Third-party APIs     API     Spotify    
Latest version: v0.3.1-pre

Crystalize alternatives and similar shards

Based on the "Third-party APIs" category

Do you think we are missing an alternative of Crystalize or a related project?

Add another 'Third-party APIs' Shard


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

Crystalize is heavily WIP. It is usable, but doesn't cover most of the API and may not have a stable interface. It's not yet recommended to use Crystalize in important software. There is very little documentation.


  1. Add the dependency to your shard.yml:
       github: t1ra/crystalize
  1. Run shards install


require "crystalize"


To use Crystalize, you first have to instantise it:

client = Crystalize::Client.new(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 client:

album = client.get_album("3ogb5zqMrLtSbT4HAvQhPc") # Album ID

puts album.name # "Твой первый диск - моя кассета"
puts album.artists[0].name # "Tima Belorusskih"

Crystalize's API can be found at https://t1ra.github.io/crystalize, and Spotify's API reference can be found at https://developer.spotify.com/documentation/web-api/reference/. Using these, it shouldn't be difficult to thoroughly understand Crystalize.


  • Albums ✅
  • Artists ✅

Coming Soon

  • Browse
  • Playlists
  • Tracks
  • 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 (https://github.com/t1ra/crystalize/fork)
  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/auth.cr and add the following:

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

  def self.id

  def self.secret


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