semrush 3.0.22 → 3.0.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5a6729e8c55a3233d0e1c4fcc5a3be7db9032882ee2d1dd1cb5ef82e6da1964
-  data.tar.gz: 8f19c166d3c034a04f881982d212b6898da414bfb11eff001db7b94ce4ce2e7c
+  metadata.gz: 10cb05ec42e77de2e49cc3c374e330478cf5f09666f62519c2ce8cb3045cfbf3
+  data.tar.gz: ffb593df0c6ff6c41a28958d1912ce0ffb4d90243c5cac50f54a5f0ba683c505
 SHA512:
-  metadata.gz: 2c073868cfc50523b71cc419fb4b25b8e7687dbf3605a1f9bf9882377033476fc056eee20fc3425786ae380d4dc45379276598759221f616b11950e6bba77fd3
-  data.tar.gz: fffe74c3225467ff853000f43321fe41373dbcefb2f454e5551452d04e46f12b8e5fec7290395fab27ee4297925ba987f14f70ab6c4c9d3451d2c46243159d1c
+  metadata.gz: fd0ea77440b7c8fac7eb81406847a1e09277f13e144527d56c79d9f4b3372f4cef504f5f6880178694e5300636467ef192bc3bfe00b088997f0023f8c46bccd3
+  data.tar.gz: af1fdf963f5ec2244462b9c5e12f0382adb275356604d87eec894c057fa7cea052c371b9d2f6a85faa799c0aaebd3beade463c27677675d554bb8c9ae6744533

data/README.rdoc

@@ -4,8 +4,8 @@ Semrush is a ruby wrapper for the SEMRush API.
 
 == Requirements
 
-- Ruby 1.9 or 2.x
-- ActiveSupport (tested with ActiveSupport 3.1 & 3.2)
+- Ruby 1.9, 2.x, 3.1<
+- ActiveSupport
 
 == Installation
 
@@ -70,6 +70,9 @@ or
   report = Semrush::Report.domain("seobook.com")
   data = report.basics(:db => 'us', :limit => 100)
 
+or
+  analytics = Semrush::Analytics.backlinks_refdomains("seobook.com")
+
 You will find more information about these parameters at http://www.semrush.com/api.html
 
 == Reports
@@ -101,6 +104,14 @@ For more information about the report types, please read http://www.semrush.com/
 
 == ChangeLog
 
+=== 3.0.24, 2023-05-15
+
+* Added Analytics class for the new Analytics API, not covered all the reports yet
+
+=== 3.0.23, 2020-03-19
+
+* Add New Zealand 'nz' to allowed databases (countries)
+
 === 3.0.22, 2019-06-14
 
 * Add India to the list of allowed countries

data/lib/semrush/analytics.rb

@@ -0,0 +1,94 @@
+module Semrush
+  # = Analytics Class
+  # Most of these methods take a hash parameter that may contain the following keys :
+  # There is no db filter for analytics api but you can use :display_filter to filter the results,
+  #   example: :display_filter => "+|country||us" will only return results from the US.
+  # See https://developer.semrush.com/api/v3/analytics/basic-docs/
+  # * :api_key (ex: :api_key => 'gt97s6d4a6w')
+  # * :limit (ex: :limit => 2000)
+  # * :offset (ex: :offset => 5)
+  # * :export_columns (ex: :export_columns => "Dn,Rk")
+  class Analytics < Base
+    ANALYTIC_TYPES = [:backlinks_refdomains]
+    REQUEST_TYPES = [:root_domain, :domain, :url]
+
+    def initialize params = {}
+      @parameters = params
+      @target_types = REQUEST_TYPES
+      @api_report_url = API_ANALYTICS_URL
+    end
+
+    # Get lists domains pointing to the queried domain, root domain, or URL.
+    # * :api_key (ex: :api_key => 'gt97s6d4a6w')
+    # * :limit (ex: :limit => "")
+    # * :offset (ex: :offset => "")
+    # * :target_type (ex: :target_type => "") One of `REQUEST_TYPES`
+    # * :export_columns (ex: :export_columns => "")
+    # * :display_filter one or many of "zone, country, ip, newdomain, lostdomain, category"
+    # See: https://developer.semrush.com/api/v3/analytics/backlinks/#reffering_domains
+    def self.backlinks_refdomains(domain, params = {})
+      export_columns = params.delete(:export_columns).presence ||
+        "domain_ascore,domain,backlinks_num,ip,country,first_seen,last_seen"
+
+      self.new(params.merge(:report_type => :backlinks_refdomains, :target => domain,
+                            :export_columns => export_columns))
+          .request
+    end
+
+    # Compare your and your competitors' backlink profiles and link-building progress.
+    # * :api_key (ex: :api_key => 'gt97s6d4a6w')
+    # * :targets (ex: :targets => ["domain1.com", "domain2.com"]) Array of domains to compare
+    # * :target_types (ex: :target_type => ["root_domain", "root_domain"]) Array to match with corresponding targets index
+    # * :export_columns (ex: :export_columns => ""), available columns: "target,target_type,ascore,backlinks_num,domains_num,ips_num,follows_num,nofollows_num,texts_num,images_num,forms_num,frames_num"
+    #
+    # * Return array of data
+    # @see https://developer.semrush.com/api/v3/analytics/backlinks/#batch_comparason
+    # @see https://www.semrush.com/batch/report/ for UI demo
+    def self.backlinks_comparison(targets, target_types, params = {})
+      target_types.each do |target_type|
+        raise Exception::BadArgument.new(self, "One of `target_types` is not valid: #{target_type}") unless REQUEST_TYPES.include?(target_type.to_sym)
+      end
+
+      raise Exception::BadArgument.new(self, "`targets` and `target_types` must be the same size") unless targets.size == target_types.size
+
+      export_columns = params.delete(:export_columns).presence ||
+        "target,target_type,ascore,backlinks_num,domains_num,ips_num,follows_num,nofollows_num,texts_num,images_num,forms_num,frames_num"
+      # Have to add target and target_type to params to cleaup API_ANALYTICS_URL (in #request v.blank? check)
+      self.new(params.merge(:report_type => :backlinks_comparison, :targets => targets, :target_types => target_types,
+                            :export_columns => export_columns,
+                            ))
+          .request
+    end
+
+    private
+
+    # All parameters:
+    # * report_type - type of the report
+    # * api_key - user identification key, you can find it in your profile on the Semrush site
+    # * target_type - type of the request.
+    # * target - your domain/url
+    # * limit - number of results returned
+    # * offset - says to skip that many results before beginning to return results to you
+    # * export_columns - list of column names, separated by coma. You may list just the column names you need in an order you need.
+    # * display_sort - a sorting as a String eg: 'am_asc' or 'am_desc'(read http://www.semrush.com/api)
+    # * display_filter - list of filters separated by "|" (maximum number - 25). A filter consists of <sign>|<field>|<operation>|<value> (read http://www.semrush.com/api)
+    #
+    # more details in http://www.semrush.com/api.html
+    def validate_parameters params = {}
+      params.symbolize_keys!
+      params.delete(:report_type) unless ANALYTIC_TYPES.include?(params[:report_type].try(:to_sym))
+      params.delete(:target_type) unless @target_types.include?(params[:target_type].try(:to_sym)) unless params[:targets]
+      @parameters = {:api_key => Semrush.api_key, :limit => "", :offset => "", :export_columns => "",
+                     :target => "", :target_type => "", :targets => "", :target_types => "",
+                     :display_sort => "", :display_filter => "", :display_date => ""}.merge(@parameters).merge(params)
+      # When(if) we will have another method that use `targets` as an Array(like backlinks_comparison) improve this
+      # and move validations from backlinks_comparison to here
+      unless @parameters[:targets]
+        raise Semrush::Exception::Nolimit.new(self, "The limit parameter is missing: a limit is required.") unless @parameters[:limit].present? && @parameters[:limit].to_i>0
+        raise Semrush::Exception::BadArgument.new(self, "Target parameter is missing: Domain name, URL.") unless @parameters[:target].present?
+        raise Semrush::Exception::BadArgument.new(self, "Bad report_type: #{@parameters[:report_type]}") unless ANALYTIC_TYPES.include?(@parameters[:report_type].try(:to_sym))
+        raise Semrush::Exception::BadArgument.new(self, "Bad target_type: #{@parameters[:target_type]}") unless @target_types.include?(@parameters[:target_type].try(:to_sym))
+      end
+    end
+  end
+end

data/lib/semrush/base.rb

@@ -0,0 +1,78 @@
+module Semrush
+  # = Base Class for all Semrush API classes
+  class Base
+    def request params = {}
+      validate_parameters params
+      temp_url = "#{@api_report_url}" #do not copy the constant as is or else the constant would be modified !!
+      @parameters.each {|k, v|
+        if v.blank?
+          temp_url.gsub!(/&[^&=]+=%#{k.to_s}%/i, '')
+        elsif k.to_sym==:display_filter
+          temp_url.gsub!("%#{k.to_s.upcase}%", CGI.escape(v.to_s).gsub('&', '%26').gsub('+', '%2B'))
+        elsif v.is_a?(Array)
+          # remove placeholder with value into query string of array of values
+          temp_url.gsub!("#{k}=%#{k.to_s.upcase}%", v.to_query(k.to_s))
+        else
+          temp_url.gsub!("%#{k.to_s.upcase}%", CGI.escape(v.to_s).gsub('&', '%26'))
+        end
+      }
+      puts "[Semrush query] URL: #{temp_url}" if Semrush.debug
+      url = URI.parse(temp_url)
+      Semrush.before.call(@parameters.merge(:url => url))
+      response = Net::HTTP.start(url.host, url.port, :use_ssl => true) {|http|
+        http.get(url.path+"?"+url.query)
+      }.body rescue "ERROR :: RESPONSE ERROR (-1)" # Make this error up
+      response.force_encoding("utf-8")
+      output = response.starts_with?("ERROR") ? error(response) : parse(response)
+      Semrush.after.call(@parameters.merge(:url => url), output)
+      output
+    end
+
+    # Format and raise an error
+    def error(text = "")
+      e = /ERROR\s(\d+)\s::\s(.*)/.match(text) || {}
+      name = (e[2] || "UnknownError").titleize
+      code = e[1] || -1
+      error_class = name.gsub(/\s/, "")
+
+      if error_class == "NothingFound"
+        []
+      else
+        begin
+          raise Semrush::Exception.const_get(error_class).new(self, "#{name} (#{code})")
+        rescue
+          raise Semrush::Exception::Base.new(self, "#{name} (#{code}) *** error_class=#{error_class} not implemented ***")
+        end
+      end
+    end
+
+    def parse(text = "")
+      return [] if text.empty?
+      csv = CSV.parse(text.to_s, :col_sep => ";")
+      format_key = lambda do |k|
+        r = {
+          /\s/ => "_",
+          /[|\.|\)|\(]/ => "",
+          /%/ => "percent",
+          /\*/ => "times"
+        }
+        k = k.to_s.downcase
+        r.each_pair {|pattern, replace| k.gsub!(pattern, replace) }
+        k.to_sym
+      end
+
+      # (thanks http://snippets.dzone.com/posts/show/3899)
+      keys = csv.shift.map(&format_key)
+      string_data = csv.map {|row| row.map {|cell| cell.to_s } }
+      string_data.map {|row| Hash[*keys.zip(row).flatten] }
+    rescue CSV::MalformedCSVError => csvife
+      tries ||= 0
+      if (tries += 1) < 3
+        retry
+      else
+        raise CSV::MalformedCSVError.new("Bad format for CSV: #{text.inspect}").tap{|e|
+          e.set_backtrace(csvife.backtrace)}
+      end
+    end
+  end
+end

data/lib/semrush/report.rb

@@ -6,14 +6,13 @@ module Semrush
   # * :limit (ex: :limit => 2000)
   # * :offset (ex: :offset => 5)
   # * :export_columns (ex: :export_columns => "Dn,Rk")
-  class Report
-    DBS = [: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] #"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
+  class Report < Base
+    DBS = [: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] #"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
     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]
 
-
     # Tries to make the api call for the report called as method (see samples on http://www.semrush.com/api.html).
     # Allows calls like:
     # * Semrush::Report.new.domain_rank(:request_type => :domain, :request => 'thedomain.com')
@@ -22,11 +21,14 @@ module Semrush
     # * Semrush::Report.new.phrase_fullsearch(:request_type => :phrase, :request => 'the+phrase')
     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
 
     def initialize params = {}
       @parameters = params
+      @request_types = REQUEST_TYPES
+      @api_report_url = API_REPORT_URL
     end
 
     # Initializes a report for a specific domain.
@@ -39,6 +41,7 @@ module Semrush
     def self.domain domain, params = {}
       self.new(params.merge(:request_type => :domain, :request => domain))
     end
+
     # Initializes a report for a specific phrase (or keyword).
     # Takes a hash parameter that may contain the following keys :
     # * :db (ex: :db => "us")
@@ -49,6 +52,7 @@ module Semrush
     def self.phrase phrase, params = {}
       self.new(params.merge(:request_type => :phrase, :request => phrase))
     end
+
     # Initializes a report for a specific domain.
     # Takes a hash parameter that may contain the following keys :
     # * :db (ex: :db => "us")
@@ -71,7 +75,7 @@ module Semrush
           if v.blank?
             temp_url.gsub!(/&[^&=]+=%#{k.to_s}%/i, '')
           else
-            temp_url.gsub!("%#{k.to_s.upcase}%", URI.escape(v.to_s).gsub('&', '%26'))
+            temp_url.gsub!("%#{k.to_s.upcase}%", CGI.escape(v.to_s).gsub('&', '%26'))
           end
         }
         temp_url
@@ -261,7 +265,7 @@ module Semrush
     def fullsearch params = {}
       request(params.merge(:report_type => :phrase_fullsearch))
     end
-    
+
     # Keyword Difficulty report
     # Usage:
     # > report = Semrush::Report.phrase(phrases.join(';'), database: 'us', limit: 100).kdi
@@ -274,30 +278,6 @@ module Semrush
 
     private
 
-    def request params = {}
-      validate_parameters params
-      temp_url = "#{API_REPORT_URL}" #do not copy the constant as is or else the constant would be modified !!
-      @parameters.each {|k, v|
-        if v.blank?
-          temp_url.gsub!(/&[^&=]+=%#{k.to_s}%/i, '')
-        elsif k.to_sym==:display_filter
-          temp_url.gsub!("%#{k.to_s.upcase}%", URI.escape(v.to_s).gsub('&', '%26').gsub('+', '%2B'))
-        else
-          temp_url.gsub!("%#{k.to_s.upcase}%", URI.escape(v.to_s).gsub('&', '%26'))
-        end
-      }
-      puts "[Semrush query] URL: #{temp_url}" if Semrush.debug
-      url = URI.parse(temp_url)
-      Semrush.before.call(@parameters.merge(:url => url))
-      response = Net::HTTP.start(url.host, url.port, :use_ssl => true) {|http|
-        http.get(url.path+"?"+url.query)
-      }.body rescue "ERROR :: RESPONSE ERROR (-1)" # Make this error up
-      response.force_encoding("utf-8")
-      output = response.starts_with?("ERROR") ? error(response) : parse(response)
-      Semrush.after.call(@parameters.merge(:url => url), output)
-      output
-    end
-
     # All parameters:
     # * db - requested database
     # * report_type - type of the report
@@ -324,64 +304,16 @@ module Semrush
       raise Semrush::Exception::BadArgument.new(self, "Bad request type: #{@parameters[:request_type]}") unless REQUEST_TYPES.include?(@parameters[:request_type].try(:to_sym))
     end
 
-    # Format and raise an error
-    def error(text = "")
-      e = /ERROR\s(\d+)\s::\s(.*)/.match(text) || {}
-      name = (e[2] || "UnknownError").titleize
-      code = e[1] || -1
-      error_class = name.gsub(/\s/, "")
-
-      if error_class == "NothingFound"
-        []
-      else
-        begin
-          raise Semrush::Exception.const_get(error_class).new(self, "#{name} (#{code})")
-        rescue
-          raise Semrush::Exception::Base.new(self, "#{name} (#{code}) *** error_class=#{error_class} not implemented ***")
-        end
-      end
-    end
-
-    def parse(text = "")
-      return [] if text.empty?
-      csv = CSV.parse(text.to_s, :col_sep => ";")
-      data = {}
-      format_key = lambda do |k|
-        r = {
-          /\s/ => "_",
-          /[|\.|\)|\(]/ => "",
-          /%/ => "percent",
-          /\*/ => "times"
-        }
-        k = k.to_s.downcase
-        r.each_pair {|pattern, replace| k.gsub!(pattern, replace) }
-        k.to_sym
-      end
-
-      # (thanks http://snippets.dzone.com/posts/show/3899)
-      keys = csv.shift.map(&format_key)
-      string_data = csv.map {|row| row.map {|cell| cell.to_s } }
-      string_data.map {|row| Hash[*keys.zip(row).flatten] }
-    rescue CSV::MalformedCSVError => csvife
-      tries ||= 0
-      if (tries += 1) < 3
-        retry
-      else
-        raise CSV::MalformedCSVError.new("Bad format for CSV: #{text.inspect}").tap{|e|
-          e.set_backtrace(csvife.backtrace)}
-      end
-    end
-
     def domain?
-      @parameters[:request_type].present? && REQUEST_TYPES.include?(@parameters[:request_type].to_sym) && @parameters[:request_type].to_sym==:domain
+      @parameters[:request_type].present? && @request_types.include?(@parameters[:request_type].to_sym) && @parameters[:request_type].to_sym==:domain
     end
+
     def url?
-      @parameters[:request_type].present? && REQUEST_TYPES.include?(@parameters[:request_type].to_sym) && @parameters[:request_type].to_sym==:url
+      @parameters[:request_type].present? && @request_types.include?(@parameters[:request_type].to_sym) && @parameters[:request_type].to_sym==:url
     end
+
     def phrase?
-      @parameters[:request_type].present? && REQUEST_TYPES.include?(@parameters[:request_type].to_sym) && @parameters[:request_type].to_sym==:phrase
+      @parameters[:request_type].present? && @request_types.include?(@parameters[:request_type].to_sym) && @parameters[:request_type].to_sym==:phrase
     end
-
-
   end
 end

data/lib/semrush/version.rb

@@ -1,3 +1,3 @@
 module Semrush
-  VERSION = "3.0.22" # we want to follow the API version: for API 3.0, the gem will be version 3.0.x
+  VERSION = "3.0.25" # we want to follow the API version: for API 3.0, the gem will be version 3.0.x
 end

data/lib/semrush.rb

@@ -5,10 +5,14 @@ require 'csv'
 require 'rubygems'
 require 'active_support/all'
 require 'semrush/exception'
+require 'semrush/base'
 require 'semrush/report'
+require 'semrush/analytics'
 
 module Semrush
+  # See https://developer.semrush.com/api/v3/analytics/basic-docs/
   API_REPORT_URL = "https://api.semrush.com/?type=%REPORT_TYPE%&%REQUEST_TYPE%=%REQUEST%&key=%API_KEY%&display_limit=%LIMIT%&display_offset=%OFFSET%&export=api&database=%DB%&export_columns=%EXPORT_COLUMNS%&display_sort=%DISPLAY_SORT%&display_filter=%DISPLAY_FILTER%&display_date=%DISPLAY_DATE%"
+  API_ANALYTICS_URL = "https://api.semrush.com/analytics/v1?type=%REPORT_TYPE%&targets=%TARGETS%&target_types=%TARGET_TYPES%&target=%TARGET%&target_type=%TARGET_TYPE%&key=%API_KEY%&display_limit=%LIMIT%&display_offset=%OFFSET%&export_columns=%EXPORT_COLUMNS%&display_sort=%DISPLAY_SORT%&display_filter=%DISPLAY_FILTER%"
   API_UNITS_URL = "https://www.semrush.com/users/countapiunits.html?key=%API_KEY%"
   mattr_accessor :api_key
   @@api_key = ""

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: semrush
 version: !ruby/object:Gem::Version
-  version: 3.0.22
+  version: 3.0.25
 platform: ruby
 authors:
 - arambert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-14 00:00:00.000000000 Z
+date: 2023-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 6.1.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 6.1.5
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.11.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.11.0
 description: This gem is a ruby client for the SemRush API.
 email:
 - adrien@rambert.me
@@ -63,6 +63,8 @@ files:
 - README.rdoc
 - Rakefile
 - lib/semrush.rb
+- lib/semrush/analytics.rb
+- lib/semrush/base.rb
 - lib/semrush/exception.rb
 - lib/semrush/exception/api_access_disabled.rb
 - lib/semrush/exception/api_report_type_disabled.rb
@@ -93,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: This gem is a ruby client for the SemRush API.