SemRush.com -> API

Or login with Facebook

SEMRush API (version 3.0)

Want to use API?

We have a special subscription type, designed for those, who want to use SEMrush API a lot.

Subscribe for $15

Limitations for API and web-interface are the same. Please note that all API data is UTF-8 encoded.

The request format
Request samples
Error Messages
API and export
Columns order
Integration scripts examples
Terms of use

The request format
The GET request for data should be sent in the following format:
http://%DB%.api.semrush.com/?action=report&type=%REPORT_TYPE%&%REQUEST_TYPE%=%REQUEST%&key=%API_KEY%&display_limit=%LIMIT%&display_offset=%OFFSET%&export=api&export_columns=%EXPORT_COLUMNS%&export_escape=%EXPORT_ESCAPE%
Where:
- %DB% - requested database. Valid values: "us" - for Google.com, "uk" - for Google.co.uk, "ca" - for Google.ca, "ru" - for Google.ru, "de" for Google.de, "fr" for Google.fr, "es" for Google.es, "it" for Google.it, "br" for Google.com.br, "au" for Google.com.au & "us.bing" for Bing.com
- %REPORT_TYPE% - type of the report. Valid values: "domain_rank", "domain_organic", "domain_adwords", "domain_organic_organic", "domain_adwords_adwords", "domain_organic_adwords", "domain_adwords_organic", "phrase_this", "phrase_related" or "url_organic" (see examples below)
  Note: Important! "Full Search" type of report is unavailable through API
- %API_KEY% - user identification key - available through your profile on the site.
- %REQUEST_TYPE% - type of request. Valid values: "domain", "phrase" or "url" (see examples below)
- %REQUEST% - your request
- %LIMIT% - number of results returned
- %OFFSET% - instructs to skip a specified number of results before beginning to return results to you
- %EXPORT_ESCAPE% - if set to "1" columns values will be wrapped in double quotes
- %EXPORT_COLUMNS% - list of column names, separated by a coma. You may list the specific column names you need, in any order you'd like. List of default column names by request types (expand for detailed explanation):
  - Main report - Dn, Rk, Or, Ot, Oc, Ad, At, Ac
    
    Dn - A site name.
    
    Rk - Rating of sites by the number of visitors coming from the first 20 search results
    
    Or - Keywords this site has in the TOP20 organic results
    
    Ot - Estimated number of visitors coming from the first 20 search results (per month)
    
    Oc - Estimated cost of purchasing the same number of visitors through Ads
    
    Ad - Keywords this site has in the TOP20 Ads results
    
    At - Estimated number of visitors coming from Ads (per month)
    
    Ac - Estimated expenses the site has for advertising in Ads (per month)
  - Organic Keywords report - Ph, Po, Pp, Nq, Cp, Ur, Tr, Tc, Co, Nr, Td
    
    Ph - The search query the site has within the first 20 search results
    
    Po - The site's position for the search query (at the moment of data collection)
    
    Pp - The site's position for the search query (at the time of prior data collection)
    
    Nq - Average number of queries for the keyword per month (for the corresponding local version of search engine)
    
    Cp - Average price of a click on an Ad for this search query (in U.S. dollars)
    
    Ur - URL of a page on the site displayed in search results for this query (landing page)
    
    Tr - The ratio comparing the number of visitors coming to the site from this search request to all visitors to the site from search results
    
    Tc - The estimated value of the organic traffic generated by the query as compared to the cost of purchasing the same volume of traffic through Ads
    
    Co - Competition of advertisers for that term (the higher the number - the greater the competition)
    
    Nr - The number of search results - how many results does the search engine return for this query
    
    Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
  - AdWords keywords report - Ph, Po, Pp, Nq, Cp, Vu, Tr, Tc, Co, Nr, Td
    
    Ph - Search query the site buys
    
    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 for the keyword per month (for the corresponding local version of search engine)
    
    Cp - Average price of a click on an Ad for this search query (in U.S. dollars)
    
    Vu - Display URL. This is the URL displayed on your Ad, identifying your site for users
    
    Tr - The number of visitors driven to the site from an Ad as compared to all visitors coming to the site from Ads
    
    Tc - The site's expenditure on this particular Ad as compared to it's expenditures on all Ads
    
    Co - Competition of advertisers for that term (the higher the number - the greater the competition)
    
    Nr - The number of search results - how many results does the search engine return 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.
  - Competitors in organic search report - Dn, Np, Or, Ot, Oc, Ad
    
    Dn - Sites competing with this site in search results, sorted by the number of common keywords
    
    Np - The number of keywords for which the site is displayed in search results next to the analyzed site
    
    Or - Keywords this site has in the TOP20 organic results
    
    Ot - Estimated number of visitors coming from the first 20 search results (per month)
    
    Oc - Estimated cost of purchasing the same number of visitors through Ads
    
    Ad - Keywords this site has in the TOP20 Ads results
  - Competitors in AdWords search report - Dn, Np, Ad, At, Ac, Or
    
    Dn - Sites competing with this site in Ads, sorted by the number of common keywords
    
    Np - Number of common keywords in Ads bought by these two sites
    
    Ad - Keywords this site has in the TOP20 Ads results
    
    At - Estimated number of visitors coming from Ads (per month)
    
    Ac - Estimated expenses the site has for advertising in Ads (per month)
    
    Or - Keywords this site has in the TOP20 organic results
  - Potential ad/traffic buyers report - Dn, Np, Ad, At, Ac, Or
    
    Dn - The list of sites that buys ads in Ads for those keywords that the domain under analyzis has within TOP20 search results
    
    Np - Number of keywords on which ads of this particular site appear and the analyzed site gets within TOP20 search results
    
    Ad - Keywords this site has in the TOP20 Ads results
    
    At - Estimated number of visitors coming from Ads (per month)
    
    Ac - Estimated expenses the site has for advertising in Ads (per month)
    
    Or - Keywords this site has in the TOP20 organic results
  - Potential ad/traffic sellers report - Dn, Np, Or, Ot, Oc, Ad
    
    Dn - Sites that get into TOP20 search results for keyword queries that analyzed site buy in Ads
    
    Np - The number of keywords which this site has in search results next to the Ads of the analyzed site
    
    Or - Keywords this site has in the TOP20 organic results
    
    Ot - Estimated number of visitors coming from the first 20 search results (per month)
    
    Oc - Estimated cost of purchasing the same number of visitors through Ads
    
    Ad - Keywords this site has in the TOP20 Ads results
  - Main keyword report - Ph, Nq, Cp, Co, Nr
    
    Ph - The search query the site has within the first 20 search results
    
    Nq - Average number of queries for the keyword per month (for the corresponding local version of search engine)
    
    Cp - Average price of a click on an Ad for this search query (in U.S. dollars)
    
    Co - Competition of advertisers for that term (the higher the number - the greater the competition)
    
    Nr - The number of search results - how many results does the search engine return for this query
  - Related keyword report - Ph, Nq, Cp, Co, Nr, Td
    
    Ph - The search query the site has within the first 20 search results
    
    Nq - Average number of queries for the keyword per month (for the corresponding local version of search engine)
    
    Cp - Average price of a click on an Ad for this search query (in U.S. dollars)
    
    Co - Competition of advertisers for that term (the higher the number - the greater the competition)
    
    Nr - The number of search results - how many results does the search engine return for this query
    
    Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
  - Organic URL report - Ph, Po, Nq, Cp, Co, Tr, Tc, Nr, Td
    
    Ph - Search query that the URL has within the first 20 organic or Ads results
    
    Po - The position of this URL for this keyword in organic or Ads results
    
    Nq - Average number of queries for the keyword per month (for the corresponding local version of search engine)
    
    Cp - Average price of a click on an Ad for this search query (in U.S. dollars)
    
    Co - Competition of advertisers for that term (the higher the number - the greater 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 results does the search engine return for this query
    
    Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
  - AdWords URL report - Ph, Po, Nq, Cp, Co, Tr, Tc, Nr, Td
    
    Ph - Search query that the URL has within the first 20 organic or Ads results
    
    Po - The position of this URL for this keyword in organic or Ads results
    
    Nq - Average number of queries for the keyword per month (for the corresponding local version of search engine)
    
    Cp - Average price of a click on an Ad for this search query (in U.S. dollars)
    
    Co - Competition of advertisers for that term (the higher the number - the greater 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 results does the search engine return for this query
    
    Td - Dynamics of change in the number of search queries in the past 12 months (estimated)
Request samples
- seobook.com - Main report
  http://fr.api.semrush.com/?action=report&type=domain_rank&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&export=api&export_columns=Dn,Rk,Or,Ot,Oc,Ad,At,Ac&domain=seobook.com
- seobook.com+(by+organic) - Organic Keywords report
  http://fr.api.semrush.com/?action=report&type=domain_organic&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Ph,Po,Pp,Nq,Cp,Ur,Tr,Tc,Co,Nr,Td&domain=seobook.com
- ebay.com+(by+adwords) - AdWords keywords report
  http://fr.api.semrush.com/?action=report&type=domain_adwords&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Ph,Po,Pp,Nq,Cp,Vu,Tr,Tc,Co,Nr,Td&domain=ebay.com
- seobook.com+(by+organic_organic) - Competitors in organic search report
  http://fr.api.semrush.com/?action=report&type=domain_organic_organic&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Dn,Np,Or,Ot,Oc,Ad&domain=seobook.com
- ebay.com+(by+adwords_adwords) - Competitors in AdWords search report
  http://fr.api.semrush.com/?action=report&type=domain_adwords_adwords&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Dn,Np,Ad,At,Ac,Or&domain=ebay.com
- ebay.com+(by+organic_adwords) - Potential ad/traffic buyers report
  http://fr.api.semrush.com/?action=report&type=domain_organic_adwords&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Dn,Np,Ad,At,Ac,Or&domain=ebay.com
- ebay.com+(by+adwords_organic) - Potential ad/traffic sellers report
  http://fr.api.semrush.com/?action=report&type=domain_adwords_organic&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Dn,Np,Or,Ot,Oc,Ad&domain=ebay.com
- search+engine+optimization - Main keyword report
  http://fr.api.semrush.com/?action=report&type=phrase_this&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&export=api&export_columns=Ph,Nq,Cp,Co,Nr&phrase=search+engine+optimization
- search+engine+optimization+(related) - Related keyword report
  http://fr.api.semrush.com/?action=report&type=phrase_related&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Ph,Nq,Cp,Co,Nr,Td&phrase=search+engine+optimization
- http://tools.seobook.com/ - Organic URL report
  http://fr.api.semrush.com/?action=report&type=url_organic&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Ph,Po,Nq,Cp,Co,Tr,Tc,Nr,Td&url=http://tools.seobook.com/
- http://www.amazon.com/ - AdWords URL report
  http://fr.api.semrush.com/?action=report&type=url_adwords&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&display_limit=10&export=api&export_columns=Ph,Po,Nq,Cp,Co,Tr,Tc,Nr,Td&url=http://www.amazon.com/
Error Messages
- ERROR 30 :: LIMIT EXCEEDED
- ERROR 50 :: NOTHING FOUND
- ERROR 70 :: API KEY HASH FAILURE
- ERROR 40 :: MANDATORY PARAMETER "action" NOT SET OR EMPTY
- ERROR 41 :: MANDATORY PARAMETER "type" NOT SET OR EMPTY
- ERROR 42 :: MANDATORY PARAMETER "domain" NOT SET OR EMPTY
- ERROR 43 :: MANDATORY PARAMETER "phrase" NOT SET OR EMPTY
- ERROR 44 :: MANDATORY PARAMETER "url" NOT SET OR EMPTY
- ERROR 45 :: MANDATORY PARAMETER "vs_domain" NOT SET OR EMPTY
- ERROR 120 :: WRONG KEY - ID PAIR
- ERROR 121 :: WRONG FORMAT OR EMPTY HASH
- ERROR 122 :: WRONG FORMAT OR EMPTY KEY
- ERROR 130 :: API DISABLED
- ERROR 131 :: LIMIT EXCEEDED
- ERROR 132 :: API UNITS BALANCE IS ZERO
- ERROR 133 :: DB ACCESS DENIED
- ERROR 134 :: TOTAL LIMIT EXCEEDED
- ERROR 135 :: API REPORT TYPE DISABLED
API and export

API format is similar to CSV semicolon export
Columns order
- Column names never change
- Order of columns may be changed
- Number of columns may be increased
- Old columns may be removed only after notification
Integration scripts examples
Below are three simple scripts showing you how you can integrate SEMrush API data into your web project. Examples are written in PERL, PHP and JavaScript (using YQL). All you have to do is:download the script you find suits you best, unzip it, set some parameters (explained in comments, in a script body) and upload it to your web server.

Attention!!! Use JavaScript example with caution as your API key in that script gets disclosed and can be viewed by anyone!!!
- PERL SEMRush API integration example script - perl_example.zip
- PHP SEMRush API integration example script - php_example.zip
- JavaScript SEMRush API integration example script - js_example.zip - Using this method your API key will be disclosed and can be viewed by anyone!!!
Terms of use

If you integrate SEMrush API in your own web service you should send X-Real-IP header with your requests! (In case a partner's user overloads the server, we'd like to have an opportunity to disconnect the specific user without blocking the partner's access to SEMRush's API. For this reason, it is necessary for us to know the IP of the end-consumer.)

Publication of data provided by the service is only possible with reference to the data source or proper branding on the site. Any other type of publication is strictly prohibited.

The use of information provided by this service for commercial and other third-party services in the form in which it was obtained directly from the service without the express written consent of SEMRush.com is strictly prohibited.

You may not perform more than 10 requests per second, nor more than 2 simultaneous requests.

E-mail		Or sign up with your Facebook account Sign up with Facebook
Password
Name
Phone
My domain

	Please, send me e-mail updates
	By clicking on "Create my account" or "Sign up with Facebook", you are agreeing to the Terms of Use.