Class: Api::Datadive::Client

Inherits:
Object
  • Object
show all
Defined in:
app/services/api/datadive/client.rb

Overview

Direct Faraday client for the DataDive Amazon product-research API v1.

Authenticates with the x-api-key header (see Heatwave::Configuration
key datadive => api_key). Each public method maps to one documented
endpoint and returns the parsed JSON body as a plain Hash — the API's
own response schema is the contract; see
https://developer.datadive.tools/docs#/v1. Non-2xx responses raise an
Error subclass (by status); transport errors are wrapped
as Error::ServerError.

Build instances via client rather than calling +new+
directly so the API key is resolved from credentials.

Examples:

client = Api::Datadive.client
client.niches(page_size: 50)               #=> { "data" => [...], "total" => 12, ... }
client.niche_competitors("z515cGOFg3")     #=> { "message" => "...", "data" => [...] }

See Also:

Constant Summary collapse

DEFAULT_API_URL = 
'https://api.datadive.tools'
TIMEOUT_SECONDS = 
30
OPEN_TIMEOUT_SECONDS = 
10
MAX_PAGE_SIZE =

DataDive caps page size at 50 (400 otherwise); clamp so callers can
pass an over-large value without tripping a BadRequest.

50

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, api_url: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String) —

    DataDive API key (sent as the x-api-key header)

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

    base URL; defaults to DEFAULT_API_URL



37
38
39
40
 
# File 'app/services/api/datadive/client.rb', line 37

def initialize(api_key:, api_url: nil)
  @api_key = api_key
  @api_url = api_url.presence || DEFAULT_API_URL
end

Instance Method Details

#asin_inventory(seller_id:, marketplace:, asin:) ⇒ Hash

GET /v1/sellers/sellerId/marketplaces/marketplace/asins/asin/inventory
— per-fulfillment-center sellable inventory for an ASIN on one of your
connected seller accounts. Includes FCs with availableStock: 0.

Parameters:

  • seller_id (String) —

    connected seller-account id

  • marketplace (String) —

    marketplace domain (e.g. "com", "co.uk", "de")

  • asin (String)

Returns:

  • (Hash) 


138
139
140
 
# File 'app/services/api/datadive/client.rb', line 138

def asin_inventory(seller_id:, marketplace:, asin:)
  get("/v1/sellers/#{esc(seller_id)}/marketplaces/#{esc(marketplace)}/asins/#{esc(asin)}/inventory")
end

#niche_competitors(niche_id) ⇒ Hash

GET /v1/niches/nicheId/competitors — Competitor list plus Niche
statistics: keyword stats, opportunity evaluation, and benchmark
medians, with key business metrics per competitor.

Parameters:

  • niche_id (String)

Returns:

  • (Hash) 


69
70
71
 
# File 'app/services/api/datadive/client.rb', line 69

def niche_competitors(niche_id)
  get("/v1/niches/#{esc(niche_id)}/competitors")
end

#niche_dive(dive_id) ⇒ Hash

GET /v1/niches/dives/diveId — status of an in-flight Niche Dive
(in_progress / success / error). Useful for polling a Dive that
was kicked off elsewhere.

Parameters:

  • dive_id (String)

Returns:

  • (Hash) 


126
127
128
 
# File 'app/services/api/datadive/client.rb', line 126

def niche_dive(dive_id)
  get("/v1/niches/dives/#{esc(dive_id)}")
end

#niche_keywords(niche_id) ⇒ Hash

GET /v1/niches/nicheId/keywords — the Master Keyword List: search
terms monitored for the Niche with search volume, relevancy, and
per-competitor organic/sponsored ranks.

Parameters:

  • niche_id (String)

Returns:

  • (Hash) 


59
60
61
 
# File 'app/services/api/datadive/client.rb', line 59

def niche_keywords(niche_id)
  get("/v1/niches/#{esc(niche_id)}/keywords")
end

#niche_ranking_juices(niche_id) ⇒ Hash

GET /v1/niches/nicheId/ranking-juices — Ranking Juice (DataDive's
proprietary metric for the factors driving search-ranking success) for
each competitor's listing, plus current vs. optimized listing scores.

Parameters:

  • niche_id (String)

Returns:

  • (Hash) 


79
80
81
 
# File 'app/services/api/datadive/client.rb', line 79

def niche_ranking_juices(niche_id)
  get("/v1/niches/#{esc(niche_id)}/ranking-juices")
end

#niche_roots(niche_id) ⇒ Hash

GET /v1/niches/nicheId/roots — keyword lexical roots extracted from
the Master Keyword List, with frequency and broad search volume.

Parameters:

  • niche_id (String)

Returns:

  • (Hash) 


88
89
90
 
# File 'app/services/api/datadive/client.rb', line 88

def niche_roots(niche_id)
  get("/v1/niches/#{esc(niche_id)}/roots")
end

#niches(current_page: 1, page_size: 20) ⇒ Hash

GET /v1/niches — paginated list of tracked Niches (market segments /
product categories). Each item carries the nicheId the per-niche
endpoints below require.

Parameters:

  • current_page (Integer) (defaults to: 1) —

    1-based page number

  • page_size (Integer) (defaults to: 20) —

    items per page (clamped to MAX_PAGE_SIZE)

Returns:

  • (Hash) —

    pagination envelope with a data array of Niche items



49
50
51
 
# File 'app/services/api/datadive/client.rb', line 49

def niches(current_page: 1, page_size: 20)
  get('/v1/niches', currentPage: current_page, pageSize: clamp_page_size(page_size))
end

#rank_radar_keywords(rank_radar_id, start_date:, end_date:) ⇒ Hash

GET /v1/niches/rank-radars/rankRadarId — historical keyword ranking
data for a Rank Radar within a date range (daily organic + impression
ranks per tracked keyword).

Parameters:

  • rank_radar_id (String)
  • start_date (String) —

    inclusive range start (YYYY-MM-DD)

  • end_date (String) —

    inclusive range end (YYYY-MM-DD)

Returns:

  • (Hash) 


116
117
118
 
# File 'app/services/api/datadive/client.rb', line 116

def rank_radar_keywords(rank_radar_id, start_date:, end_date:)
  get("/v1/niches/rank-radars/#{esc(rank_radar_id)}", startDate: start_date, endDate: end_date)
end

#rank_radars(niche_id: nil, status: nil, search_text: nil, current_page: 1, page_size: 20) ⇒ Hash

GET /v1/niches/rank-radars — paginated list of Rank Radars (keyword
ranking trackers for a specific ASIN within a Niche).

Parameters:

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

    filter to one Niche

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

    "ALL" or "PAUSED"

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

    free-text filter

  • current_page (Integer) (defaults to: 1)
  • page_size (Integer) (defaults to: 20) —

    clamped to MAX_PAGE_SIZE

Returns:

  • (Hash) —

    pagination envelope with a data array of Rank Radars



101
102
103
104
105
106
 
# File 'app/services/api/datadive/client.rb', line 101

def rank_radars(niche_id: nil, status: nil, search_text: nil, current_page: 1, page_size: 20)
  get('/v1/niches/rank-radars', {
    nicheId: niche_id, status: status, searchText: search_text,
    currentPage: current_page, pageSize: clamp_page_size(page_size)
  }.compact)
end