Supermetrics Support Forum

SEMrush Project Use Case - Position Tracking, Keyword Ranking

This use case shows you how to set up a query that replicates the data seen in the SEMrush Projects' Keyword Ranking report, that is part of the Position Tracking data.


Here is an example report we want to replicate from the Rankings tab in the SEMrush Projects UI:

Full keyword view of SEMrush's Position Tracking report, part of the Projects interface


The connector to use will be SEMrush Projects - this is supported currently in Google Sheets, Data Studio, and the Supermetrics API. It is an "early access" connector, which means it is still being worked on and may have some bugs/issues.

Blue box highlights the data source "SEMrush Projects (Early access)" with SEMrush logo, red circle with red flames trailing off it to the left


The setup in this use case will be done in Google Sheets, but the same fields and configuration can be used in the other platforms to build the report.


IMPORTANT - Each query run with SEMrush Projects will use API units from your account, even if the query results were not what you wanted. Be careful about what you run and start with small test, with 5 or 10 rows maximum to preserve API units. See also SEMrush API Units.


  1. Click on the SEMrush Projects connector and log in with your API key (which can be obtained here).
  2. Under Select projects, pick the project you wish to obtain keyword ranking data for.

    Blue box highlights the "Select projects" section of the Supermetrics sidebar, the element is expanded and showing box with supermetrics.com project selected

    This should match this part of the SEMrush UI:

    Screenshot of Position Tracking overview with the available projects listed for keyword tracking

  3. Under Report configuration, you will select the settings for the report type. In this case you, want the "Organic positions report" option.

    Orange box highlights the "Select query type:" option, Organic positions report, to get the tracking data for organic keywords

    This aligns to this setting for the Positing Tracking report:

    Orange box highlights the "Type: Organic" option in the SEMrush UI


    Note - If you want to track "Google Ads" based data (aka Paid), then you can use the "AdWords positions report" instead.

  4. For the Tracked URL field, you will add the domain or URL you want to get keywords for, either your Tracked URL or a competitors. Note that this MUST use what they call a 'mask' to work properly.


    IMPORTANT - If you give the wrong mask/no mask, you may get no keyword position results back, so this is critical to set up correctly!


    Examples of proper masks, based on the URL type:

    URL TypeMask example
    rootdomain*.ebay.com/*
    subdomainwww.ebay.com/*
    subfolderebay.com/motors/*
    URL (default)https://www.ebay.com/motors/

    Note - URLs that end in a trailing slash (/) and those without are considered two different URLs. So "mysite.com/*" and "mysite.com*" are not the same and may return different results.


    For this example then, we want to get the keywords for the root domain of Supermetrics, so the mask would be:
    *supermetrics.com/*

    Orange box highlights the "Tracked URL" setting, with the proper site mask for Supermetrics main website, *supermetrics.com/*

  5. Other settings:
    • Max keywords is the number of keyword values to pull, make sure this is set high enough to get all keywords in the project. Supermetrics has 11, so we set to 20 to ensure all were retrieved. (WARNING - more keywords means more API units are used, so start low to test and increase when the query is final).
    • Local pack filter aligns with the "Rank count" option in the UI. Default to "Include local pack rankings" should be used, unless you have changed the setting in the UI.

      Orange box highlights the SEMrush option for "Rank count" which matches the "Local pack filter" setting in Supermetrics

    • Position Filter is an optional setting and aligns with the "Top positions & changes" filter in the UI:

      Orange box shows the options under the filter control "Top positions & changes" in the SEMrush Position Tracking report

    • Display tags is an optional setting, and can be used to filter results based on any tags you have set. For example, we could filter for excel and get this keyword.

      Orange box highlights a tag added to a specific keyword for "excel"

      You can add multiple tags, separated by the pipe (|) character.

  6. Under Select Dates, you can pick the range you want to monitor for the changes.


    WARNING - Longer ranges means more API units are used! Start short at first and then extend as you confirm your tests.

    Select dates setting shown set to "Last X days" where X is 7

    This should align with this element in the SEMrush UI:

    Orange box highlights date range element in Position Tracking report in the SEMrush UI - it is also set to the last 7 days to match the Supermetrics date selector

  7. Under Select metrics, you want the following that align with the report:
    • Position at beginning
    • Position at end
    • Position difference
    • Absolute visibility

      Example of the "Select metrics" settings in the sidebar, showing various metrics selected to get the changes in the position of the keyword in the rankings

  8. Under Split by, Split to rows you want the following dimensions that align with the report:
    • Keyword
    • Avg searches per month
    • Avg Price

      Example of Split by section of the sidebar, showing some dimensions selected, such as to get the "Keyword" itself

      Note that # of rows to fetch in this case does nothing, you set the rows based on the Max keywords setting under the "Report configuration" above.

  9. Click Get data to Table to pull the data (if using Data Studio, the table will update automatically).


    Here's the results in our example:


    Here's then how those items align to the report to check (note that "Absolute visibility" doesn't appear to be featured in the UI, so there's link to it):

    Orange arrows point to each element and shows the Supermetrics field name that matches that element

  10. There are other dimensions that may be useful, such as "Date" or "Keyword position" but each one added will split the data further.

    For example, if we added both, there will now be multiple entries for each keyword, showing the data for each day in the range as well as the past from starting position to ending position:

    Orange boxes highlight a specific keywords journey over a few days, starting at 50 and moving down to 83

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.