This guide covers the basic functionality of the Supermetrics SEMrush connector for Sheets and Data Studio, and gives examples of how to set up a query in both products.


Basics

The SEMRush connector requires you have set up an API account with SEMrush and have purchased a subscription with them for API request units. Supermetrics does not include this with the connector. If you have not done so already, please visit this site to get started with your SEMrush account - https://www.semrush.com/api-use/


The SEMrush connector uses a query-type system where you select the kind of report you want to get data for. The types of fields you can get are locked to the query type, so should not be possible to make invalid combinations! Note that you cannot combine different reports into a single query, you will need to make a new query for each query type. 


Query Types

The SEMrush connector supports 5 main types of queries - Domain, Keyword, URLs, Display Ads, and Backlinks - for a total of 35 different query-types. The connector uses the same structure as the API Reports with the same names, so you can check the SEMrush Analytics API documentation to find out what specific reports are available and what fields you can pull from them.


Query type selection in Google Sheets:

Showing 'Select query type' drop-down in Google Sheets


Query type selection in Data Studio:

Query type drop-down in Data Studio connector



Example Query Setup in Google Sheets

Here is a walk-through for setting up a 'Domain organic search keywords' query using the Google Sheets Add-on. (The example for Data Studio is below this section.)


IMPORTANT - each query you run with the SEMrush connector will use your API units, even if the query result wasn't what you wanted. You can run yourself out of available units if you are not careful!

  1. With an empty cell selected, launch the sidebar in Google Sheets.
  2. In the Data Source section, scroll down to the Simple Connectors part of the list and then select the connector "SEMrush".

    SEMRush connector icon with red flames coming from a red ball

  3. In the box provided, give you SEMrush API key that you obtained with you signed up with SEMrush for an API subscription (you can find your key here when logged into their website). Click Log In to continue.

    Blue arrow points to the API Key field to log in to the SEMRush service

  4. Open the Query Type section. In the Select query type drop-down, select "Domain organic search keywords".

    Highlighting the 'Domain organic search keywords' query in the drop-down

  5. In the Domain: box, add the domain name you wish to search for. You can add expand the box and add more than one name, one each on a new line.
  6. In the SEMrush database drop-down, select the database you wish to search against. You can only select one at a time. Most major markets are covered.
  7. In the # of rows per item drop-down, select "50". This will pull the top 50 items for the domains you added, in alphabetical order for keyword. For better performance and use fewer API units, avoid extremely high row values.

    Example query setup in Google Sheets add-on

  8. Open the Select fields section. By default all fields should be selected, but you can add/remove fields to your liking. Note that the available fields are linked to the report type, so not all items may be available.

    Example metrics selection, also showing the other possible options

  9. You can also apply filters to some fields under Filter, or set "no headers" in the advanced settings under the Options. These are optional though, and not required to make the query work.
  10. At the top of the sidebar, click Get Data to Table to run the query and see the results. This example is showing the position and prior position of keywords, listed in alphabetical order.

    Example output with the SEMRush keyword query

  11. If further adjustments need to be made, click Modify. Note that due to the nature of the "Query type" system, you cannot gather different report types or different databases into the same query. If you get errors, see the "Common Issues" section in this article at the bottom.


Example Query Setup in Data Studio

Here is a walk-through for setting up a 'Domain organic search keywords' query using the Data Studio connector.


IMPORTANT - each query you run with the SEMrush connector will use your API units, even if the query result wasn't what you wanted. You can run yourself out of available units if you are not careful!

  1. In Data Studio, add a new data source and search for "SEMrush" in the Partner Connectors section. Click SELECT to add it.

    SEMRush partner connector from Supermetrics with blue select banner


  2. Click AUTHORIZE to start the authorization process for Data Studio. In the resulting pop-up, click your Google account you are using for Data Studio access. Click Allow to continue (else the connector won't function).
  3. Click AUTHORIZE for SEMrush. There will be a pop-up that will disappear. This is fine, you will use your API key for access instead of logging into the service.

    Authorization step for SEMRush connector, with blue authorize button


  4. In the Your SEMrush API key box, give you SEMrush API key that you obtained with you signed up with SEMrush for an API subscription (you can find your key here when logged into their website). Make sure to copy it cleanly - extra characters or spaces will cause errors

    Blue highlighted text box for your SEMrush API key

  5. In the Query type drop-down, select "Domain organic search keywords".

    Query type drop-down with the example type selected

  6. Go down to the ***************** SETTINGS FOR QUERY TYPE: Domain organic search keywords ***************** section.
  7. In the Domain text box, add one or more domain names, comma separated.
  8. In the SEMRush database drop-down, select the database you wish to search against. You can only select one at a time. Most major markets are covered.
  9. In the # of rows per item drop-down, select "10". This will pull the top 10 items for the domains you added. For better performance and use fewer API units, avoid extremely high row values.

    Example query setup in Data Studio connector

  10. You do not need to fill out any other query section as it will not be used. Note that you can only set one query type at a time with this connector. If you need other query types, repeat this process to create a new data source with the different query type selected.
  11. Give the Data Source a meaningful name.

    Blue highlighted text given an example data source name

  12. Click CONNECT in the upper right-hand corner to create the data source.
  13. It will take you to a page with all the connector's fields that are available for the "Domain organic search keywords" query type. Click ADD TO REPORT to continue.
  14. Create a report element on the report page, selecting your new source as the Data Source. Add the metrics and dimensions available to create your query. In this example, a table is used to show the 10 keywords selected for the domain "supermetrics.com" from Google.com database.

    Example output of query in Data Studio table element


  15. If you need to modify the query, you can do so from the Data bar in the Data Studio UI and it will update automatically to reflect your changes.


Common Issues


"No account objects selected" Errors

More often affects Data Studio. Check that you filled out the proper query section and that there's a valid information given.

Example of Domain overview query type not having an value in the settings



"Authentication failed" Errors

The SEMRush API Key field is blank, has hidden characters copied in on accident, or is incorrect. Go back to the authentication settings and check to make sure that is filled out and is cleanly copied into the form.


"API UNITS BALANCE IS ZERO" Errors

You've run out of API units for your SEMrush account and won't be able to make more queries until you purchase more units. Please check your status of your API limit on the SEMRush API site. Note that there may be some delays if you recently purchased more units, so if you get this error but do have units, wait some time and try again.