Class: Seo::AhrefsApiClient

Inherits:
Object
  • Object
show all
Defined in:
app/services/seo/ahrefs_api_client.rb

Overview

Client for Ahrefs API v3 using direct REST endpoints.
Fetches SEO metrics including traffic estimates, keywords, and positions.

Examples:

Basic usage

client = Seo::AhrefsApiClient.new
pages = client.top_pages(target: 'warmlyyours.com', limit: 100)

Get keywords for a specific URL

keywords = client.organic_keywords(url: 'https://www.warmlyyours.com/en-US/posts/example')

See Also:

Defined Under Namespace

Classes: Response

Constant Summary collapse

BASE_URL = 
'https://api.ahrefs.com/v3'

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil) ⇒ AhrefsApiClient

Returns a new instance of AhrefsApiClient.



28
29
30
31
32
33
 
# File 'app/services/seo/ahrefs_api_client.rb', line 28

def initialize(api_key: nil)
  @api_key = api_key || Heatwave::Configuration.fetch(:ahrefs, :api_key)
  raise 'Ahrefs API key not configured in credentials' if @api_key.blank?

  @connection = build_connection
end

Instance Method Details

#limits_and_usage ⇒ Response

Check API limits and usage

Returns:



83
84
85
 
# File 'app/services/seo/ahrefs_api_client.rb', line 83

def limits_and_usage
  request(:get, 'subscription-info/limits-and-usage', {})
end

#organic_keywords(target:, limit: 50) ⇒ Response

Get organic keywords for a specific URL

Parameters:

  • target (String) —

    URL to analyze

  • limit (Integer) (defaults to: 50) —

    Max keywords to return

Returns:



57
58
59
60
61
62
63
64
65
66
 
# File 'app/services/seo/ahrefs_api_client.rb', line 57

def organic_keywords(target:, limit: 50)
  params = {
    target: target,
    mode: 'exact',
    select: %w[keyword position sum_traffic volume traffic_share].join(','),
    limit: [limit, 1000].min
  }

  request(:get, 'site-explorer/organic-keywords', params)
end

#overview(target:, mode: 'subdomains') ⇒ Response

Get overview metrics for a target

Parameters:

  • target (String) —

    Domain or URL to analyze

  • mode (String) (defaults to: 'subdomains') —

    'subdomains', 'domain', 'exact', or 'prefix'

Returns:



72
73
74
75
76
77
78
79
 
# File 'app/services/seo/ahrefs_api_client.rb', line 72

def overview(target:, mode: 'subdomains')
  params = {
    target: target,
    mode: mode
  }

  request(:get, 'site-explorer/overview', params)
end

#top_pages(target:, mode: 'subdomains', limit: 100, offset: 0) ⇒ Response

Get top pages by estimated organic traffic

Parameters:

  • target (String) —

    Domain to analyze (e.g., 'warmlyyours.com')

  • mode (String) (defaults to: 'subdomains') —

    'subdomains' (default), 'domain', 'exact', or 'prefix'

  • limit (Integer) (defaults to: 100) —

    Max pages to return (default 100, max 1000)

  • offset (Integer) (defaults to: 0) —

    Pagination offset

Returns:



41
42
43
44
45
46
47
48
49
50
51
 
# File 'app/services/seo/ahrefs_api_client.rb', line 41

def top_pages(target:, mode: 'subdomains', limit: 100, offset: 0)
  params = {
    target: target,
    mode: mode,
    select: %w[url sum_traffic keywords top_keyword top_keyword_best_position value].join(','),
    limit: [limit, 1000].min,
    offset: offset
  }

  request(:get, 'site-explorer/top-pages', params)
end