# Ruby SDK

> Install the shopsavvy-sdk gem to look up products, current offers and price history from Ruby scripts and Rails apps, including an initializer example.

*Source: https://shopsavvy.com/data/documentation/sdk-ruby* · Part of the [ShopSavvy Data API documentation](https://shopsavvy.com/data/documentation.md)

---

Our official Ruby SDK provides a convenient way to interact with the ShopSavvy Data API from Ruby applications with idiomatic Ruby patterns and comprehensive documentation.

- [View on GitHub](https://github.com/shopsavvy/sdk-ruby)
- [View on RubyGems](https://rubygems.org/gems/shopsavvy-sdk)

## Installation

```bash
gem install shopsavvy-sdk

# Or add to your Gemfile:
gem 'shopsavvy-sdk'
```

## Basic Usage

```ruby
require 'shopsavvy_data_api'

# Initialize the client
client = ShopsavvyDataApi.new(api_key: "ss_live_your_api_key_here")

# Look up a product by barcode
product = client.get_product_details("012345678901")
puts product.data.name

# Get current prices from all retailers
offers = client.get_current_offers("012345678901")
offers.data.each do |offer|
  puts "#{offer.retailer}: $#{offer.price}"
end

# Get price history
history = client.get_price_history(
  "012345678901",
  "2024-01-01",
  "2024-01-31"
)
```

## Features

- Idiomatic Ruby patterns and conventions
- Comprehensive YARD documentation
- Automatic retry logic with exponential backoff
- Convenient model methods and helpers
- Rails integration examples
- Ruby 2.7+ compatibility

## Rails Integration

```ruby
# config/initializers/shopsavvy.rb
Rails.application.config.shopsavvy_client = ShopsavvyDataApi.new(
  api_key: Rails.application.credentials.shopsavvy_api_key
)

# In your models/controllers
client = Rails.application.config.shopsavvy_client
product = client.get_product_details(params[:barcode])
```

## Error Handling

```ruby
begin
  client = ShopsavvyDataApi.new(api_key: "ss_live_your_api_key_here")
  product = client.get_product_details("invalid-identifier")
rescue ShopsavvyDataApi::NotFoundError => e
  puts "Product not found"
rescue ShopsavvyDataApi::AuthenticationError => e
  puts "Invalid API key"
rescue ShopsavvyDataApi::RateLimitError => e
  puts "Rate limit exceeded"
rescue ShopsavvyDataApi::APIError => e
  puts "API error: #{e.message}"
end
```