Class: ShopsavvyDataApi::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/shopsavvy_data_api/client.rb

Overview

Official Ruby client for ShopSavvy Data API

Provides access to product data, pricing information, and price history across thousands of retailers and millions of products.

Examples:

Basic usage

client = ShopsavvyDataApi::Client.new(api_key: "ss_live_your_api_key_here")
product = client.get_product_details("012345678901")
puts product.data.name

Using configuration

config = ShopsavvyDataApi::Configuration.new(
  api_key: "ss_live_your_api_key_here",
  timeout: 60
)
client = ShopsavvyDataApi::Client.new(config)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config = nil, api_key: nil, base_url: nil, timeout: nil) ⇒ Client

Initialize a new client

Parameters:

  • config (Configuration, Hash) (defaults to: nil) —

    Configuration object or hash with :api_key

  • api_key (String) (defaults to: nil) —

    API key (alternative to config parameter)

  • base_url (String) (defaults to: nil) —

    Base URL for API (default: api.shopsavvy.com/v1)

  • timeout (Integer) (defaults to: nil) —

    Request timeout in seconds (default: 30)



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/shopsavvy_data_api/client.rb', line 33

def initialize(config = nil, api_key: nil, base_url: nil, timeout: nil)
  @config = if config.is_a?(Configuration)
              config
            elsif config.is_a?(Hash)
              Configuration.new(**config)
            elsif api_key
              Configuration.new(
                api_key: api_key,
                base_url: base_url || "https://api.shopsavvy.com/v1",
                timeout: timeout || 30
              )
            else
              raise ConfigurationError, "Either config or api_key must be provided"
            end

  @connection = build_connection
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



25
26
27
 
# File 'lib/shopsavvy_data_api/client.rb', line 25

def config
  @config
end

Instance Method Details

#get_current_offers(identifier, retailer: nil, format: nil) ⇒ APIResponse<Array<Offer>>

Get current offers for a product

Examples:

offers = client.get_current_offers("012345678901")
offers.data.each { |offer| puts "#{offer.retailer}: $#{offer.price}" }

Parameters:

  • identifier (String) —

    Product identifier

  • retailer (String, nil) (defaults to: nil) —

    Optional retailer to filter by

  • format (String, nil) (defaults to: nil) —

    Response format (‘json’ or ‘csv’)

Returns:



95
96
97
98
99
100
101
102
 
# File 'lib/shopsavvy_data_api/client.rb', line 95

def get_current_offers(identifier, retailer: nil, format: nil)
  params = { identifier: identifier }
  params[:retailer] = retailer if retailer
  params[:format] = format if format

  response = make_request(:get, "/products/offers", params: params)
  APIResponse.new(response, data_class: Offer)
end

#get_current_offers_batch(identifiers, retailer: nil, format: nil) ⇒ APIResponse<Hash<String, Array<Offer>>>

Get current offers for multiple products

Parameters:

  • identifiers (Array<String>) —

    Array of product identifiers

  • retailer (String, nil) (defaults to: nil) —

    Optional retailer to filter by

  • format (String, nil) (defaults to: nil) —

    Response format (‘json’ or ‘csv’)

Returns:

  • (APIResponse<Hash<String, Array<Offer>>>) —

    Hash mapping identifiers to their offers



110
111
112
113
114
115
116
117
 
# File 'lib/shopsavvy_data_api/client.rb', line 110

def get_current_offers_batch(identifiers, retailer: nil, format: nil)
  params = { identifiers: identifiers.join(",") }
  params[:retailer] = retailer if retailer
  params[:format] = format if format

  response = make_request(:get, "/products/offers", params: params)
  APIResponse.new(response, data_class: Offer)
end

#get_price_history(identifier, start_date, end_date, retailer: nil, format: nil) ⇒ APIResponse<Array<OfferWithHistory>>

Get price history for a product

Examples:

history = client.get_price_history("012345678901", "2024-01-01", "2024-01-31")
history.data.each do |offer|
  puts "#{offer.retailer}: #{offer.price_history.length} price points"
end

Parameters:

  • identifier (String) —

    Product identifier

  • start_date (String) —

    Start date (YYYY-MM-DD format)

  • end_date (String) —

    End date (YYYY-MM-DD format)

  • retailer (String, nil) (defaults to: nil) —

    Optional retailer to filter by

  • format (String, nil) (defaults to: nil) —

    Response format (‘json’ or ‘csv’)

Returns:



133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/shopsavvy_data_api/client.rb', line 133

def get_price_history(identifier, start_date, end_date, retailer: nil, format: nil)
  params = {
    identifier: identifier,
    start_date: start_date,
    end_date: end_date
  }
  params[:retailer] = retailer if retailer
  params[:format] = format if format

  response = make_request(:get, "/products/history", params: params)
  APIResponse.new(response, data_class: OfferWithHistory)
end

#get_product_details(identifier, format: nil) ⇒ APIResponse<ProductDetails>

Look up product details by identifier

Examples:

product = client.get_product_details("012345678901")
puts product.data.name

Parameters:

  • identifier (String) —

    Product identifier (barcode, ASIN, URL, model number, or ShopSavvy product ID)

  • format (String, nil) (defaults to: nil) —

    Response format (‘json’ or ‘csv’)

Returns:



60
61
62
63
64
65
66
 
# File 'lib/shopsavvy_data_api/client.rb', line 60

def get_product_details(identifier, format: nil)
  params = { identifier: identifier }
  params[:format] = format if format

  response = make_request(:get, "/products/details", params: params)
  APIResponse.new(response, data_class: ProductDetails)
end

#get_product_details_batch(identifiers, format: nil) ⇒ APIResponse<Array<ProductDetails>>

Look up details for multiple products

Examples:

products = client.get_product_details_batch(["012345678901", "B08N5WRWNW"])
products.data.each { |product| puts product.name }

Parameters:

  • identifiers (Array<String>) —

    Array of product identifiers

  • format (String, nil) (defaults to: nil) —

    Response format (‘json’ or ‘csv’)

Returns:



77
78
79
80
81
82
83
 
# File 'lib/shopsavvy_data_api/client.rb', line 77

def get_product_details_batch(identifiers, format: nil)
  params = { identifiers: identifiers.join(",") }
  params[:format] = format if format

  response = make_request(:get, "/products/details", params: params)
  APIResponse.new(response, data_class: ProductDetails)
end

#get_scheduled_products ⇒ APIResponse<Array<ScheduledProduct>>

Get all scheduled products

Examples:

scheduled = client.get_scheduled_products
puts "Monitoring #{scheduled.data.length} products"

Returns:



191
192
193
194
 
# File 'lib/shopsavvy_data_api/client.rb', line 191

def get_scheduled_products
  response = make_request(:get, "/products/scheduled")
  APIResponse.new(response, data_class: ScheduledProduct)
end

#get_usage ⇒ APIResponse<UsageInfo>

Get API usage information

Examples:

usage = client.get_usage
puts "Credits remaining: #{usage.data.credits_remaining}"

Returns:



229
230
231
232
 
# File 'lib/shopsavvy_data_api/client.rb', line 229

def get_usage
  response = make_request(:get, "/usage")
  APIResponse.new(response, data_class: UsageInfo)
end

#remove_product_from_schedule(identifier) ⇒ APIResponse<Hash>

Remove product from monitoring schedule

Examples:

result = client.remove_product_from_schedule("012345678901")
puts "Removed: #{result.data['removed']}"

Parameters:

  • identifier (String) —

    Product identifier to remove

Returns:



204
205
206
207
208
209
 
# File 'lib/shopsavvy_data_api/client.rb', line 204

def remove_product_from_schedule(identifier)
  body = { identifier: identifier }

  response = make_request(:delete, "/products/schedule", body: body)
  APIResponse.new(response)
end

#remove_products_from_schedule(identifiers) ⇒ APIResponse<Array<Hash>>

Remove multiple products from monitoring schedule

Parameters:

  • identifiers (Array<String>) —

    Array of product identifiers to remove

Returns:

  • (APIResponse<Array<Hash>>) —

    Removal confirmation for all products



215
216
217
218
219
220
 
# File 'lib/shopsavvy_data_api/client.rb', line 215

def remove_products_from_schedule(identifiers)
  body = { identifiers: identifiers.join(",") }

  response = make_request(:delete, "/products/schedule", body: body)
  APIResponse.new(response)
end

#schedule_product_monitoring(identifier, frequency, retailer: nil) ⇒ APIResponse<Hash>

Schedule product monitoring

Examples:

result = client.schedule_product_monitoring("012345678901", "daily")
puts "Scheduled: #{result.data['scheduled']}"

Parameters:

  • identifier (String) —

    Product identifier

  • frequency (String) —

    How often to refresh (‘hourly’, ‘daily’, ‘weekly’)

  • retailer (String, nil) (defaults to: nil) —

    Optional retailer to monitor

Returns:



156
157
158
159
160
161
162
163
164
165
 
# File 'lib/shopsavvy_data_api/client.rb', line 156

def schedule_product_monitoring(identifier, frequency, retailer: nil)
  body = {
    identifier: identifier,
    frequency: frequency
  }
  body[:retailer] = retailer if retailer

  response = make_request(:post, "/products/schedule", body: body)
  APIResponse.new(response)
end

#schedule_product_monitoring_batch(identifiers, frequency, retailer: nil) ⇒ APIResponse<Array<Hash>>

Schedule monitoring for multiple products

Parameters:

  • identifiers (Array<String>) —

    Array of product identifiers

  • frequency (String) —

    How often to refresh (‘hourly’, ‘daily’, ‘weekly’)

  • retailer (String, nil) (defaults to: nil) —

    Optional retailer to monitor

Returns:

  • (APIResponse<Array<Hash>>) —

    Scheduling confirmation for all products



173
174
175
176
177
178
179
180
181
182
 
# File 'lib/shopsavvy_data_api/client.rb', line 173

def schedule_product_monitoring_batch(identifiers, frequency, retailer: nil)
  body = {
    identifiers: identifiers.join(","),
    frequency: frequency
  }
  body[:retailer] = retailer if retailer

  response = make_request(:post, "/products/schedule", body: body)
  APIResponse.new(response)
end