Songstats Ruby SDK

Official Ruby client for the Songstats Enterprise API.

📦 RubyGems: https://rubygems.org/gems/songstats-ruby-sdk
📚 API Documentation: https://developers.stats.company/songstats
🔑 API Key Access: Please contact api@songstats.com

Requirements

Ruby >= 3.0

Installation

Add to your Gemfile:

gem "songstats-ruby-sdk"

Then install:

bundle install

Or install directly via RubyGems:

gem install songstats-ruby-sdk

Quick Start

require "songstats_sdk"

client = SongstatsSDK::Client.new(
  api_key: ENV["SONGSTATS_API_KEY"]
)

# API status
status = client.info.status

# Track information
track = client.tracks.info(
  songstats_track_id: "abcd1234"
)

# Artist statistics
artist_stats = client.artists.stats(
  songstats_artist_id: "abcd1234",
  source: "spotify"
)

Authentication

All requests include your API key in the apikey header.

You can generate an API key in your Songstats Enterprise dashboard.

We recommend storing your key securely in environment variables:

export SONGSTATS_API_KEY=your_key_here

Available Resource Clients

client.info
client.tracks
client.artists
client.collaborators
client.labels

Info endpoints:

client.info.sources -> /sources
client.info.status -> /status
client.info.definitions -> /definitions

Error Handling

begin
  client.tracks.info(songstats_track_id: "invalid")
rescue SongstatsSDK::SongstatsAPIError => e
  puts "API error: #{e.message}"
rescue SongstatsSDK::SongstatsTransportError => e
  puts "Transport error: #{e.message}"
end

Development

To work on the SDK locally:

git clone https://github.com/songstats/songstats-ruby-sdk.git
cd songstats-ruby-sdk
bundle install
bundle exec rake test

Versioning

This SDK follows Semantic Versioning (SemVer).

License

MIT