Socialstats Ruby SDK

Official Ruby client for the Socialstats Enterprise API.

RubyGems: https://rubygems.org/gems/socialstats-ruby-sdk
API Documentation: https://docs.socialstats.com
API Key Access: Please contact api@socialstats.com

Requirements

  • Ruby >= 3.2

Installation

Add to your Gemfile:

gem "socialstats-ruby-sdk"

Then install:

bundle install

Or install directly via RubyGems:

gem install socialstats-ruby-sdk

Quick Start

require "socialstats_sdk"

client = SocialstatsSDK::Client.new(
  api_key: ENV["SOCIALSTATS_API_KEY"]
)

# API status
status = client.info.status

# Creator information
creator = client.creators.info(
  socialstats_creator_id: "d3rvjgk2"
)

# Creator statistics
creator_stats = client.creators.stats(
  socialstats_creator_id: "d3rvjgk2",
  source: "instagram"
)

# Post statistics
post_stats = client.posts.stats(
  socialstats_creator_id: "d3rvjgk2",
  source_id: "tiktok",
  post_id: "7654234001833610518"
)

Authentication

All requests include your API key in the apikey header.

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

We recommend storing your key securely in environment variables:

export SOCIALSTATS_API_KEY=your_key_here

Available Resource Clients

  • client.info
  • client.creators
  • client.posts

Info endpoints:

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

Creator endpoints:

  • client.creators.info(...) -> /creators/info
  • client.creators.stats(...) -> /creators/stats
  • client.creators.historic_stats(...) -> /creators/historic_stats
  • client.creators.audience(...) -> /creators/audience
  • client.creators.audience_details(country_code: ..., ...) -> /creators/audience/details
  • client.creators.activities(...) -> /creators/activities
  • client.creators.content(...) -> /creators/content
  • client.creators.top_posts(...) -> /creators/top_posts
  • client.creators.search(q: ..., ...) -> /creators/search
  • client.creators.add_link_request(link: ..., ...) -> /creators/link_request
  • client.creators.remove_link_request(link: ..., ...) -> /creators/link_request

Post endpoints:

  • client.posts.stats(...) -> /posts/stats
  • client.posts.historic_stats(...) -> /posts/historic_stats

Error Handling

begin
  client.creators.info(socialstats_creator_id: "invalid")
rescue SocialstatsSDK::SocialstatsAPIError => e
  puts "API error: #{e.message}"
rescue SocialstatsSDK::SocialstatsTransportError => e
  puts "Transport error: #{e.message}"
end

Development

To work on the SDK locally:

git clone https://github.com/songstats/socialstats-ruby-sdk.git
cd socialstats-ruby-sdk
bundle install

Versioning

This SDK follows Semantic Versioning (SemVer).

License

MIT