├── VERSION ├── requirements.txt ├── python_semrush ├── tests │ ├── __init__.py │ ├── response.txt │ └── test_semrush.py ├── errors.py ├── __init__.py └── semrush.py ├── requirements ├── default.txt ├── pkgutils.txt ├── test.txt └── README.rst ├── setup.cfg ├── scripts └── removepyc.sh ├── .gitmodules ├── tox.ini ├── MANIFEST.in ├── CHANGELOG.md ├── .gitignore ├── LICENSE ├── README.rst └── setup.py /VERSION: -------------------------------------------------------------------------------- 1 | 0.1.3 2 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | requests==2.8.1 -------------------------------------------------------------------------------- /python_semrush/tests/__init__.py: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /requirements/default.txt: -------------------------------------------------------------------------------- 1 | requests==2.8.1 -------------------------------------------------------------------------------- /requirements/pkgutils.txt: -------------------------------------------------------------------------------- 1 | setuptools>=1.3.2 2 | wheel 3 | tox 4 | -------------------------------------------------------------------------------- /requirements/test.txt: -------------------------------------------------------------------------------- 1 | nose==1.3.7 2 | coverage==4.0.2 3 | mock==1.3.0 -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | description-file = README.rst 3 | 4 | [wheel] 5 | universal = 1 6 | -------------------------------------------------------------------------------- /scripts/removepyc.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | (cd "${1:-.}"; 3 | find . -name "*.pyc" | xargs rm -- 2>/dev/null) || echo "ok" 4 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "scripts/git-tools"] 2 | path = scripts/git-tools 3 | url = https://github.com/alexhayes/git-tools.git 4 | -------------------------------------------------------------------------------- /tox.ini: -------------------------------------------------------------------------------- 1 | [tox] 2 | envlist = py27,py33,py34,pypy 3 | 4 | [testenv] 5 | sitepackages = False 6 | commands = nosetests 7 | deps = -r{toxinidir}/requirements/test.txt -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include CHANGELOG.md 2 | include LICENSE 3 | include README.rst 4 | include MANIFEST.in 5 | include setup.cfg 6 | include setup.py 7 | recursive-include python-semrush *.py 8 | recursive-include docs * 9 | recursive-include requirements *.txt 10 | prune *.pyc 11 | prune *.sw* 12 | -------------------------------------------------------------------------------- /python_semrush/errors.py: -------------------------------------------------------------------------------- 1 | from __future__ import absolute_import, print_function, unicode_literals 2 | 3 | 4 | class BaseSemrushError(Exception): 5 | pass 6 | 7 | 8 | class SemRushKeyError(BaseSemrushError): 9 | pass 10 | 11 | 12 | class SemRushRegionalDatabaseError(BaseSemrushError): 13 | pass -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Release 0.1.3 - Sun Feb 28 21:32:01 AEDT 2016 2 | 3 | - Fixed test mock import for non python 3 4 | 5 | # Release 0.1.2 - Mon Feb 1 16:35:20 AEDT 2016 6 | 7 | - Updated git tools submodule url 8 | 9 | # Release 0.1.1 - Sun Jan 10 21:24:01 AEDT 2016 10 | 11 | - Updated the readme 12 | 13 | # Release 0.1.0 - Sun Jan 10 21:12:29 AEDT 2016 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /python_semrush/tests/response.txt: -------------------------------------------------------------------------------- 1 | Date;Database;Domain;Rank;Organic Keywords;Organic Traffic;Organic Cost;Adwords Keywords;Adwords Traffic;Adwords Cost;PLA keywords;PLA uniques\r\n20160109;au;roi.com.au;63497;88;429;2945;1092;905;13658;0;0\r\n20160109;ca;roi.com.au;2531198;0;0;0;3;0;0;0;0\r\n20160109;es;roi.com.au;0;2;0;0;0;0;0;0;0\r\n20160109;il;roi.com.au;268908;1;0;0;0;0;0;0;0\r\n20160109;in;roi.com.au;1095780;4;3;20;0;0;0;0;0\r\n20160109;jp;roi.com.au;1527052;1;0;0;0;0;0;0;0\r\n20160109;mobile-us;roi.com.au;5410614;13;23;0;6;12;24;0;0\r\n20160109;sg;roi.com.au;316149;1;0;0;0;0;0;0;0\r\n20160109;uk;roi.com.au;2688625;0;0;0;3;0;0;0;0\r\n20160108;us;roi.com.au;3658541;628;26;7;61;0;1;0;0\r\n -------------------------------------------------------------------------------- /python_semrush/__init__.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """Wrapper around the SEMrush API.""" 3 | # :copyright: (c) 2015 Jeremy Storer and individual contributors, 4 | # All rights reserved. 5 | # :license: MIT License, see LICENSE for more details. 6 | 7 | 8 | from collections import namedtuple 9 | 10 | version_info_t = namedtuple( 11 | 'version_info_t', ('major', 'minor', 'micro', 'releaselevel', 'serial'), 12 | ) 13 | 14 | VERSION = version_info_t(0, 1, 2, '', '') 15 | __version__ = '{0.major}.{0.minor}.{0.micro}{0.releaselevel}'.format(VERSION) 16 | __author__ = 'Jeremy Storer' 17 | __contact__ = 'storerjeremy@gmail.com' 18 | __homepage__ = 'http://github.com/storerjeremy/python-semrush' 19 | __docformat__ = 'restructuredtext' 20 | 21 | # -eof meta- -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | 5 | # C extensions 6 | *.so 7 | 8 | # Distribution / packaging 9 | .Python 10 | env/ 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | *.egg-info/ 23 | .installed.cfg 24 | *.egg 25 | 26 | # PyInstaller 27 | # Usually these files are written by a python script from a template 28 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 29 | *.manifest 30 | *.spec 31 | 32 | # Installer logs 33 | pip-log.txt 34 | pip-delete-this-directory.txt 35 | 36 | # Unit test / coverage reports 37 | htmlcov/ 38 | .tox/ 39 | .coverage 40 | .coverage.* 41 | .cache 42 | nosetests.xml 43 | coverage.xml 44 | *,cover 45 | 46 | # Translations 47 | *.mo 48 | *.pot 49 | 50 | # Django stuff: 51 | *.log 52 | 53 | # Sphinx documentation 54 | docs/_build/ 55 | 56 | # PyBuilder 57 | target/ 58 | 59 | #PyCharm 60 | .idea/ 61 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Jeremy Storer 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /requirements/README.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | pip requirements files 3 | ======================== 4 | 5 | 6 | Index 7 | ===== 8 | 9 | * :file:`requirements/default.txt` 10 | 11 | Default requirements for Python 2.7+. 12 | 13 | * :file:`requirements/test.txt` 14 | 15 | Requirements needed to run the full unittest suite via ./runtests.py 16 | 17 | * :file:`requirements/test-ci.txt` 18 | 19 | Extra test requirements required by the CI suite (Tox). 20 | 21 | * :file:`requirements/doc.txt` 22 | 23 | Extra requirements required to build the Sphinx documentation. 24 | 25 | * :file:`requirements/pkgutils.txt` 26 | 27 | Extra requirements required to perform package distribution maintenance. 28 | 29 | * :file:`requirements/dev.txt` 30 | 31 | Requirement file installing the current master branch of Celery and deps. 32 | 33 | Examples 34 | ======== 35 | 36 | Installing requirements 37 | ----------------------- 38 | 39 | :: 40 | 41 | $ pip install -U -r requirements/default.txt 42 | 43 | 44 | Running the tests 45 | ----------------- 46 | 47 | :: 48 | 49 | $ pip install -U -r requirements/default.txt 50 | $ pip install -U -r requirements/test.txt 51 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | python-semrush 3 | ============== 4 | 5 | Python-Semrush is a wrapper around the `SEMrush API`_ version 3.0. 6 | 7 | Thanks to `tomlinton`_ for the basis of this package. 8 | 9 | .. _`SEMrush API`: http://www.semrush.com/api-documentation/ 10 | .. _`tomlinton`: https://github.com/tomlinton 11 | 12 | Installation 13 | ============ 14 | 15 | You can install python-semrush from github. 16 | 17 | From github; 18 | 19 | .. code-block:: bash 20 | 21 | $ pip install git+https://github.com/storerjeremy/python-semrush.git 22 | 23 | Usage 24 | ===== 25 | .. code-block:: python 26 | 27 | from python_semrush.semrush import SemrushClient 28 | client = SemrushClient(key='your_semrush_api_key') 29 | result = client.domain_ranks(domain='example.com') 30 | 31 | Todo 32 | ==== 33 | 34 | - Implement projects API http://www.semrush.com/api-projects/ 35 | - Implement accounts API http://www.semrush.com/api-accounts/ 36 | - Implement specific errors 37 | 38 | License 39 | ======= 40 | 41 | This software is licensed under the `MIT License`. See the ``LICENSE`` 42 | file in the top distribution directory for the full license text. 43 | 44 | 45 | Author 46 | ====== 47 | 48 | Jeremy Storer 49 | -------------------------------------------------------------------------------- /python_semrush/tests/test_semrush.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | from __future__ import absolute_import, print_function, unicode_literals 3 | import os 4 | from unittest import TestCase 5 | try: 6 | from unittest.mock import patch 7 | except: 8 | from mock import patch 9 | from python_semrush.semrush import SemrushClient 10 | from requests import Response 11 | 12 | 13 | def semrush_response_bytes(filename): 14 | with open(os.path.join(os.path.dirname(__file__), filename), 'rb') as f: 15 | return f.read() 16 | 17 | 18 | class SemrushTestCase(TestCase): 19 | 20 | def test_parse_response(self): 21 | with open(os.path.join(os.path.dirname(__file__), 'response.txt'), 'rb') as f: 22 | response = SemrushClient.parse_response(f.read()) 23 | self.assertEqual(response.__class__, list) 24 | self.assertEqual(len(response), 10) 25 | 26 | @patch('requests.get') 27 | def test_domain_ranks(self, RequestsGet): 28 | contents = semrush_response_bytes('response.txt') 29 | 30 | RequestsGet.return_value = Response() 31 | RequestsGet.return_value.status_code = 200 32 | RequestsGet.return_value._content = contents 33 | 34 | s = SemrushClient(key='fdjsaiorghrtbnjvlouhsdlf') 35 | result = s.domain_ranks('example.com') 36 | self.assertEqual(len(result), 10) 37 | 38 | 39 | 40 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # -*- coding: utf-8 -*- 3 | 4 | try: 5 | from setuptools import setup, find_packages 6 | from setuptools.command.test import test 7 | is_setuptools = True 8 | except ImportError: 9 | raise 10 | from ez_setup import use_setuptools 11 | use_setuptools() 12 | from setuptools import setup, find_packages # noqa 13 | from setuptools.command.test import test # noqa 14 | is_setuptools = False 15 | 16 | import os 17 | import sys 18 | import codecs 19 | 20 | NAME = 'python-semrush' 21 | entrypoints = {} 22 | extra = {} 23 | 24 | # -*- Classifiers -*- 25 | 26 | classes = """ 27 | Development Status :: 4 - Beta 28 | License :: OSI Approved :: MIT License 29 | Topic :: System :: Distributed Computing 30 | Topic :: Software Development :: Object Brokering 31 | Intended Audience :: Developers 32 | Programming Language :: Python 33 | Programming Language :: Python :: 2 34 | Programming Language :: Python :: 2.6 35 | Programming Language :: Python :: 2.7 36 | Programming Language :: Python :: 3 37 | Programming Language :: Python :: 3.3 38 | Programming Language :: Python :: 3.4 39 | Programming Language :: Python :: Implementation :: CPython 40 | Programming Language :: Python :: Implementation :: PyPy 41 | Operating System :: OS Independent 42 | Operating System :: POSIX 43 | Operating System :: Microsoft :: Windows 44 | Operating System :: MacOS :: MacOS X 45 | """ 46 | classifiers = [s.strip() for s in classes.split('\n') if s] 47 | 48 | # -*- Distribution Meta -*- 49 | 50 | import re 51 | re_meta = re.compile(r'__(\w+?)__\s*=\s*(.*)') 52 | re_vers = re.compile(r'VERSION\s*=.*?\((.*?)\)') 53 | re_doc = re.compile(r'^"""(.+?)"""') 54 | rq = lambda s: s.strip("\"'") 55 | 56 | 57 | def add_default(m): 58 | attr_name, attr_value = m.groups() 59 | return ((attr_name, rq(attr_value)), ) 60 | 61 | 62 | def add_version(m): 63 | v = list(map(rq, m.groups()[0].split(', '))) 64 | return (('VERSION', '.'.join(v[0:3]) + ''.join(v[3:])), ) 65 | 66 | 67 | def add_doc(m): 68 | return (('doc', m.groups()[0]), ) 69 | 70 | pats = {re_meta: add_default, 71 | re_vers: add_version, 72 | re_doc: add_doc} 73 | here = os.path.abspath(os.path.dirname(__file__)) 74 | with open(os.path.join(here, 'python_semrush/__init__.py')) as meta_fh: 75 | meta = {} 76 | for line in meta_fh: 77 | if line.strip() == '# -eof meta-': 78 | break 79 | for pattern, handler in pats.items(): 80 | m = pattern.match(line.strip()) 81 | if m: 82 | meta.update(handler(m)) 83 | 84 | # -*- Installation Requires -*- 85 | 86 | py_version = sys.version_info 87 | 88 | 89 | def strip_comments(l): 90 | return l.split('#', 1)[0].strip() 91 | 92 | 93 | def reqs(*f): 94 | return [ 95 | r for r in ( 96 | strip_comments(l) for l in open( 97 | os.path.join(os.getcwd(), 'requirements', *f)).readlines() 98 | ) if r] 99 | 100 | install_requires = reqs('default.txt') 101 | 102 | # -*- Tests Requires -*- 103 | 104 | tests_require = reqs('test.txt') 105 | 106 | # -*- Long Description -*- 107 | 108 | if os.path.exists('README.rst'): 109 | long_description = codecs.open('README.rst', 'r', 'utf-8').read() 110 | else: 111 | long_description = 'See http://pypi.python.org/pypi/python-semrush' 112 | 113 | # -*- Entry Points -*- # 114 | 115 | # -*- %%% -*- 116 | 117 | setup( 118 | name=NAME, 119 | version=meta['VERSION'], 120 | description=meta['doc'], 121 | author=meta['author'], 122 | author_email=meta['contact'], 123 | url=meta['homepage'], 124 | platforms=['any'], 125 | license='MIT', 126 | packages=find_packages(exclude=['tests', 'tests.*']), 127 | zip_safe=False, 128 | install_requires=install_requires, 129 | tests_require=tests_require, 130 | test_suite='nose.collector', 131 | classifiers=classifiers, 132 | entry_points=entrypoints, 133 | long_description=long_description) 134 | -------------------------------------------------------------------------------- /python_semrush/semrush.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | from __future__ import absolute_import, print_function, unicode_literals 3 | import requests 4 | from python_semrush.errors import * 5 | 6 | SEMRUSH_API_URL = 'http://api.semrush.com/' 7 | SEMRUSH_ASNS_API_URL = 'http://api.asns.backend.semrush.com/' 8 | SEMRUSH_API_V1_URL = 'http://api.semrush.com/analytics/v1/' 9 | 10 | REGIONAL_DATABASES = { 11 | 'google.com': 'us', 12 | 'google.co.uk': 'uk', 13 | 'google.ca': 'ca', 14 | 'google.ru': 'ru', 15 | 'google.de': 'de', 16 | 'google.fr': 'fr', 17 | 'google.es': 'es', 18 | 'google.it': 'it', 19 | 'google.com.br': 'br', 20 | 'google.com.au': 'au', 21 | 'bing.com': 'bing-us', 22 | 'google.com.ar': 'ar', 23 | 'google.be': 'be', 24 | 'google.ch': 'ch', 25 | 'google.dk': 'dk', 26 | 'google.fi': 'fi', 27 | 'google.com.hk': 'hk', 28 | 'google.ie': 'ie', 29 | 'google.co.il': 'il', 30 | 'google.com.mx': 'mx', 31 | 'google.nl': 'nl', 32 | 'google.no': 'no', 33 | 'google.pl': 'pl', 34 | 'google.se': 'se', 35 | 'google.com.sg': 'sg', 36 | 'google.com.tr': 'tr', 37 | 'm.google.com': 'mobile-us', 38 | 'google.co.jp': 'jp', 39 | 'google.co.in': 'in' 40 | } 41 | 42 | 43 | class SemrushClient(object): 44 | 45 | def __init__(self, key): 46 | if not key: 47 | raise SemRushKeyError('A Semrush key must be provided') 48 | 49 | self.api_url = SEMRUSH_API_URL 50 | self.key = key 51 | 52 | @staticmethod 53 | def get_database_from_search_engine(search_engine='google.com'): 54 | if search_engine in REGIONAL_DATABASES: 55 | return REGIONAL_DATABASES[search_engine] 56 | else: 57 | raise SemRushRegionalDatabaseError('%s - is not an accepted search engine.' % search_engine) 58 | 59 | # Report producing methods 60 | def produce(self, report_type, **kwargs): 61 | data = self.retrieve(report_type, **kwargs) 62 | return self.parse_response(data) 63 | 64 | def retrieve(self, report_type, **kwargs): 65 | kwargs['type'] = report_type 66 | kwargs['key'] = self.key 67 | 68 | response = requests.get(self.api_url, params=kwargs) 69 | 70 | if response.status_code == 200: 71 | return response.content 72 | else: 73 | raise BaseSemrushError(response.content) 74 | 75 | @staticmethod 76 | def parse_response(data): 77 | results = [] 78 | data = data.decode('unicode_escape') 79 | lines = data.split('\r\n') 80 | lines = list(filter(bool, lines)) 81 | columns = lines[0].split(';') 82 | 83 | for line in lines[1:]: 84 | result = {} 85 | for i, datum in enumerate(line.split(';')): 86 | result[columns[i]] = datum.strip('"\n\r\t') 87 | results.append(result) 88 | 89 | return results 90 | 91 | # Overview Reports 92 | def domain_ranks(self, domain, **kwargs): 93 | """ 94 | Domain Overview (All Databases) 95 | This report provides live or historical data on a domain’s keyword rankings in both organic and paid search in 96 | all regional databases. 97 | 98 | :param domain: The domain to query data for ie. 'example.com' 99 | 100 | Optional kwargs 101 | - display_date: date in format "YYYYMM15" 102 | - export_columns: Db, Dn, Rk, Or, Ot, Oc, Ad, At, Ac 103 | """ 104 | return self.produce('domain_ranks', domain=domain, **kwargs) 105 | 106 | def domain_rank(self, domain, database, **kwargs): 107 | """ 108 | Domain Overview (One Database) 109 | This report provides live or historical data on a domain’s keyword rankings in both organic and paid search in a 110 | chosen regional database. 111 | 112 | :param domain: The domain to query data for ie. 'example.com' 113 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 114 | 115 | Optional kwargs 116 | - export_escape: 1 to wrap report columns in quotation marks (") 117 | - export decode: 1 or 0, 0 to url encode string 118 | - display_date: date in format "YYYYMM15" 119 | - export_columns: Dn, Rk, Or, Ot, Oc, Ad, At, Ac 120 | """ 121 | if database not in REGIONAL_DATABASES.values(): 122 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 123 | return self.produce('domain_rank', domain=domain, database=database, **kwargs) 124 | 125 | def domain_rank_history(self, domain, database, **kwargs): 126 | """ 127 | Domain Overview (History) 128 | This report provides live and historical data on a domain’s keyword rankings in both organic and paid search in 129 | a chosen database. 130 | 131 | :param domain: The domain to query data for ie. 'example.com' 132 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 133 | 134 | Optional kwargs 135 | - display_limit: integer 136 | - display_offset: integer 137 | - export_escape: 1 138 | - export_decode: 1 or 0 139 | - display_daily: 1 140 | - export_columns: Rk, Or, Ot, Oc, Ad, At, Ac, Dt 141 | - display_sort: dt_asc, dt_desc 142 | """ 143 | if database not in REGIONAL_DATABASES.values(): 144 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 145 | return self.produce('domain_rank_history', domain=domain, database=database, **kwargs) 146 | 147 | def rank_difference(self, database, **kwargs): 148 | """ 149 | Winners and Losers 150 | This report shows changes in the number of keywords, traffic, and budget estimates of the most popular websites 151 | in Google's top 20 and paid search results. 152 | 153 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 154 | 155 | Optional kwargs 156 | - display_limit: integer 157 | - display_offset: integer 158 | - export_escape: 1 159 | - export_decode: 1 or 0 160 | - display_date: date in format "YYYYMM15" 161 | - export_columns: Dn, Rk, Or, Ot, Oc, Ad, At, Ac, Om, Tm, Um, Am, Bm, Cm 162 | - display_sort: om_asc, om_desc, tm_asc, tm_desc, um_asc, um_desc, am_asc, am_desc, bm_asc, bm_desc, cm_asc, 163 | cm_desc 164 | """ 165 | if database not in REGIONAL_DATABASES.values(): 166 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 167 | return self.produce('rank_difference', database=database, **kwargs) 168 | 169 | def rank(self, database, **kwargs): 170 | """ 171 | Semrush Rank 172 | This report lists the most popular domains ranked by traffic originating from Google's top 20 organic search 173 | results. 174 | 175 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 176 | 177 | Optional kwargs 178 | - display_limit: integer 179 | - display_offset: integer 180 | - export_escape: 1 181 | - export_decode: 1 or 0 182 | - display_date: date in format "YYYYMM15" 183 | - export_columns: Dn, Rk, Or, Ot, Oc, Ad, At, Ac 184 | """ 185 | if database not in REGIONAL_DATABASES.values(): 186 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 187 | return self.produce('rank', database=database, **kwargs) 188 | 189 | # Domain Reports 190 | def domain_organic(self, domain, database, **kwargs): 191 | """ 192 | Domain Organic Search Keywords 193 | This report lists keywords that bring users to a domain via Google's top 20 organic search results. 194 | 195 | :param domain: The domain to query data for ie. 'example.com' 196 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 197 | 198 | Optional kwargs 199 | - display_limit: integer 200 | - display_offset: integer 201 | - export_escape: 1 202 | - export_decode: 1 or 0 203 | - display_date: date in format "YYYYMM15" 204 | - export_columns: Ph, Po, Pp, Pd, Nq, Cp, Ur, Tr, Tc, Co, Nr, Td 205 | - display_sort: tr_asc, tr_desc, po_asc, po_desc, tc_asc, tc_desc 206 | - display_positions: new, lost, rise or fall 207 | - display_filter: 208 | """ 209 | if database not in REGIONAL_DATABASES.values(): 210 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 211 | return self.produce('domain_organic', domain=domain, database=database, **kwargs) 212 | 213 | def domain_adwords(self, domain, database, **kwargs): 214 | """ 215 | Domain Paid Search 216 | This report lists keywords that bring users to a domain via Google's paid search results. 217 | 218 | :param domain: The domain to query data for ie. 'example.com' 219 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 220 | 221 | Optional kwargs 222 | - display_limit: integer 223 | - display_offset: integer 224 | - export_escape: 1 225 | - export_decode: 1 or 0 226 | - display_date: date in format "YYYYMM15" 227 | - export_columns: Ph, Po, Pp, Pd, Ab, Nq, Cp, Tr, Tc, Co, Nr, Td, Tt, Ds, Vu, Ur 228 | - display_sort: tr_asc, tr_desc, po_asc, po_desc, tc_asc, tc_desc 229 | - display_positions: new, lost, rise or fall 230 | - display_filter: 231 | """ 232 | if database not in REGIONAL_DATABASES.values(): 233 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 234 | return self.produce('domain_adwords', domain=domain, database=database, **kwargs) 235 | 236 | def domain_adwords_unique(self, domain, database, **kwargs): 237 | """ 238 | Ads Copies 239 | This report shows unique ad copies SEMrush noticed when the domain ranked in Google's paid search results for 240 | keywords from our databases. 241 | 242 | :param domain: The domain to query data for ie. 'example.com' 243 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 244 | 245 | Optional kwargs 246 | - display_limit: integer 247 | - display_offset: integer 248 | - export_escape: 1 249 | - export_decode: 1 or 0 250 | - export_columns: Ph, Po, Pp, Nq, Cp, Tr, Tc, Co, Nr, Td, Tt, Ds, Vu, Ur, Pc 251 | - display_filter: 252 | """ 253 | if database not in REGIONAL_DATABASES.values(): 254 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 255 | return self.produce('domain_adwords_unique', domain=domain, database=database, **kwargs) 256 | 257 | def domain_organic_organic(self, domain, database, **kwargs): 258 | """ 259 | Competitors In Organic Search 260 | This report lists a domain’s competitors in organic search results. 261 | 262 | :param domain: The domain to query data for ie. 'example.com' 263 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 264 | 265 | Optional kwargs 266 | - display_limit: integer 267 | - display_offset: integer 268 | - export_escape: 1 269 | - export_decode: 1 or 0 270 | - display_date: date in format "YYYYMM15" 271 | - export_columns: Dn, Cr, Np, Or, Ot, Oc, Ad 272 | - display_sort: np_desc, cr_desc 273 | """ 274 | if database not in REGIONAL_DATABASES.values(): 275 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 276 | return self.produce('domain_organic_organic', domain=domain, database=database, **kwargs) 277 | 278 | def domain_adwords_adwords(self, domain, database, **kwargs): 279 | """ 280 | Competitors In Paid Search 281 | This report lists a domain’s competitors in paid search results. 282 | 283 | :param domain: The domain to query data for ie. 'example.com' 284 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 285 | 286 | Optional kwargs 287 | - display_limit: integer 288 | - display_offset: integer 289 | - export_escape: 1 290 | - export_decode: 1 or 0 291 | - display_date: date in format "YYYYMM15" 292 | - export_columns: Dn, Cr, Np, Ad, At, Ac, Or 293 | - display_sort: np_desc, cr_desc 294 | """ 295 | if database not in REGIONAL_DATABASES.values(): 296 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 297 | return self.produce('domain_adwords_adwords', domain=domain, database=database, **kwargs) 298 | 299 | def domain_adwords_historical(self, domain, database, **kwargs): 300 | """ 301 | Domains Ads History 302 | This report shows keywords a domain has bid on in the last 12 months and its positions in paid search results. 303 | 304 | :param domain: The domain to query data for ie. 'example.com' 305 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 306 | 307 | Optional kwargs 308 | - display_limit: integer 309 | - display_offset: integer 310 | - export_escape: 1 311 | - export_decode: 1 or 0 312 | - export_columns: Ph, Dt, Po, Cp, Nq, Tr, Ur, Tt, Ds, Vu, Cv 313 | - display_sort: cv_asc, cv_desc 314 | - display_filter: 315 | """ 316 | if database not in REGIONAL_DATABASES.values(): 317 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 318 | return self.produce('domain_adwords_historical', domain=domain, database=database, **kwargs) 319 | 320 | def domain_domains(self, domains, database, **kwargs): 321 | """ 322 | Domain Vs. Domain 323 | This report allows users to compare up to five domains by common keywords, unique keywords, all keywords, or 324 | search terms that are unique to the first domain. 325 | 326 | :param domains: The domains to query data for 327 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 328 | 329 | Optional kwargs 330 | - display_limit: integer 331 | - display_offset: integer 332 | - export_escape: 1 333 | - export_decode: 1 or 0 334 | - display_date: date in format "YYYYMM15" 335 | - export_columns: Ph, P0, P1, P2, P3, P4, Nr, Cp, Co, Nq 336 | - display_sort: p0_asc, p0_desc, p1_asc, p1_desc, p2_asc, p2_desc, p3_asc, p3_desc, p4_asc, p4_desc, nq_asc, 337 | nq_desc, co_asc, co_desc, cp_asc, cp_desc, nr_asc, nr_desc 338 | - display_filter: 339 | 340 | Note: Refer to SEMrush API documentation for format of domains 341 | """ 342 | if database not in REGIONAL_DATABASES.values(): 343 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 344 | return self.produce('domain_domains', domains=domains, database=database, **kwargs) 345 | 346 | def domain_shopping(self, domain, database, **kwargs): 347 | """ 348 | Domain PLA Search Keywords 349 | This report lists keywords that trigger a domain’s product listing ads to appear in Google's paid search 350 | results. 351 | 352 | :param domain: The domain to query data for ie. 'example.com' 353 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 354 | 355 | Optional kwargs 356 | - display_limit: integer 357 | - display_offset: integer 358 | - export_escape: 1 359 | - export_decode: 1 or 0 360 | - export_columns: Ph, Po, Pp, Pd, Ab, Nq, Cp, Tr, Tc, Co, Nr, Td, Tt, Ds, Vu, Ur 361 | - display_sort: tr_asc, tr_desc, po_asc, po_desc, tc_asc, tc_desc 362 | - display_filter: 363 | """ 364 | if database not in REGIONAL_DATABASES.values(): 365 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 366 | return self.produce('domain_shopping', domain=domain, database=database, **kwargs) 367 | 368 | def domain_shopping_unique(self, domain, database, **kwargs): 369 | """ 370 | PLA Copies 371 | This report shows product listing ad copies SEMrush noticed when the domain ranked in Google's paid search results 372 | for keywords from our databases. 373 | 374 | :param domain: The domain to query data for ie. 'example.com' 375 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 376 | 377 | Optional kwargs 378 | - display_limit: integer 379 | - display_offset: integer 380 | - export_escape: 1 381 | - export_decode: 1 or 0 382 | - export_columns: Ph, Po, Pp, Nq, Cp, Tr, Tc, Co, Nr, Td, Tt, Ds, Vu, Ur, Pc 383 | - display_filter: 384 | """ 385 | if database not in REGIONAL_DATABASES.values(): 386 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 387 | return self.produce('domain_shopping_unique', domain=domain, database=database, **kwargs) 388 | 389 | def domain_shopping_shopping(self, domain, database, **kwargs): 390 | """ 391 | PLA Competitors 392 | This report lists domains a queried domain is competing against in Google's paid search results with product 393 | listing ads. 394 | 395 | :param domain: The domain to query data for ie. 'example.com' 396 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 397 | 398 | Optional kwargs 399 | - display_limit: integer 400 | - display_offset: integer 401 | - export_escape: 1 402 | - export_decode: 1 or 0 403 | - export_columns: Dn, Cr, Np, Ad, At, Ac, Or 404 | - display_sort: np_asc, np_desc, cr_asc, cr_desc 405 | - display_filter: 406 | """ 407 | if database not in REGIONAL_DATABASES.values(): 408 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 409 | return self.produce('domain_shopping_shopping', domain=domain, database=database, **kwargs) 410 | 411 | # Keyword Reports 412 | def phrase_all(self, phrase, **kwargs): 413 | """ 414 | Keyword Overview (All Databases) 415 | This report provides a summary of a keyword, including its volume, CPC, competition, and the number of results 416 | in all regional databases. 417 | 418 | :param phrase: The phrase or term to obtain data for 419 | 420 | Optional kwargs 421 | - database: 422 | - export_escape: 1 423 | - export_decode: 1 or 0 424 | - export_columns: Db, Ph, Nq, Cp, Co 425 | """ 426 | return self.produce('phrase_all', phrase=phrase, **kwargs) 427 | 428 | def phrase_this(self, phrase, database, **kwargs): 429 | """ 430 | Keyword Overview (One Database) 431 | This report provides a summary of a keyword, including its volume, CPC, competition, and the number of results 432 | in a chosen regional database. 433 | 434 | :param phrase: The phrase or term to obtain data for 435 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 436 | 437 | Optional kwargs 438 | - export_escape: 1 439 | - export_decode: 1 or 0 440 | - display_date: date in format "YYYYMM15" 441 | - export_columns: Ph, Nq, Cp, Co, Nr 442 | """ 443 | if database not in REGIONAL_DATABASES.values(): 444 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 445 | return self.produce('phrase_this', phrase=phrase, database=database, **kwargs) 446 | 447 | def phrase_organic(self, phrase, database, **kwargs): 448 | """ 449 | Organic Results 450 | This report lists domains that are ranking in Google's top 20 organic search results with a requested keyword. 451 | 452 | :param phrase: The phrase or term to obtain data for 453 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 454 | 455 | Optional kwargs 456 | - display_limit: integer 457 | - export_escape: 1 458 | - export_decode: 1 or 0 459 | - display_date: date in format "YYYYMM15" 460 | - export_columns: Dn, Ur 461 | """ 462 | if database not in REGIONAL_DATABASES.values(): 463 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 464 | return self.produce('phrase_organic', phrase=phrase, database=database, **kwargs) 465 | 466 | def phrase_adwords(self, phrase, database, **kwargs): 467 | """ 468 | Paid Results 469 | This report lists domains that are ranking in Google's paid search results with a requested keyword. 470 | 471 | :param phrase: The phrase or term to obtain data for 472 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 473 | 474 | Optional kwargs 475 | - display_limit: integer 476 | - export_escape: 1 477 | - export_decode: 1 or 0 478 | - display_date: date in format "YYYYMM15" 479 | - export_columns: Dn, Ur 480 | """ 481 | if database not in REGIONAL_DATABASES.values(): 482 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 483 | return self.produce('phrase_adwords', phrase=phrase, database=database, **kwargs) 484 | 485 | def phrase_related(self, phrase, database, **kwargs): 486 | """ 487 | Related Keywords 488 | This report provides an extended list of related keywords, synonyms, and variations relevant to a queried term 489 | in a chosen database. 490 | 491 | :param phrase: The phrase or term to obtain data for 492 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 493 | 494 | Optional kwargs 495 | - display_limit: integer 496 | - display_offset: integer 497 | - export_escape: 1 498 | - export_decode: 1 or 0 499 | - display_date: date in format "YYYYMM15" 500 | - export_columns: Ph, Nq, Cp, Co, Nr, Td 501 | - display_sort: nq_asc, nq_desc, cp_asc, cp_desc, co_asc, co_desc, nr_asc, nr_desc 502 | - display_filter: 503 | """ 504 | if database not in REGIONAL_DATABASES.values(): 505 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 506 | return self.produce('phrase_related', phrase=phrase, database=database, **kwargs) 507 | 508 | def phrase_adwords_historical(self, phrase, database, **kwargs): 509 | """ 510 | Keywords Ads History 511 | This report shows domains that have bid on a requested keyword in the last 12 months and their positions in paid 512 | search results. 513 | 514 | :param phrase: The phrase or term to obtain data for 515 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 516 | 517 | Optional kwargs 518 | - display_limit: integer 519 | - display_offset: integer 520 | - export_escape: 1 521 | - export_decode: 1 or 0 522 | - export_columns: Dn, Dt, Po, Ur, Tt, Ds, Vu, At, Ac, Ad 523 | """ 524 | if database not in REGIONAL_DATABASES.values(): 525 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 526 | return self.produce('phrase_adwords_historical', database=database, **kwargs) 527 | 528 | def phrase_fullsearch(self, phrase, database, **kwargs): 529 | """ 530 | Phrase Match Keywords 531 | The report offers a list of phrase matches and alternate search queries, including particular keywords or 532 | keyword expressions. 533 | 534 | :param phrase: The phrase or term to obtain data for 535 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 536 | 537 | Optional kwargs 538 | - display_limit: integer 539 | - display_offset: integer 540 | - export_escape: 1 541 | - export_decode: 1 or 0 542 | - export_columns: Ph, Nq, Cp, Co, Nr, Td 543 | - display_sort: nq_asc, nq_desc, cp_asc, cp_desc, co_asc, co_desc, nr_asc, nr_desc 544 | - display_filter: 545 | """ 546 | if database not in REGIONAL_DATABASES.values(): 547 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 548 | return self.produce('phrase_fullsearch', phrase=phrase, database=database, **kwargs) 549 | 550 | def phrase_kdi(self, phrase, database, **kwargs): 551 | """ 552 | Keyword Difficulty 553 | This report provides keyword difficulty, an index that helps to estimate how difficult it would be to seize 554 | competitors' positions in organic search within the Google's top 20 with an indicated search term. 555 | 556 | :param phrase: The phrase or term to obtain data for 557 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 558 | 559 | Optional kwargs 560 | - export_escape: 1 561 | - export_columns: Ph, Kd 562 | """ 563 | if database not in REGIONAL_DATABASES.values(): 564 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 565 | return self.produce('phrase_kdi', phrase=phrase, database=database, **kwargs) 566 | 567 | # URL Reports 568 | def url_organic(self, url, database, **kwargs): 569 | """ 570 | URL Organic Search Keywords 571 | This report lists keywords that bring users to a URL via Google's top 20 organic search results. 572 | 573 | :param url: The URL to obtain data for, ie. http://example.com 574 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 575 | 576 | Optional kwargs 577 | - display_limit: integer 578 | - display_offset: integer 579 | - export_escape: 1 580 | - export_decode: 1 or 0 581 | - display_date: date in format "YYYYMM15" 582 | - export_columns: Ph, Po, Nq, Cp, Co, Tr, Tc, Nr, Td 583 | """ 584 | if database not in REGIONAL_DATABASES.values(): 585 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 586 | return self.produce('url_organic', url=url, database=database, **kwargs) 587 | 588 | def url_adwords(self, url, database, **kwargs): 589 | """ 590 | URL Paid Search Keywords 591 | This report lists keywords that bring users to a URL via Google's paid search results. 592 | 593 | :param url: The URL to obtain data for, ie. http://example.com 594 | :param database: The database to query, one of the choices from REGIONAL_DATABASES 595 | 596 | Optional kwargs 597 | - display_limit: integer 598 | - display_offset: integer 599 | - export_escape: 1 600 | - export_decode: 1 or 0 601 | - display_date: date in format "YYYYMM15" 602 | - export_columns: Ph, Po, Nq, Cp, Co, Tr, Tc, Nr, Td, Tt, Ds 603 | """ 604 | if database not in REGIONAL_DATABASES.values(): 605 | raise SemRushRegionalDatabaseError('%s - is not an accepted database.' % database) 606 | return self.produce('url_adwords', url=url, database=database, **kwargs) 607 | 608 | # Display Advertising Reports 609 | def publisher_text_ads(self, domain, **kwargs): 610 | """ 611 | Publisher Display Ads 612 | This report lists display ads that have appeared on a publisher’s website. 613 | 614 | :param domain: The domain to query data for ie. 'example.com' 615 | 616 | Optional kwargs 617 | - display_limit: integer 618 | - display_offset: integer 619 | - export_escape: 1 620 | - export_decode: 1 or 0 621 | - export_columns: title, text, first_seen, last_seen, times_seen, avg_position, media_type, visible_url 622 | - display_sort: last_seen_asc, last_seen_desc, first_seen_asc, first_seen_desc, times_seen_asc, times_seen_asc, 623 | times_seen_desc 624 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 625 | - display_filter: 626 | """ 627 | kwargs['action'] = 'report' 628 | kwargs['export'] = 'api' 629 | self.api_url = SEMRUSH_ASNS_API_URL 630 | return self.produce('publisher_text_ads', domain=domain, **kwargs) 631 | 632 | def publisher_advertisers(self, domain, **kwargs): 633 | """ 634 | Advertisers 635 | This report lists advertisers whose display ads have appeared on a queried publisher’s website. 636 | 637 | :param domain: The domain to query data for ie. 'example.com' 638 | 639 | Optional kwargs 640 | - display_limit: integer 641 | - display_offset: integer 642 | - export_escape: 1 643 | - export_decode: 1 or 0 644 | - export_columns: domain, ads_count, first_seen, last_seen, times_seen, ads_percent 645 | - display_sort: last_seen_asc, last_seen_desc, first_seen_asc, first_seen_desc, times_seen_asc, times_seen_desc 646 | ads_count_asc, ads_count_desc 647 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 648 | - display_filter: 649 | """ 650 | kwargs['action'] = 'report' 651 | kwargs['export'] = 'api' 652 | self.api_url = SEMRUSH_ASNS_API_URL 653 | return self.produce('publisher_advertisers', domain=domain, **kwargs) 654 | 655 | def advertiser_publishers(self, domain, **kwargs): 656 | """ 657 | Publishers 658 | This report lists publisher’s websites where an advertiser’s display ads have appeared. 659 | 660 | :param domain: The domain to query data for ie. 'example.com' 661 | 662 | Optional kwargs 663 | - display_limit: integer 664 | - display_offset: integer 665 | - export_escape: 1 666 | - export_decode: 1 or 0 667 | - export_columns: domain, ads_count, first_seen, last_seen, times_seen, ads_percent 668 | - display_sort: last_seen_asc, last_seen_desc, first_seen_asc, first_seen_desc, times_seen_asc, times_seen_desc 669 | ads_count_asc, ads_count_desc 670 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 671 | - display_filter: 672 | """ 673 | kwargs['action'] = 'report' 674 | kwargs['export'] = 'api' 675 | self.api_url = SEMRUSH_ASNS_API_URL 676 | return self.produce('advertiser_publishers', domain=domain, **kwargs) 677 | 678 | def advertiser_text_ads(self, domain, **kwargs): 679 | """ 680 | Advertiser Display Ads 681 | This report lists display ads of a queried advertiser’s website. 682 | 683 | :param domain: The domain to query data for ie. 'example.com' 684 | 685 | Optional kwargs 686 | - display_limit: integer 687 | - display_offset: integer 688 | - export_escape: 1 689 | - export_decode: 1 or 0 690 | - export_columns: title,text, first_seen, last_seen, times_seen, avg_position, media_type, visible_url 691 | - display_sort: last_seen_asc, last_seen_desc, first_seen_asc, first_seen_desc, times_seen_asc, times_seen_asc, 692 | times_seen_desc 693 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 694 | - display_filter: 695 | """ 696 | kwargs['action'] = 'report' 697 | kwargs['export'] = 'api' 698 | self.api_url = SEMRUSH_ASNS_API_URL 699 | return self.produce('advertiser_text_ads', domain=domain, **kwargs) 700 | 701 | def advertiser_landings(self, domain, **kwargs): 702 | """ 703 | Landing Pages 704 | This report lists URLs of a domain’s landing pages promoted via display ads. 705 | 706 | :param domain: The domain to query data for ie. 'example.com' 707 | 708 | Optional kwargs 709 | - display_limit: integer 710 | - display_offset: integer 711 | - export_escape: 1 712 | - export_decode: 1 or 0 713 | - export_columns: target_url, first_seen, last_seen, times_seen, ads_count 714 | - display_sort: ast_seen_asc, last_seen_desc, first_seen_asc, first_seen_desc, times_seen_asc, times_seen_desc, 715 | ads_count_asc, ads_count_desc 716 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 717 | - display_filter: 718 | """ 719 | kwargs['action'] = 'report' 720 | kwargs['export'] = 'api' 721 | self.api_url = SEMRUSH_ASNS_API_URL 722 | return self.produce('advertiser_landings', domain=domain, **kwargs) 723 | 724 | def advertiser_publisher_text_ads(self, domain, **kwargs): 725 | """ 726 | Advertiser Display Ads On A Publishers Website 727 | This report lists the display ads of a given advertiser that have appeared on a particular publisher’s website. 728 | 729 | :param domain: The domain to query data for ie. 'example.com' 730 | 731 | Optional kwargs 732 | - display_limit: integer 733 | - display_offset: integer 734 | - export_escape: 1 735 | - export_decode: 1 or 0 736 | - export_columns: title,text, first_seen, last_seen, times_seen, avg_position, media_type, visible_url 737 | - display_sort last_seen_asc, last_seen_desc, first_seen_asc, first_seen_desc, times_seen_asc, times_seen_asc, 738 | times_seen_desc 739 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 740 | - display_filter: 741 | """ 742 | kwargs['action'] = 'report' 743 | kwargs['export'] = 'api' 744 | self.api_url = SEMRUSH_ASNS_API_URL 745 | return self.produce('advertiser_publisher_text_ads', domain=domain, **kwargs) 746 | 747 | def advertiser_rank(self, domain, **kwargs): 748 | """ 749 | Advertisers Rank 750 | This report lists advertisers ranked by the total number of display ads noticed by SEMrush. 751 | 752 | :param domain: The domain to query data for ie. 'example.com' 753 | 754 | Optional kwargs 755 | - export_escape: 1 756 | - export_columns: domain, ads_overall, text_ads_overall, ads_count, text_ads_count, times_seen, first_seen, 757 | last_seen, media_ads_overall, media_ads_count, publishers_overall, publishers_count 758 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 759 | """ 760 | kwargs['action'] = 'report' 761 | kwargs['export'] = 'api' 762 | self.api_url = SEMRUSH_ASNS_API_URL 763 | return self.produce('advertiser_rank', domain=domain, **kwargs) 764 | 765 | def publisher_rank(self, domain, **kwargs): 766 | """ 767 | Publishers Rank 768 | This report lists publishers ranked by the total number of display ads noticed by SEMrush. 769 | 770 | :param domain: The domain to query data for ie. 'example.com' 771 | 772 | Optional kwargs 773 | - export_escape: 1 774 | - export_columns: domain, ads_overall, text_ads_overall, ads_count, text_ads_count, times_seen, first_seen, 775 | last_seen, media_ads_overall, media_ads_count, advertiser_overall, advertiser_count 776 | - device_type: all, desktop, smartphone_apple, smartphone_android, tablet_apple, tablet_android 777 | """ 778 | kwargs['action'] = 'report' 779 | kwargs['export'] = 'api' 780 | self.api_url = SEMRUSH_ASNS_API_URL 781 | return self.produce('publisher_rank', domain=domain, **kwargs) 782 | 783 | # Backlinks 784 | def backlinks_overview(self, target, target_type='root_domain'): 785 | """ 786 | Backlinks Overview 787 | This report provides a summary of backlinks, including their type, referring domains and IP addresses for a 788 | domain, root domain, or URL. 789 | 790 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 791 | :param target_type: domain, root_domain or url 792 | 793 | Kwargs 794 | - target_type: domain, root_domain or url 795 | """ 796 | self.api_url = SEMRUSH_API_V1_URL 797 | return self.produce('backlinks_overview', target=target, target_type=target_type) 798 | 799 | def backlinks(self, target, target_type='root_domain', **kwargs): 800 | """ 801 | Backlinks 802 | This report lists backlinks for a domain, root domain, or URL. 803 | 804 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 805 | :param target_type: domain, root_domain or url 806 | 807 | Optional kwargs 808 | - display_limit: integer 809 | - display_offset: integer 810 | - export_columns: page_score, response_code, source_size, external_num, internal_num, redirect_url, source_url, 811 | source_title, image_url, target_url, target_title, anchor, image_alt, last_seen, first_seen, nofollow, form, 812 | frame, image, sitewide 813 | - display_sort: last_seen_asc, last_seen_desc, first_seen_asc, first_seen_desc 814 | - display_filter: 815 | """ 816 | self.api_url = SEMRUSH_API_V1_URL 817 | return self.produce('backlinks', target=target, target_type=target_type, **kwargs) 818 | 819 | def backlinks_refdomains(self, target, target_type='root_domain', **kwargs): 820 | """ 821 | Referring Domains 822 | This report lists domains pointing to the queried domain, root domain, or URL. 823 | 824 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 825 | :param target_type: domain, root_domain or url 826 | 827 | Optional kwargs 828 | - display_limit: integer 829 | - display_offset: integer 830 | - export_columns: domain_score, domain, backlinks_num, ip, country, first_seen, last_seen 831 | - display_sort: rank_asc, rank_desc, backlinks_asc, backlinks_desc, last_seen_asc, last_seen_desc, first_seen_asc, 832 | first_seen_desc 833 | - display_filter: 834 | """ 835 | self.api_url = SEMRUSH_API_V1_URL 836 | return self.produce('backlinks_refdomains', target=target, target_type=target_type, **kwargs) 837 | 838 | def backlinks_refips(self, target, target_type='root_domain', **kwargs): 839 | """ 840 | Referring IPs 841 | This report lists IP addresses where backlinks to a domain, root domain, or URL are coming from. 842 | 843 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 844 | :param target_type: domain, root_domain or url 845 | 846 | Optional kwargs 847 | - display_limit: integer 848 | - display_offset: integer 849 | - export_columns: ip, country, domains_num, backlinks_num, first_seen, last_seen 850 | - display_sort: backlinks_num_asc, backlinks_num_desc, last_seen_asc, last_seen_desc, first_seen_asc, 851 | first_seen_desc, domains_num_asc domains_num_desc 852 | """ 853 | self.api_url = SEMRUSH_API_V1_URL 854 | return self.produce('backlinks_refips', target=target, target_type=target_type, **kwargs) 855 | 856 | def backlinks_tld(self, target, target_type='root_domain', **kwargs): 857 | """ 858 | TLD Distribution 859 | This report shows referring domain distributions depending on their top-level domain type. 860 | 861 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 862 | :param target_type: domain, root_domain or url 863 | 864 | Optional kwargs 865 | - export_columns: zone, domains_num, backlinks_num 866 | - display_sort: backlinks_num_asc, backlinks_num_desc, domains_num_asc domains_num_desc 867 | """ 868 | self.api_url = SEMRUSH_API_V1_URL 869 | return self.produce('backlinks_tld', target=target, target_type=target_type, **kwargs) 870 | 871 | def backlinks_geo(self, target, target_type='root_domain', **kwargs): 872 | """ 873 | Referring Domains By Country 874 | This report shows referring domain distributions by country (an IP address defines a country). 875 | 876 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 877 | :param target_type: domain, root_domain or url 878 | 879 | Optional kwargs 880 | - export_columns: country, domains_num, backlinks_num 881 | - display_sort: backlinks_num_asc, backlinks_num_desc, domains_num_asc domains_num_desc 882 | """ 883 | self.api_url = SEMRUSH_API_V1_URL 884 | return self.produce('backlinks_geo', target=target, target_type=target_type, **kwargs) 885 | 886 | def backlinks_anchors(self, target, target_type='root_domain', **kwargs): 887 | """ 888 | Anchors 889 | This report lists anchor texts used in backlinks leading to the queried domain, root domain, or URL. It also 890 | includes the number of backlinks and referring domains per anchor. 891 | 892 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 893 | :param target_type: domain, root_domain or url 894 | 895 | Optional kwargs 896 | - export_columns: anchor, domains_num, backlinks_num, first_seen, last_seen 897 | - display_sort: backlinks_num_asc, backlinks_num_desc, last_seen_asc, last_seen_desc, first_seen_asc, 898 | first_seen_desc, domains_num_asc domains_num_desc 899 | """ 900 | self.api_url = SEMRUSH_API_V1_URL 901 | return self.produce('backlinks_anchors', target=target, target_type=target_type, **kwargs) 902 | 903 | def backlinks_pages(self, target, target_type='root_domain', **kwargs): 904 | """ 905 | Indexed Pages 906 | This report shows indexed pages of the queried domain 907 | 908 | :param target: A domain, root domain, or URL address to retrieve the data for ie. 909 | :param target_type: domain, root_domain or url 910 | 911 | Optional kwargs 912 | - export_columns: response_code, backlinks_num, domains_num, last_seen, external_num, internal_num, source_url, 913 | source_title 914 | - display_sort: backlinks_num_asc, backlinks_num_desc, domains_num_asc, domains_num_desc, last_seen_asc, 915 | last_seen_desc 916 | """ 917 | self.api_url = SEMRUSH_API_V1_URL 918 | return self.produce('backlinks_pages', target=target, target_type=target_type, **kwargs) 919 | --------------------------------------------------------------------------------