Class: Semrush::Report
Overview
Report Class
Most of these methods take a hash parameter that may contain the following keys :
-
:db (ex: :db => “us”)
-
:api_key (ex: :api_key => ‘gt97s6d4a6w’)
-
:limit (ex: :limit => 2000)
-
:offset (ex: :offset => 5)
-
:export_columns (ex: :export_columns => “Dn,Rk”)
Constant Summary collapse
- DBS =
“us” - for Google.com, “uk” - for Google.co.uk, “ru” - for Google.ru, “de” for Google.de, “fr” for Google.fr, “es” for Google.es, “it” for Google.it Beta, “br” for Google.com.br Beta, “au” for Google.com.au Beta, etc
[:us, :uk, :ca, :ru, :de, :fr, :es, :it, :br, :au, :ar, :be, :ch, :dk, :fi, :hk, :ie, :il, :mx, :nl, :no, :pl, :se, :sg, :tr, :in, :nz]
- REPORT_TYPES =
[:domain_rank, :domain_organic, :domain_adwords, :domain_organic_organic, :domain_adwords_adwords, :domain_organic_adwords, :domain_adwords_organic, :domain_adwords_historical, :phrase_this, :phrase_organic, :phrase_related, :phrase_adwords_historical, :phrase_fullsearch, :phrase_kdi, :url_organic, :url_adwords]
- REQUEST_TYPES =
[:domain, :phrase, :url]
Class Method Summary collapse
-
.domain(domain, params = {}) ⇒ Object
Initializes a report for a specific domain.
-
.phrase(phrase, params = {}) ⇒ Object
Initializes a report for a specific phrase (or keyword).
-
.remaining_quota(params = {}) ⇒ Object
Initializes & calls a report for the remaining API units Takes a hash parameter that may contain the following keys : * :api_key (ex: :api_key => ‘gt97s6d4a6w’).
-
.url(url, params = {}) ⇒ Object
Initializes a report for a specific domain.
Instance Method Summary collapse
-
#adwords(params = {}) ⇒ Object
AdWords report Can be called for a domain or a URL.
-
#basics(params = {}) ⇒ Object
Main report.
-
#competitors_adwords(params = {}) ⇒ Object
Competitors in AdWords search report Default columns: * Dn - Sites competing with this site in AdWords, sorted by the number of common keywords * Np - Number of common keywords in AdWords that these two sites buy * Ad - Keywords that this site has in TOP20 Google AdWords * At - Estimated number of visitors coming from AdWords (per month) * Ac - Estimated expenses of the site for the advertising in AdWords (per month) * Or - Keywords that this site has in TOP20 Google Organic results.
-
#competitors_adwords_by_organic(params = {}) ⇒ Object
Potential ad/traffic sellers report Default columns: * Dn - Sites that get into Google TOP20 for keyword queries that analyzed site buy in AdWords * Np - The number of keywords which this site has in search results next to the AdWords ads of the analyzed site * Or - Keywords that this site has in TOP20 Google Organic results * Ot - Estimated number of visitors coming from the first 20 Google search results (per month) * Oc - Estimated cost of purchasing the same number of visitors * Ad - Keywords that this site has in TOP20 Google AdWords.
-
#competitors_organic(params = {}) ⇒ Object
Competitors in organic search report Default columns: * Dn - Sites competing with this site in Google search results, sorted by the number of common keywords * Np - The number of keywords on which the site is displayed in search results next to the analyzed site * Or - Keywords that this site has in TOP20 Google Organic results * Ot - Estimated number of visitors coming from the first 20 Google search results (per month) * Oc - Estimated cost of purchasing the same number of visitors * Ad - Keywords that this site has in TOP20 Google AdWords.
-
#competitors_organic_by_adwords(params = {}) ⇒ Object
Potential ad/traffic buyers report Default columns: * Dn - The list of sites that buys ads in AdWords for those keywords that the domain under analyzis has within Google TOP20 * Np - Number of keywords on which ads of this particular site appear and the analyzed site gets within Google TOP20 * Ad - Keywords that this site has in TOP20 Google AdWords * At - Estimated number of visitors coming from AdWords (per month) * Ac - Estimated expenses of the site for the advertising in AdWords (per month) * Or - Keywords that this site has in TOP20 Google Organic results.
-
#fullsearch(params = {}) ⇒ Object
Fullsearch keyword report Default columns: * Ph - The search query which the site has within the first 20 Google search results * Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google * Cp - Average price of a click on the AdWords ad for this search query, in U.S.
-
#history_adwords(params = {}) ⇒ Object
Ads history for domain or phrase Default columns:.
-
#initialize(params = {}) ⇒ Report
constructor
A new instance of Report.
-
#kdi(params = {}) ⇒ Object
Keyword Difficulty report Usage: > report = Semrush::Report.phrase(phrases.join(‘;’), database: ‘us’, limit: 100).kdi Report constants an array of hashes: * keyword - phrase for KDI * keyword_difficulty_index - KDI for phrase.
- #keywords_adwords(params = {}) ⇒ Object
- #keywords_organic(params = {}) ⇒ Object
-
#method_missing(method, *args) ⇒ Object
Tries to make the api call for the report called as method (see samples on www.semrush.com/api.html).
-
#organic(params = {}) ⇒ Object
Organic report Can be called for a domain or a URL.
-
#related(params = {}) ⇒ Object
Related keyword report Default columns: * Ph - The search query which the site has within the first 20 Google search results * Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google * Cp - Average price of a click on the AdWords ad for this search query, in U.S.
Methods inherited from Base
Constructor Details
#initialize(params = {}) ⇒ Report
Returns a new instance of Report.
28 29 30 31 32 |
# File 'lib/semrush/report.rb', line 28 def initialize params = {} @parameters = params @request_types = REQUEST_TYPES @api_report_url = API_REPORT_URL end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *args) ⇒ Object
Tries to make the api call for the report called as method (see samples on www.semrush.com/api.html). Allows calls like:
-
Semrush::Report.new.domain_rank(:request_type => :domain, :request => ‘thedomain.com’)
-
Semrush::Report.new.domain_organic_organic(:request_type => :domain, :request => ‘thedomain.com’)
-
Semrush::Report.new.phrase_related(:request_type => :phrase, :request => ‘the+phrase’)
-
Semrush::Report.new.phrase_fullsearch(:request_type => :phrase, :request => ‘the+phrase’)
22 23 24 25 26 |
# File 'lib/semrush/report.rb', line 22 def method_missing(method, *args) return super unless REPORT_TYPES.include?(method) && args.first.is_a?(Hash) request args.first.merge(:report_type => method) end |
Class Method Details
.domain(domain, params = {}) ⇒ Object
Initializes a report for a specific domain. Takes a hash parameter that may contain the following keys :
-
:db (ex: :db => “us”)
-
:api_key (ex: :api_key => ‘gt97s6d4a6w’)
-
:limit (ex: :limit => “”)
-
:offset (ex: :offset => “”)
-
:export_columns (ex: :export_columns => “”)
41 42 43 |
# File 'lib/semrush/report.rb', line 41 def self.domain domain, params = {} self.new(params.merge(:request_type => :domain, :request => domain)) end |
.phrase(phrase, params = {}) ⇒ Object
Initializes a report for a specific phrase (or keyword). Takes a hash parameter that may contain the following keys :
-
:db (ex: :db => “us”)
-
:api_key (ex: :api_key => ‘gt97s6d4a6w’)
-
:limit (ex: :limit => “”)
-
:offset (ex: :offset => “”)
-
:export_columns (ex: :export_columns => “”)
52 53 54 |
# File 'lib/semrush/report.rb', line 52 def self.phrase phrase, params = {} self.new(params.merge(:request_type => :phrase, :request => phrase)) end |
.remaining_quota(params = {}) ⇒ Object
Initializes & calls a report for the remaining API units Takes a hash parameter that may contain the following keys :
-
:api_key (ex: :api_key => ‘gt97s6d4a6w’)
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 |
# File 'lib/semrush/report.rb', line 70 def self.remaining_quota params = {} @remaining_quota_url ||= begin temp_url = "#{API_UNITS_URL}" #do not copy the constant as is or else the constant would be modified !! params = {:api_key => Semrush.api_key}.merge(params) params.each {|k, v| if v.blank? temp_url.gsub!(/&[^&=]+=%#{k.to_s}%/i, '') else temp_url.gsub!("%#{k.to_s.upcase}%", CGI.escape(v.to_s).gsub('&', '%26')) end } temp_url end puts "[Semrush query] URL: #{@remaining_quota_url}" if Semrush.debug url = URI.parse(@remaining_quota_url) response = Net::HTTP.start(url.host, url.port, :use_ssl => true) {|http| http.get(url.path+"?"+url.query) } body = response.body if body.blank? && response['location'].present? && response['location']!=@remaining_quota_url @remaining_quota_url = URI.join("http://#{url.host}", response['location']).to_s self.remaining_quota params else body.force_encoding("utf-8") body.starts_with?("ERROR") ? error(body) : body.to_i end end |
.url(url, params = {}) ⇒ Object
Initializes a report for a specific domain. Takes a hash parameter that may contain the following keys :
-
:db (ex: :db => “us”)
-
:api_key (ex: :api_key => ‘gt97s6d4a6w’)
-
:limit (ex: :limit => “”)
-
:offset (ex: :offset => “”)
-
:export_columns (ex: :export_columns => “”)
63 64 65 |
# File 'lib/semrush/report.rb', line 63 def self.url url, params = {} self.new(params.merge(:request_type => :url, :request => url)) end |
Instance Method Details
#adwords(params = {}) ⇒ Object
AdWords report Can be called for a domain or a URL. Default columns for a domain:
-
Ph - Search query which the site buys in AdWords in Google
-
Po - The position of the ad at the time of data collection
-
Pp - The position of the ad at the time of previous data collection
-
Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google
-
Cp - Average price of a click on the AdWords ad for this search query, in U.S. dollars
-
Vu - Display URL. This is the URL displayed on your ad to identify your site to users.
-
Tr - The ratio of the number of visitors coming to the site from this ad to all visitors coming from Google AdWords
-
Tc - The ratio of site’s expenditures on this particular ad to it’s expenditures on all AdWords ads in general
-
Co - Competition of advertisers in AdWords for that term, the higher is the number - the higher is the competition
-
Nr - The number of search results - how many pages does Google know for this query
-
Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
-
Ur - The destination URL is the exact URL within your website that you want to send users to from your ad.
Default columns for a URL:
-
Ph - Search query that the URL has within the first 20 Google Organic or AdWords results
-
Po - The position of this URL for this keyword in Organic or AdWords results
-
Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google
-
Cp - Average price of a click on the AdWords ad for this search query, in U.S. dollars
-
Co - Competition of advertisers in AdWords for that term, the higher is the number - the higher is the competition
-
Tr - The ratio of the number of visitors coming to the URL from this keyword to all visitors coming
-
Tc - The ratio of the estimated cost of buying the same number of visitors for this search query to the estimated cost of purchasing the same number of targeted visitors coming to this URL
-
Nr - The number of search results - how many pages does Google know for this query
-
Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
183 184 185 |
# File 'lib/semrush/report.rb', line 183 def adwords params = {} url? ? request(params.merge(:report_type => :url_adwords)) : request(params.merge(:report_type => :domain_adwords)) end |
#basics(params = {}) ⇒ Object
Main report. Available for a phrase or a domain. Default columns for a domain:
-
Dn - A site name.
-
Rk - Rating of sites by the number of visitors coming from the first 20 Google search results
-
Or - Keywords that this site has in TOP20 Google Organic results
-
Ot - Estimated number of visitors coming from the first 20 Google search results (per month)
-
Oc - Estimated cost of purchasing the same number of visitors
-
Ad - Keywords that this site has in TOP20 Google AdWords
-
At - Estimated number of visitors coming from AdWords (per month)
-
Ac - Estimated expenses of the site for the advertising in AdWords (per month)
Default columns for a phrase:
-
Ph - The search query which the site has within the first 20 Google search results
-
Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google
-
Cp - Average price of a click on the AdWords ad for this search query, in U.S. dollars
-
Co - Competition of advertisers in AdWords for that term, the higher is the number - the higher is the competition
-
Nr - The number of search results - how many pages does Google know for this query
115 116 117 |
# File 'lib/semrush/report.rb', line 115 def basics params = {} domain? ? request(params.merge(:report_type => :domain_rank)) : request(params.merge(:report_type => :phrase_this)) end |
#competitors_adwords(params = {}) ⇒ Object
Competitors in AdWords search report Default columns:
-
Dn - Sites competing with this site in AdWords, sorted by the number of common keywords
-
Np - Number of common keywords in AdWords that these two sites buy
-
Ad - Keywords that this site has in TOP20 Google AdWords
-
At - Estimated number of visitors coming from AdWords (per month)
-
Ac - Estimated expenses of the site for the advertising in AdWords (per month)
-
Or - Keywords that this site has in TOP20 Google Organic results
211 212 213 |
# File 'lib/semrush/report.rb', line 211 def competitors_adwords params = {} request(params.merge(:report_type => :domain_adwords_adwords)) end |
#competitors_adwords_by_organic(params = {}) ⇒ Object
Potential ad/traffic sellers report Default columns:
-
Dn - Sites that get into Google TOP20 for keyword queries that analyzed site buy in AdWords
-
Np - The number of keywords which this site has in search results next to the AdWords ads of the analyzed site
-
Or - Keywords that this site has in TOP20 Google Organic results
-
Ot - Estimated number of visitors coming from the first 20 Google search results (per month)
-
Oc - Estimated cost of purchasing the same number of visitors
-
Ad - Keywords that this site has in TOP20 Google AdWords
235 236 237 |
# File 'lib/semrush/report.rb', line 235 def competitors_adwords_by_organic params = {} request(params.merge(:report_type => :domain_adwords_organic)) end |
#competitors_organic(params = {}) ⇒ Object
Competitors in organic search report Default columns:
-
Dn - Sites competing with this site in Google search results, sorted by the number of common keywords
-
Np - The number of keywords on which the site is displayed in search results next to the analyzed site
-
Or - Keywords that this site has in TOP20 Google Organic results
-
Ot - Estimated number of visitors coming from the first 20 Google search results (per month)
-
Oc - Estimated cost of purchasing the same number of visitors
-
Ad - Keywords that this site has in TOP20 Google AdWords
199 200 201 |
# File 'lib/semrush/report.rb', line 199 def competitors_organic params = {} request(params.merge(:report_type => :domain_organic_organic)) end |
#competitors_organic_by_adwords(params = {}) ⇒ Object
Potential ad/traffic buyers report Default columns:
-
Dn - The list of sites that buys ads in AdWords for those keywords that the domain under analyzis has within Google TOP20
-
Np - Number of keywords on which ads of this particular site appear and the analyzed site gets within Google TOP20
-
Ad - Keywords that this site has in TOP20 Google AdWords
-
At - Estimated number of visitors coming from AdWords (per month)
-
Ac - Estimated expenses of the site for the advertising in AdWords (per month)
-
Or - Keywords that this site has in TOP20 Google Organic results
223 224 225 |
# File 'lib/semrush/report.rb', line 223 def competitors_organic_by_adwords params = {} request(params.merge(:report_type => :domain_organic_adwords)) end |
#fullsearch(params = {}) ⇒ Object
Fullsearch keyword report Default columns:
-
Ph - The search query which the site has within the first 20 Google search results
-
Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google
-
Cp - Average price of a click on the AdWords ad for this search query, in U.S. dollars
-
Co - Competition of advertisers in AdWords for that term, the higher is the number - the higher is the competition
-
Nr - The number of search results - how many pages does Google know for this query
-
Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
265 266 267 |
# File 'lib/semrush/report.rb', line 265 def fullsearch params = {} request(params.merge(:report_type => :phrase_fullsearch)) end |
#history_adwords(params = {}) ⇒ Object
Ads history for domain or phrase Default columns:
241 242 243 |
# File 'lib/semrush/report.rb', line 241 def history_adwords params = {} domain? ? request(params.merge(:report_type => :domain_adwords_historical)) : request(params.merge(:report_type => :phrase_adwords_historical)) end |
#kdi(params = {}) ⇒ Object
Keyword Difficulty report Usage: > report = Semrush::Report.phrase(phrases.join(‘;’), database: ‘us’, limit: 100).kdi Report constants an array of hashes:
-
keyword - phrase for KDI
-
keyword_difficulty_index - KDI for phrase
275 276 277 |
# File 'lib/semrush/report.rb', line 275 def kdi params = {} request(params.merge(:report_type => :phrase_kdi)) end |
#keywords_adwords(params = {}) ⇒ Object
186 187 188 189 |
# File 'lib/semrush/report.rb', line 186 def keywords_adwords params = {} warn "[DEPRECATION] `keywords_adwords` is deprecated. Please use `adwords` instead." adwords(params) end |
#keywords_organic(params = {}) ⇒ Object
153 154 155 156 |
# File 'lib/semrush/report.rb', line 153 def keywords_organic params = {} warn "[DEPRECATION] `keywords_organic` is deprecated. Please use `organic` instead." organic(params) end |
#organic(params = {}) ⇒ Object
Organic report Can be called for a domain or a URL. Default columns for a domain:
-
Ph - The search query which the site has within the first 20 Google search results
-
Po - The position of the site for the search query in Google, at the moment of data collection
-
Pp - The position of the site for the search query in Google, for the previous data collection
-
Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google
-
Cp - Average price of a click on the AdWords ad for this search query, in U.S. dollars
-
Ur - URL of a page of the site which is displayed in search results for this query (landing page)
-
Tr - The ratio of the number of visitors coming to the site from this search request to all visitors coming from Google search results
-
Tc - The ratio of the estimated cost of buying the same number of visitors for this search query to the estimated cost of purchasing the same number of targeted visitors coming to this site from Google search results
-
Co - Competition of advertisers in AdWords for that term, the higher is the number - the higher is the competition
-
Nr - The number of search results - how many pages does Google know for this query
-
Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
Default columns for a URL:
-
Ph - Search query that the URL has within the first 20 Google Organic or AdWords results
-
Po - The position of this URL for this keyword in Organic or AdWords results
-
Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google
-
Cp - Average price of a click on the AdWords ad for this search query, in U.S. dollars
-
Co - Competition of advertisers in AdWords for that term, the higher is the number - the higher is the competition
-
Tr - The ratio of the number of visitors coming to the URL from this keyword to all visitors coming
-
Tc - The ratio of the estimated cost of buying the same number of visitors for this search query to the estimated cost of purchasing the same number of targeted visitors coming to this URL
-
Nr - The number of search results - how many pages does Google know for this query
-
Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
Default columns for a phrase:
-
Dn - A site name
-
Ur - Target URL
146 147 148 149 150 151 152 |
# File 'lib/semrush/report.rb', line 146 def organic params = {} case when url? then request(params.merge(:report_type => :url_organic)) when phrase? then request(params.merge(:report_type => :phrase_organic)) else request(params.merge(:report_type => :domain_organic)) end end |
#related(params = {}) ⇒ Object
Related keyword report Default columns:
-
Ph - The search query which the site has within the first 20 Google search results
-
Nq - Average number of queries of this keyword in a month, for the corresponding local version of Google
-
Cp - Average price of a click on the AdWords ad for this search query, in U.S. dollars
-
Co - Competition of advertisers in AdWords for that term, the higher is the number - the higher is the competition
-
Nr - The number of search results - how many pages does Google know for this query
-
Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
253 254 255 |
# File 'lib/semrush/report.rb', line 253 def params = {} request(params.merge(:report_type => :phrase_related)) end |