Position Tracking

Projects

Last updated: August 18, 2021

About Position Tracking API

Below you will find a description of methods that can be divided into three groups: Management, Available regions, and Reports.

Management

Lets you create a Position Tracking campaign and manage the process of sending emails with tracking campaign statistics.

The base URL

https://api.semrush.com/management/v1/projects/{projectID or campaignID}/tracking/

Available regions

Returns a list of available countries with corresponding regions and cities.

The base URL

https://api.semrush.com/management/v1/info/

Reports

Returns a set of reports about your product. All of the report requests use the HTTP GET method.

The base URL

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Project and campaign IDs

Both project and campaign IDs are required to send requests through the Position Tracking API.

To find the IDs for a specific campaign using the Semrush web interface, open your campaign in the Position Tracking tool. Then, look at the name of the HTML page in your browser's address bar. The number before the underscore represents the project ID, while the number following the underscore is the campaign ID.

Project and campaign IDs in the address bar

To find the IDs for multiple campaigns, use the request that returns a list of all campaigns within a project. This request consumes 100 API units and requires you to know the project ID. You can check your project ID either by using the method described earlier or by sending the request that returns a list of all your projects, including their IDs and basic information.

Formatting

Use a proper mask in requests with the url parameter.

URL type	Mask example
rootdomain	.ebay.com/
subdomain	www.ebay.com/*
subfolder	ebay.com/motors/*
url	http://www.ebay.com/motors/

Encode parameter values containing special characters.

Character	Encoded
#	%23
&	%26
+	%2B
-	%2D
:	%3A
\|	%7C

Show all

When using the display_tags_condition parameter in requests, any tag values that include special characters must be double-encoded.
For example, the "name&co" tag must be submitted as "name%2526co". Here, %25 is decoded as the % character, and then %26 is decoded as the & character.

Sortings

{DATE} is a date in the YYYYMMDD format.
{DOMAIN_N} is a domain number: 0, 1, 2, 3, 4.

Value	Description
ad_asc	By the difference in average position over the selected period, in ascending order
ad_desc	By the difference in average position over the selected period, in descending order
0_av_asc	By average position on the start date of the selected period, in ascending order
0_av_desc	By average position on the start date of the selected period, in descending order
1_av_asc	By average position on the end date of the selected period, in ascending order
1_av_desc	By average position on the end date of the selected period, in descending order
av_asc	By average position, in ascending order
av_desc	By average position, in descending order
{DOMAIN_N}_be_asc	By position at the start date of the selected period, in ascending order
{DOMAIN_N}_be_desc	By position at the start date of the selected period, in descending order
cd_asc	By visibility change, in ascending order
cd_desc	By visibility change, in descending order
cl_asc	By visibility, in ascending order
cl_desc	By visibility, in descending order
cp_asc	By CPC, in ascending order
cp_desc	By CPC, in descending order
{DATE}_asc	By date, in ascending order
{DATE}_desc	By date, in descending order
{DOMAIN_N}_diff_asc	By position change, in ascending order
{DOMAIN_N}_diff_desc	By position change, in descending order
{DOMAIN_N}_fi_asc	By position at the end date of the selected period, in ascending order
{DOMAIN_N}_fi_desc	By position at the end date of the selected period, in descending order
{DOMAIN_N}_pos_asc	By position at the end date of the selected period, in ascending order
{DOMAIN_N}_pos_desc	By position at the end date of the selected period, in descending order
0_mc_asc	By the number of keywords having a specific URL on SERP for the start date of the selected period, in ascending order
0_mc_desc	By the number of keywords having a specific URL on SERP for the start date of the selected period, in descending order
1_mc_asc	By the number of keywords having a specific URL on SERP for the end date of the selected period, in ascending order
1_mc_desc	By the number of keywords having a specific URL on SERP for the end date of the selected period, in descending order
md_asc	By the difference in the number of keywords having a specific URL on SERP over the selected period, in ascending order
md_desc	By the difference in the number of keywords having a specific URL on SERP over the selected period, in descending order
0_nq_asc	By volume on the start date of the selected period, in ascending order
0_nq_desc	By volume on the start date of the selected period, in descending order
1_nq_asc	By volume on the end date of the selected period, in ascending order
1_nq_desc	By volume on the end date of the selected period, in descending order
nq_asc	By volume, in ascending order
nq_desc	By volume, in descending order
ph_asc	By keyword, in ascending order
ph_desc	By keyword, in descending order
rd_asc	By the difference in volume over the selected period, in ascending order
rd_desc	By the difference in volume over the selected period, in descending order
sov_asc	By Share of Voice, in ascending order
sov_desc	By Share of Voice, in descending order
sovdiff_asc	By the difference in Share of Voice over the selected period, in ascending order
sovdiff_desc	By the difference in Share of Voice over the selected period, in descending order
0_tr_asc	By estimated traffic on the start date of the selected period, in ascending order
0_tr_desc	By estimated traffic on the start date of the selected period, in descending order
1_tr_asc	By estimated traffic on the end date of the selected period, in ascending order
1_tr_desc	By estimated traffic on the end date of the selected period, in descending order
trdiff_asc	By the difference in the estimated traffic over the selected period, in ascending order
trdiff_desc	By the difference in the estimated traffic over the selected period, in descending order
ur_asc	By URL, in ascending order
ur_desc	By URL, in descending order
vi_asc	By visibility, in ascending order
vi_desc	By visibility, in descending order
0_vd_asc	By the difference in visibility over the selected period, in ascending order
0_vd_desc	By the difference in visibility over the selected period, in descending order

Show all

Filters

To apply a filter to a report, add the display_filter parameter with a URL-encoded string that contains filter parameters separated by "|". You can apply up to 25 filter parameters in a single request.

A filter consists of <sign>|<field>|<operation>|<value>.

The following filter narrows down the report data to keywords that contain the word "phone", have a volume greater than 10,000, and CPC greater than 2.

Example

display_filter=+|Ph|Co|phone|+|Nq|Gt|10000|+|Cp|Gt|2

The encoded variant of the example filter to add to a request

display_filter=%2B%7CPh%7CCo%7Cphone%7C%2B%7CNq%7CGt%7C10000%7C%2B%7CCp%7CGt%7C2

Parameter	Values	Description
sign	+, -	Include or exclude
field	Ph, Cp, Nq	Ph - phrase; Cp - average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords); Nq - the average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months.
operation	For metrical fields: Eq, Gt, Lt For textual fields: Bw, Ew, Eq, Co	For metrical fields: Eq - exactly matching; Gt - greater than; Lt - less than. For textual fields: Bw - starts with; Ew - ends with; Eq - exactly matching; Co - containing.
value	string	Value to filter for

Price: 100 API units per request

This request creates a Position Tracking campaign in a project. The newly created campaign won't have any keywords. To add keywords, use the Add keywords to an existing tracking campaign request.

When creating a campaign in a project that already has one or more tracking campaigns, make sure that a combination of its location (either country_id, region_id, or city_id ) and device is different from those in the existing campaigns.

You can use the campaign_id value from the response as {campaignID} in other requests to the Position Tracking API.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
tracking_url_type*	rootdomain, subdomain, subfolder, url	Type of the tracked URL.
tracking_url*	string	Tracked URL.
country_id	integer	Get a list of countries
region_id	integer	Get a list of regions
city_id	integer	Get a list of cities
weekly_notification	1 (default), 0	`1`: Enable weekly emails. `0`: Disable weekly emails.
first_letter	1 (default), 0	`1`: Send an email when the first harvesting for the project is finished. `0`: Do not send an email when the first harvesting for the project is finished.
timezone	integer	Time zone. The crawling starts at 05:00 in a specified time zone.
device	desktop, phone, tablet	Target device.

* Fields marked by an asterisk (*) are required

Endpoint (POST)

https://api.semrush.com/management/v1/projects/{projectID}/tracking/enable?key=YOUR_API_KEY

Request example

{
  "tracking_url": "ebay.com",
  "tracking_url_type": "rootdomain",
  "country_id": "2840",
  "weekly_notification": "1",
  "device": "desktop"
}

Response example

{
  "status": "SUCCESS",
  "action": "tracking_enable",
  "result": {
    "campaign_id": "103345921_15710"
  }
}

Price: 100 API units per request

This request lets you enable the delivery of weekly emails with tracking campaign statistics.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.

* Fields marked by an asterisk (*) are required

Endpoint (PUT)

https://api.semrush.com/management/v1/projects/{campaignID}/tracking/notifications?key=YOUR_API_KEY

Price: 100 API units per request

This request lets you disable the delivery of weekly emails with tracking campaign statistics.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.

* Fields marked by an asterisk (*) are required

Endpoint (DELETE)

https://api.semrush.com/management/v1/projects/{campaignID}/tracking/notifications?key=YOUR_API_KEY

Price: 100 API units per keyword added

This request lets you add keywords to track to an existing tracking campaign and group them with tags.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
campaignID*	string	Campaign ID.
keywords	array	Keywords.
tags	array	Tags for a keyword.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
url	string	Domain of a tracking campaign.
tools	array	List of project tools activated by the user.
project_id	string	Project ID.
project_name	string	Project name.
campaign_id	string	Campaign ID.
competitors	array	Competitors.
keywords	array	Keywords.

* Fields marked by an asterisk (*) are required

Endpoint (PUT)

https://api.semrush.com/management/v1/projects/{campaignID}/keywords?key=YOUR_API_KEY

Request example

{
  "keywords": [
    {
      "keyword": "seo",
      "tags": [
        "seo"
      ]
    },
    {
      "keyword": "seotool",
      "tags": [
        "seo"
      ]
    }
  ]
}

Response example

{
  "url": "mysite.com",
  "tools": [
    {
      "tool": "tracking"
    }
  ],
  "project_id": 643526670283248,
  "project_name": "my old project",
  "campaign_id": "643526670283248_17238",
  "competitors": [
    "google.com",
    "ebay.com",
    "bing.com"
  ],
  "keywords": [
    {
      "keyword": "search tool",
      "tags": [
        "search"
      ],
      "timestamp": 1391517755
    },
    {
      "keyword": "search engine",
      "tags": [
        "search"
      ],
      "timestamp": 1391517755
    },
    {
      "keyword": "seo",
      "tags": [
        "seo"
      ],
      "timestamp": 1491517755
    },
    {
      "keyword": "seotool",
      "tags": [
        "seo"
      ],
      "timestamp": 1491517755
    }
  ]
}

Price: 100 API units per request

This request lets you remove tracked keywords from an existing tracking campaign.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
campaignID*	string	Campaign ID.
keywords	array	Keywords.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
url	string	Domain of a tracking campaign.
tools	array	List of project tools activated by the user.
project_id	string	Project ID.
project_name	string	Project name.
campaign_id	string	Campaign ID.
competitors	array	Competitors.
keywords	array	Keywords.

* Fields marked by an asterisk (*) are required

Endpoint (DELETE)

https://api.semrush.com/management/v1/projects/{campaignID}/keywords?key=YOUR_API_KEY

Request example

{
  "keywords": [
    {
      "keyword": "seo"
    },
    {
      "keyword": "seotool"
    }
  ]
}

Response example

{
  "url": "mysite.com",
  "tools": [
    {
      "tool": "tracking"
    }
  ],
  "project_id": 643526670283248,
  "project_name": "my old project",
  "campaign_id": "643526670283248_17238",
  "competitors": [
    "google.com",
    "ebay.com",
    "bing.com"
  ],
  "keywords": [
    {
      "keyword": "search tool",
      "tags": [
        "search"
      ],
      "timestamp": 1391517755
    },
    {
      "keyword": "search engine",
      "tags": [
        "search"
      ],
      "timestamp": 1391517755
    }
  ]
}

Price: 100 API units per request

This request lets you assign up to five tags to each of your tracked keywords.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
campaignID*	string	Campaign ID.
keywords	array	Keywords.
tags	array	Tags.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
url	string	Domain of a tracking campaign.
tools	array	List of project tools activated by the user.
project_id	string	Project ID.
project_name	string	Project name.
campaign_id	string	Campaign ID.
competitors	array	Competitors.
keywords	array	Keywords.

* Fields marked by an asterisk (*) are required

Endpoint (PUT)

https://api.semrush.com/management/v1/projects/{campaignID}/tags?key=YOUR_API_KEY

Request example

[
  {
    "tag": "seo",
    "keywords": [
      "search tool",
      "search engine"
    ]
  },
  {
    "tag": "seo tool",
    "keywords": [
      "search tool",
      "search engine"
    ]
  }
]

Response example

{
   "url": "mysite.com",
   "tools": [
       {
         "tool": "tracking"
       }
   ],
   "project_id": 643526670283248,
   "project_name": "myproject",
   "campaign_id": 643526670283248_17238,
   "competitors": [
       "google.com",
       "ebay.com"
   ],
   "keywords": [
       {
            "keyword": "search tool",
            "tags": [
                "search",
                "seo",
                "seo tool"
             ],
            "timestamp": 1391517755
       },
       {
            "keyword": "search engine",
            "tags": [
                "search",
                "seo",
                "seo tool"
             ],
            "timestamp": 1391517755
       }
   ]
}

Price: 100 API units per request

This request lets you delete up to five tags assigned to each of your tracked keywords.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
campaignID*	string	Campaign ID.
keywords	array	Keywords.
tags	array	Tags.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
url	string	Domain of a tracking campaign.
tools	array	List of project tools activated by the user.
project_id	string	Project ID.
project_name	string	Project name.
campaign_id	string	Campaign ID.
competitors	array	Competitors.
keywords	array	Keywords.

* Fields marked by an asterisk (*) are required

Endpoint (DELETE)

https://api.semrush.com/management/v1/projects/{campaignID}/tags?key=YOUR_API_KEY

Request example

[
  {
    "tag": "seo",
    "keywords": [
      "search tool",
      "search engine"
    ]
  },
  {
    "tag": "seo tool",
    "keywords": [
      "search tool",
      "search engine"
    ]
  }
]

Response example

{
   "url": "mysite.com",
   "tools": [
       {
         "tool": "tracking"
       }
   ],
   "project_id": 643526670283248,
   "project_name": "myproject",
   "campaign_id": 643526670283248_17238,
   "competitors": [
       "google.com",
       "ebay.com"
   ],
   "keywords": [
       {
            "keyword": "search tool",
            "tags": [
                "search"
             ],
            "timestamp": 1391517755
       },
       {
            "keyword": "search engine",
            "tags": [
                "search"
             ],
            "timestamp": 1391517755
       }
   ]
}

Price: 100 API units per request

This request lets you add competitor domains to an existing tracking campaign.

About adding competitors to a Position Tracking campaign ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
campaignID*	string	Campaign ID.
competitors	array	List of competitors.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
url	string	Domain of a tracking campaign.
tools	array	List of project tools activated by the user.
project_id	string	Project ID.
project_name	string	Project name.
campaign_id	string	Campaign ID.
competitors	array	Competitors.
keywords	array	Keywords.

* Fields marked by an asterisk (*) are required

Endpoint (PUT)

https://api.semrush.com/management/v1/projects/{campaignID}/competitors?key=YOUR_API_KEY

Request example

{
  "competitors": [
    "yahoo.com"
  ]
}

Response example

{
   "url": "mysite.com",
   "tools": [
       {
         "tool": "tracking"
       }
   ],
   "project_id": 643526670283248,
   "project_name": "myproject",
   "campaign_id": 643526670283248_17238,
   "competitors": [
       "google.com",
       "ebay.com",
       "yahoo.com"
   ],
   "keywords": [
       {
            "keyword": "search tool",
            "tags": [
                "search",
                "seo",
                "seo tool"
             ],
            "timestamp": 1391517755
       },
       {
            "keyword": "search engine",
            "tags": [
                "search",
                "seo",
                "seo tool"
             ],
            "timestamp": 1391517755
       }
   ]
}

Price: 100 API units per request

This request lets you remove competitors from an existing tracking campaign.

About adding and removing competitors from a Position Tracking campaign ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
campaignID*	string	Campaign ID.
competitors	array	List of competitors.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
url	string	Domain of a tracking campaign.
tools	array	List of project tools activated by the user.
project_id	string	Project ID.
project_name	string	Project name.
campaign_id	string	Campaign ID.
competitors	array	Competitors.
keywords	array	Keywords.

* Fields marked by an asterisk (*) are required

Endpoint (DELETE)

https://api.semrush.com/management/v1/projects/{campaignID}/competitors?key=YOUR_API_KEY

Request example

{
  "competitors": [
    "ebay.com",
    "yahoo.com"
  ]
}

Response example

{
   "url": "mysite.com",
   "tools": [
       {
         "tool": "tracking"
       }
   ],
   "project_id": 643526670283248,
   "project_name": "myproject",
   "campaign_id": 643526670283248_17238,
   "competitors": [
       "google.com"
   ],
   "keywords": [
       {
            "keyword": "search tool",
            "tags": [
                "search",
                "seo",
                "seo tool"
             ],
            "timestamp": 1391517755
       },
       {
            "keyword": "search engine",
            "tags": [
                "search",
                "seo",
                "seo tool"
             ],
            "timestamp": 1391517755
       }
   ]
}

Price: 100 API units per request

This request returns a list of campaigns in the specified project and basic information about each of them.

To get a list of all your tracking campaigns in the Semrush web interface, refer to the Position Tracking main page.

Request parameters

Name	Value/Type	Description
key*		Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
targets	integer	Number of targets available under the user's subscription.
project_id	string	Project ID.
device	string	Type of SERPs the campaign is set up to track: `desktop`, `phone`, or `tablet`.
engine	string	Search engine.
id	string	Campaign ID.
isGathering	boolean	Whether the campaign is being harvested.
keywords_count	integer	Number of keywords in the campaign.
language	string	Language.
location->code	string	Location code.
location->hl	string	Language code.
location->location_id	integer	Location ID.
location->name	string	Location name.
location->type	string	Location type.
url	string	Tracked URL.
type	string	Tracked URL type.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/management/v1/projects/{projectID}/tracking/campaigns?key=YOUR_API_KEY

Response example

{
    "project_id": "103580023",
    "targets": [
        {
            "id": "103580023_16852",
            "url": "apple.com",
            "type": "rootdomain",
            "engine": "google",
            "location": {
                "name": "San Francisco, California, United States",
                "location_id": 1014221,
                "type": "city",
                "code": "us",
                "hl": "en"
            },
            "isGathering": false,
            "language": "English",
            "device": "desktop",
            "keywords_count": 81
        },
        ...
    ],
    "limits": {
        "targets": 5000
    }
}

Price: 100 API units per request

This request returns a list of country IDs a project can be set up for.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
id	integer	Country ID.
name	string	Country name.
code	string	Country code.
canonical_name	string	Country canonical name.
language->id	integer	Language ID.
language->hl	string	Language code.
language->name	string	Language name.
language->is_default	boolean	Whether the language is default for this location.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/management/v1/info/countries?key=YOUR_API_KEY

Response example

{
  "0": {
    "id": 2826,
    "name": "United Kingdom",
    "code": "GB",
    "canonical_name": "United Kingdom",
    "languages": {
      "0": {
        "id": 4082745666,
        "hl": "en",
        "name": "English",
        "is_default": true
      }
    }
  },
  "1": {
    "id": 2840,
    "name": "United States",
    "code": "US",
    "canonical_name": "United States",
    "languages": {
      "0": {
        "id": 4082745666,
        "hl": "en",
        "name": "English",
        "is_default": true
      },
      "1": {
        "id": 2422189467,
        "hl": "es",
        "name": "Spanish",
        "is_default": false
      }
    }
  },
  "...": "..."
}

Price: 100 API units per request

This request returns a list of regions within the specified country for which a project can be set up for.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
country_id	integer	Country ID.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
id	integer	Region ID.
name	string	Region name.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/management/v1/info/countries/{country_id}/regions?key=YOUR_API_KEY

Response example

{
  "0": {
    "id": 21133,
    "name": "Alabama"
  },
  "1": {
    "id": 21132,
    "name": "Alaska"
  },
  "2": {
    "id": 21136,
    "name": "Arizona"
  },
  "...": "..."
}

Price: 100 API units per request

This request returns a list of cities within the specified country and region for which a project can be set up for.

About the Position Tracking configuration ›

Request parameters

Name	Value/Type	Description
key	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
country_id	integer	Country ID.
region_id	integer	Region ID.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
id	integer	City ID.
name	string	City name.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/management/v1/info/countries/{country_id}/regions/{region_id}/cities?key=YOUR_API_KEY

Response example

{
  "0": {
    "id": 1013370,
    "name": "Ajo"
  },
  "1": {
    "id": 1013371,
    "name": "Alpine"
  },
  "2": {
    "id": 1013372,
    "name": "Amado"
  },
  "...": "..."
}

Price: 100 API units per request

This request returns a list of dates when campaign data was harvested.

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
action*	report
type*	tracking_campaign_dates	Request type.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	Number of results.
last_crawl	integer	Hours elapsed since the last crawl.
Dt	Date in YYYYMMDD format	Date.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_campaign_dates

Response example

{
    "total": "9",
    "last_crawl": "2",
    "data": {
        "0": {
            "Dt": "20140401",
        },
        "1": {
            "Dt": "20140402",
        },
        "2": {
            "Dt": "20140403",
        },
        "3": {
            "Dt": "20140404",
        },
        ...
    }
}

Price: 100 API units per request

This request returns the number of keywords that land the specified domain on each of the top 100 positions on SERP, the number of new and lost keywords, the number of keywords with improved or decreased rankings, and the number of keywords that have changed their rankings over the selected period.

About the Position Tracking Pages report ›

Request parameters

Name	Value/Type	Description
key	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
action	report
type	tracking_overview_organic	Request type.
url	string	Tracked URL or competitor URL (with a mask).
display_tags	string	Tags separated by the `\|` symbol. To exclude a tag, use the `-` symbol. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories.
display_tags_condition	string	A newer variation of the `display_tags` filter. Tags separated by the `\|` symbol (the OR logic) or the `&` symbol (the AND logic). To exclude a tag, use the `!` symbol.
date_begin	Date in YYYYMMDD format	Start date of the selected period.
date_end	Date in YYYYMMDD format	End date of the selected period.
linktype_filter	0 - Include local pack and hotels ranki… 0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotel rankings should be included in the report output or excluded from it.
business_name	string	Business name associated with the domain. It must match the name in Google Business Profile.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	Number of results.
visibility	percentage	Visibility index.
differenceVisibility	percentage	Visibility index difference.
all	integer	Number of keywords ranking in the top 100.
all_difference	integer	Difference in the number of keywords ranking in the top 100.
all_improved	integer	Number of improved keywords in the top 100.
all_declined	integer	Number of declined keywords in the top 100.
all_left	integer	Number of keywords that no longer rank in the top 100.
all_entered	integer	Number of keywords that have entered the top 100.
top3	integer	Number of keywords ranking in the top 3.
top3_improved	integer	Number of improved keywords in the top 3.
top3_declined	integer	Number of declined keywords in the top 3.
top3_difference	integer	Difference in the number of keywords ranking in the top 3.
top3_left	integer	Number of keywords that no longer rank in the top 3.
top3_entered	integer	Number of keywords that have entered the top 3.
top10	integer	Number of keywords ranking on the first page of search results.
top10_improved	integer	Number of improved keywords ranking on the first page of search results.
top10_declined	integer	Number of declined keywords ranking on the first page of search results.
top10_difference	integer	Difference in the number of keywords ranking on the first page of search results.
top10_left	integer	Number of keywords that no longer rank on the first page of search results.
top10_entered	integer	Number of keywords that have entered the first page of search results.
top20	integer	Number of keywords ranking on the first two pages of search results.
top20_improved	integer	Number of improved keywords ranking on the first two pages of search results.
top20_declined	integer	Number of declined keywords ranking on the first two pages of search results.
top20_difference	integer	Difference in the number of keywords ranking on the first two pages of search results.
top20_left	integer	Number of keywords that no longer rank on the first two pages of search results.
top20_entered	integer	Number of keywords that have entered the first two pages of search results
data	array	Array of SERP positions (where `0` stands for the first position on a SERP and `99` stands for the 100th position) and a number of keywords on each position for the end date of the selected period.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_overview_organic&url=*.apple.com%2F*&date_begin=20140405&date_end=20140411&linktype_filter=0

Response example

{
    "total": 199,
    "visibility": 15.9602,
    "differenceVisibility": 1.7159,
    "all": 146,
    "all_improved": 67,
    "all_declined": 32,
    "all_difference": 3,
    "all_left": 3,
    "all_entered": 6,
    "top3": 36,
    "top3_improved": 8,
    "top3_declined": 2,
    "top3_difference": 2,
    "top3_left": 1,
    "top3_entered": 3,
    "top10": 67,
    "top10_improved": 19,
    "top10_declined": 13,
    "top10_difference": 6,
    "top10_left": 1,
    "top10_entered": 7,
    "top20": 97,
    "top20_improved": 36,
    "top20_declined": 19,
    "top20_difference": 10,
    "top20_left": 1,
    "top20_entered": 11,
    "data": {
			0: 47,
			1: 17,
			2: 2,
			...
			99: 0
	}
}

Price: 100 API units per keyword added

This request lists all keywords from a tracking campaign, Google’s top 100 rankings of the specified URLs for these keywords, and position changes over the selected timeframe.

About the Position Tracking Overview report ›

Request parameters

Name	Value/Type	Description
key*	string	Identification key assigned to each user after subscribing to Semrush. You'll find it in Subscription info > API units.
action*	report
type*	tracking_position_organic	Request type.
url*	string	Tracked URL or competitor URL (with a mask).
top_filter	top_3 top_3_income top_3_leave top_3… top_3 top_3_income top_3_leave top_3_down top_3_up top_1page top_1page_income top_1page_leave top_1page_down top_1page_up top_2page top_2page_income top_2page_leave top_2page_down top_2page_up top_100 top_100_income top_100_leave top_100_down top_100_up	Positions filter.
date_begin	Date in YYYYMMDD format	Start date of the selected period.
date_end	Date in YYYYMMDD format	End date of the selected period.
display_tags	string	Tags separated by the `\|` symbol. To exclude a tag, use the `-` symbol. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories.
display_tags_condition	string	A newer variation of the `display_tags` filter. Tags separated by the `\|` symbol (the OR logic) or the `&` symbol (the AND logic). To exclude a tag, use the `!` symbol.
display_filter	string	Filter for the following columns: `Ph`, `Nq`, and `Cp`.
display_limit	integer	Number of returned results. The default value is `10`.
display_offset	integer	Number of lines to skip in the report output.
display_sort	cp_asc cp_desc {DOMAIN_N}_be_asc {DO… cp_asc cp_desc {DOMAIN_N}_be_asc {DOMAIN_N}_be_desc {DOMAIN_N}_diff_asc {DOMAIN_N}_diff_desc {DOMAIN_N}_pos_asc {DOMAIN_N}_pos_desc nq_asc nq_desc ph_asc ph_desc sov_asc sov_desc sovdiff_asc sovdiff_desc {DOMAIN_N}_vd_asc {DOMAIN_N}_vd_desc vi_asc vi_desc	Report sorting.
linktype_filter	0 - Include local pack and hotels ranki… 0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotel rankings should be included in the report output or excluded from it.
use_volume	national regional local	Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used.
business_name	string	Business name associated with the domain. It must match the name in Google Business Profile.
serp_feature_filter	string	Filters the report output for keywords that have a specific SERP feature on a SERP: `adb`: AdWords bottom. `adt`: AdWords top. `amp`: AMP. `app`: Apps block. `flg`: Flights. `fsn`: Featured snippet. `geo`: Local pack. `hot`: Hotels. `img`: Images. `ind`: Indented. `job`: Jobs. `kng`: Knowledge panel. `knw`: Instant answer. `tea`: Local teaser. `new`: Top stories. `rel`: People also ask. `rev`: Reviews. `shp`: Shopping ads. `stl`: Site links. `twt`: Twitter. `vib`: Featured video. `vid`: Video.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
limit	integer	Number of returned results.
offset	integer	Number of lines to skip in the report output.
data	array	Array of landing URLs and their metrics.
Pi	string	Keyword ID.
Ph	string	Keyword the URL ranks for.
Kb	string	The date the keyword was added to the tracking campaign.
Tg	array	Keyword tags.
Cp	float	Average price in the U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords).
Nq	integer	Average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months.
Gs	integer	Volume crawling status: `0`: Crawled. `1`: Not crawled.
Dt	array	Array of dates and positions. Dates are in the `YYYYMMDD` format.
Be	array	Ranking at the beginning of the specified period.
Fi	array	Ranking at the end of the specified period.
Diff	array	Difference in rankings over the specified period.
Diff1	array	Difference in rankings compared to the previous day.
Diff7	array	Difference in rankings over a one week period.
Diff30	array	Difference in rankings over a one month period.
Vi	array	Domain's visibility on the specified date.
Sov	array	Domain's Share of Voice on the specified date.
Sf	array	SERP features present on a SERP for the specified date.
Tr	array	Estimated traffic on the specified date.
Tc	array	Estimated traffic cost on the specified date.
Lu		Landing URLs.
Lt	array	Ranking type: `adb`: AdWords bottom. `adt`: AdWords top. `amp`: AMP. `app`: Apps block. `flg`: Flights. `fsn`: Featured snippet. `geo`: Local pack. `hot`: Hotels. `img`: Images. `ind`: Indented. `job`: Jobs. `kng`: Knowledge panel. `knw`: Instant answer. `tea`: Local teaser. `new`: Top stories. `rel`: People also ask. `rev`: Reviews. `shp`: Shopping ads. `stl`: Site links. `twt`: Twitter. `vib`: Featured video. `vid`: Video.
In	array	Array of intents for the keyword: `i`: Informational. `n`: Navigational. `t`: Transactional. `c`: Commercial.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_position_organic&url=*.apple.com%2F*:*.amazon.com%2F*&date_begin=20210521&date_end=20210527&linktype_filter=0&display_tags=tag1%26!tag2&display_sort=0_pos_asc

Response example

{
  "total": 2,
  "state": "0",
  "limit": 10,
  "offset": 0,
  "data": {
    "0": {
      "Pi": "801444466689038445",
      "Ph": "facebook",
      "Kb": 20170908,
      "Tg": {
        "0": "tag1"
      },
      "In": {
        "0": "i",
        "1": "c"
      },
      "Cp": "1.44",
      "Nq": "185000000",
      "Gs": "0",
      "Dt": {
        "20210521": {
          "*.apple.com/*": 4,
          "*.amazon.com/*": 32
        },
        "...": "...",
        "20210527": {
          "*.apple.com/*": 3,
          "*.amazon.com/*": 38
        }
      },
      "Be": {
        "*.apple.com/*": 4,
        "*.amazon.com/*": 32
      },
      "Fi": {
        "*.apple.com/*": 3,
        "*.amazon.com/*": 38
      },
      "Diff": {
        "*.apple.com/*": 1,
        "*.amazon.com/*": -6
      },
      "Diff1": {
        "*.apple.com/*": 0,
        "*.amazon.com/*": -10
      },
      "Diff7": {
        "*.apple.com/*": 97,
        "*.amazon.com/*": 62
      },
      "Diff30": {
        "*.apple.com/*": 97,
        "*.amazon.com/*": 62
      },
      "Vi": {
        "20210521": {
          "*.apple.com/*": 10.8516,
          "*.amazon.com/*": 1.0714
        },
        "...": "...",
        "20210527": {
          "*.apple.com/*": 13.0494,
          "*.amazon.com/*": 0.9065
        },
        "Diff": {
          "*.apple.com/*": 2.1978,
          "*.amazon.com/*": -0.1649
        }
      },
      "Sov": {
        "20210521": {
          "*.apple.com/*": 0.02,
          "*.amazon.com/*": 0.07
        },
        "...": "...",
        "20210527": {
          "*.apple.com/*": 0.03,
          "*.amazon.com/*": 0.05
        },
        "Diff": {
          "*.apple.com/*": 0.01,
          "*.amazon.com/*": -0.02
        }
      },
      "Sf": {
        "20210521": [
          "new",
          "twt",
          "rev",
          "stl",
          "kng"
        ],
        "...": "...",
        "20210527": [
          "new",
          "twt",
          "rev",
          "stl",
          "kng"
        ]
      },
      "Tr": {
        "20210521": {
          "*.apple.com/*": 487166.66,
          "*.amazon.com/*": 48100
        },
        "...": "...",
        "20210527": {
          "*.apple.com/*": 585833.33,
          "*.amazon.com/*": 40700
        }
      },
      "Tc": {
        "20210521": {
          "*.apple.com/*": 701520,
          "*.amazon.com/*": 69264
        },
        "...": "...",
        "20210527": {
          "*.apple.com/*": 843600,
          "*.amazon.com/*": 58608
        }
      },
      "Lu": {
        "20210521": {
          "*.apple.com/*": "https://apps.apple.com/us/app/facebook/id284882215",
          "*.amazon.com/*": "https://www.amazon.com/Facebook/dp/B0094BB4TW"
        },
        "...": "...",
        "20210527": {
          "*.apple.com/*": "https://apps.apple.com/us/app/facebook/id284882215",
          "*.amazon.com/*": "https://www.amazon.com/Facebook/dp/B0094BB4TW"
        }
      },
      "Lt": {
        "20210521": {
          "*.apple.com/*": [
            "rev"
          ],
          "*.amazon.com/*": [
            "rev"
          ]
        },
        "...": "...",
        "20210527": {
          "*.apple.com/*": [
            "rev"
          ],
          "*.amazon.com/*": [
            "rev"
          ]
        }
      }
    },
    "...": "..."
  }
}

Price: 100 API units per line

This request lists all keywords from a tracking campaign, the Google’s paid search rankings of the specified URLs for these keywords, and position changes over the selected time period.

Request parameters

Name	Value/Type	Description
key*	string	An identification key assigned to a user after subscribing to SEMrush that is available via Profile page
action*	report
type*	tracking_position_adwords	Request type
url*	string	Tracked URL or competitor URL (with mask)
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories.
display_tags_condition	string	This is a newer variation of the `display_tags` filter. Tags, separated by the '\|' symbol (the OR logic) or the '&' symbol (the AND logic). The '!' sign can be used to exclude a tag.
display_filter	string	Filter for columns Ph, Nq, Cp
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	cp_asc cp_desc {DOMAIN_N}_be_asc {DO… cp_asc cp_desc {DOMAIN_N}_be_asc {DOMAIN_N}_be_desc {DOMAIN_N}_di_asc {DOMAIN_N}_di_desc {DOMAIN_N}_pos_asc {DOMAIN_N}_pos_desc nq_asc nq_desc ph_asc ph_desc	Report sorting

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
data	array	An array of landing URLs and their metrics
Pi	string	Keyword ID
Ph	string	A keyword the URL ranks for
Kb	string	The date the keyword was added to the tracking campaign
Tg	array	Keyword tags
Cp	float	Average price in U.S. dollars advertisers pay for a user’s click on an ad containing the given keyword (Google AdWords).
Nq	integer	The average number of times users have searched for a given keyword per month. We calculate this value over the last 12 months.
Gs	integer	Volume crawling status; 0 - crawled, 1 - not crawled
Dt	array	An array of dates and positions (dates in format "YYYYMMDD")
Be	array	Ranking at the beginning of the specified period
Fi	array	Ranking at the end of the specified period
Diff	array	The difference in rankings over the specified period
Diff1	array	The difference in rankings compared to the previous day
Diff7	array	The difference in rankings over a one week period
Diff30	array	The difference in rankings over a one month period
Vi	array	Domain's visibility on the specified date
Sf	array	Serp features present on SERP for the specified date
Tr	array	Estimated traffic on the specified date
Tc	array	Estimated traffic cost on the specified date
Lu		Landing URLs
Lt	array	Ranking type org: Organic adt: AdWords top adb: AdWords bottom

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_position_adwords&url=*.apple.com%2F*:*.walmart.com%2F*&date_begin=20210522&date_end=20210528&display_sort=0_pos_asc&display_tags_condition=tag1%26!tag2

Response example

{
  "total": 4,
  "state": "0",
  "limit": 10,
  "offset": 0,
  "data": {
    "0": {
      "Pi": "5331787400075558242",
      "Ph": "appl",
      "Kb": 20170908,
      "Tg": {
        "0": "tag2"
      },
      "Cp": "1.00",
      "Nq": "165000",
      "Gs": "0",
      "Dt": {
        "20210522": {
          "*.apple.com/*": "-",
          "*.walmart.com/*": "-"
        },
        "...": "...",
        "20210528": {
          "*.apple.com/*": 1,
          "*.walmart.com/*": "-"
        }
      },
      "Be": {
        "*.apple.com/*": "-",
        "*.walmart.com/*": "-"
      },
      "Fi": {
        "*.apple.com/*": 1,
        "*.walmart.com/*": "-"
      },
      "Diff": {
        "*.apple.com/*": 11,
        "*.walmart.com/*": "-"
      },
      "Diff1": {
        "*.apple.com/*": 0,
        "*.walmart.com/*": "-"
      },
      "Diff7": {
        "*.apple.com/*": 11,
        "*.walmart.com/*": "-"
      },
      "Diff30": {
        "*.apple.com/*": 11,
        "*.walmart.com/*": "-"
      },
      "Vi": {
        "20210522": {
          "*.apple.com/*": 0,
          "*.walmart.com/*": 0
        },
        "...": "...",
        "20210528": {
          "*.apple.com/*": 25,
          "*.walmart.com/*": 0
        },
        "Diff": {
          "*.apple.com/*": 25,
          "*.walmart.com/*": 0
        }
      },
      "Sf": {
        "20210522": [
          "new",
          "knw",
          "stl",
          "kng"
        ],
        "...": "...",
        "20210528": [
          "new",
          "rel",
          "adt",
          "knw",
          "rev",
          "stl",
          "kng"
        ]
      },
      "Tr": {
        "20210522": {
          "*.apple.com/*": 0,
          "*.walmart.com/*": 0
        },
        "...": "...",
        "20210528": {
          "*.apple.com/*": 5500,
          "*.walmart.com/*": 0
        }
      },
      "Tc": {
        "20210522": {
          "*.apple.com/*": 0,
          "*.walmart.com/*": 0
        },
        "...": "...",
        "20210528": {
          "*.apple.com/*": 5500,
          "*.walmart.com/*": 0
        }
      },
      "Lu": {
        "20210522": {
          "*.apple.com/*": "",
          "*.walmart.com/*": ""
        },
        "...": "...",
        "20210528": {
          "*.apple.com/*": "https://www.apple.com/",
          "*.walmart.com/*": ""
        }
      },
      "Lt": {
        "20210522": {
          "*.apple.com/*": [
            "org"
          ],
          "*.walmart.com/*": [
            "org"
          ]
        },
        "...": "...",
        "20210528": {
          "*.apple.com/*": [
            "adt"
          ],
          "*.walmart.com/*": [
            "org"
          ]
        }
      }
    }
  }
}

Price: 1000 API units per competitor

This request lists the domains that appear in Google's top 100 organic search results for the keywords from a tracking campaign for the chosen location, the average position, and visibility for these domains.

About the Competitors Discovery report ›

Request parameters

Name	Value/Type	Description
key*	string	An identification key assigned to a user after subscribing to Semrush that is available via the Profile page
action*	report
type*	tracking_competitors_organic	Request type
url_type	rootdomain subdomain subfolder url	Type of competitor URLs. If omitted, the value from the campaign's settings is used.
main_domain	string	The domain URL (without a mask) that will have its data displayed in a special block at the top of the competitors list in the response.
black_list	string	Exclude domains from the report output (separated by the '\|' symbol).
top_start	integer	The top of the position range to search for competitors on SERP.
top_end	integer	The bottom of the position range to search for competitors on SERP.
date_begin	Date in YYYYMMDD format	Start date of the selected period.
date_end	Date in YYYYMMDD format	End date of the selected period.
display_limit	integer	The number of returned results, the default value is 10.
display_offset	integer	The number of lines to skip in the report output.
display_sort	av_asc av_desc cd_asc cd_desc cl_as… av_asc av_desc cd_asc cd_desc cl_asc cl_asc {DATE}_asc {DATE}_desc ur_asc ur_desc	Report sorting.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	The number of results.
limit	integer	The number of returned results.
offset	integer	The number of lines to skip in the report output.
keywords_count	integer	The number of keywords used to build this report.
data	array	An array of competitor domains and their metrics.
Dt	array	Dates and positions (Date in YYYYMMDD format).
Mc	integer	The number of keywords.
Av	float	Average position.
Sq	integer	Position deviation.
Cl	float	Visibility.
Sov	float	Share of Voice.
Tr	float	Estimated traffic on the specified date.
Tc	float	Estimated traffic cost on the specified date.
Cd	float	Visibility change over the specified period.
Ur	string	Competitor URL.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_competitors_organic&date_begin=20210518&date_end=20210524&top_start=1&top_end=10&url_type=rootdomain&linktype_filter=0&display_sort=20210524_desc&main_domain=apple.com

Response example

{
  "Md": {
    "Dt": {
        "20210518": {
            "Mc": 58,
            "Av": 30.666667,
            "Sq": 43,
            "Cl": 33.889567,
            "Sov": 31.962638999999999,
            "Tr": 53941.550000000003,
            "Tc": 44413.093072999996
        },
        "20210524": {
            "Mc": 57,
            "Av": 31.950617000000001,
            "Sq": 44,
            "Cl": 33.245150000000002,
            "Sov": 6.3006149999999996,
            "Tr": 9495.7073330000003,
            "Tc": 11272.560507
        },
        "Diff": {
           "Mc": -1,
           "Av": 1.2839500000000008,
           "Sq": 1,
           "Cl": -0.64441699999999713,
           "Sov": -25.662023999999999,
           "Tr": -44445.842667000004,
           "Tc": -33140.532565999994
        }
    },
    "Cd": -0.64441699999999713,
    "Ur": "apple.com",
    "Ps": 73
   },
   "total":560,
   "state":"0",
   "limit":100,
   "offset":0,
   "keywords_count":200,
   "data":{
      "0":{
         "Dt":{
            "20210518":{
               "Mc":0,
               "Av":100,
               "Sq":0,
               "Cl":0,
               "Sov":0,
               "Tr":"n/a",
               "Tc":"n/a"
            },
            "20210524":{
               "Mc":1,
               "Av":99.545,
               "Sq":6,
               "Cl":0.04120879120879121,
               "Sov":0.000013038870213554158,
               "Tr":8.1,
               "Tc":9.072
            },
            "Diff":{
               "Mc":1,
               "Av":-0.455,
               "Sq":6,
               "Cl":0.04120879120879121,
               "Sov":0.000013038870213554158,
               "Tr":8.1,
               "Tc":9.072
            }
         },
         "Cd":0.04120879120879121,
         "Ur":"android.com"
      },
      ...
   }
}

Price: 1000 API units per competitor

This request lists the domains that appear in Google's paid search results for the keywords from a tracking campaign for the chosen location, the average position, and visibility for these domains.

About the Competitors Discovery report ›

Request parameters

Name	Value/Type	Description
key*	string	An identification key assigned to a user after subscribing to Semrush that is available via the Profile page.
action*	report
type*	tracking_competitors_adwords	Request type.
url_type	rootdomain subdomain subfolder url	Type of competitor URLs. If omitted, the value from the campaign's settings is used.
main_domain	string	The domain URL (without a mask) that will have its data displayed in a special block at the top of the competitors list in the response.
black_list	string	Exclude domains from the report output (separated by the '\|' symbol).
top_start	integer	The top of the position range to search for competitors on SERP.
top_end	integer	The bottom of the position range to search for competitors on SERP.
date_begin	Date in YYYYMMDD format	Start date of the selected period.
date_end	Date in YYYYMMDD format	End date of the selected period.
display_limit	integer	The number of returned results, the default value is 10.
display_offset	integer	The number of lines to skip in the report output.
display_sort	av_asc av_desc cd_asc cd_desc cl_as… av_asc av_desc cd_asc cd_desc cl_asc cl_asc {DATE}_asc {DATE}_desc ur_asc ur_desc	Report sorting.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	The number of results.
limit	integer	The number of returned results.
offset	integer	The number of lines to skip in the report output.
keywords_count	integer	The number of keywords used to build this report.
data	array	An array of competitor domains and their metrics.
Dt	array	Dates and positions (Date in YYYYMMDD format).
Mc	integer	The number of keywords.
Av	float	Average position.
Sq	integer	Position deviation.
Cl	float	Visibility.
Sov	float	Share of Voice.
Tr	float	Estimated traffic on the specified date.
Tc	float	Estimated traffic cost on the specified date.
Cd	float	Visibility change over the specified period.
Ur	string	Competitor URL.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_competitors_adwords&date_begin=20210518&date_end=20210524&top_start=1&top_end=10&url_type=rootdomain&display_sort=20210524_desc&main_domain=apple.com

Response example

{
  "Md": {
    "Dt": {
        "20210518": {
            "Mc": 4,
            "Av": 11.45679,
            "Sq": 2,
            "Cl": 4.9382720000000004,
            "Sov": 1.3998269999999999,
            "Tr": 2416.666667,
            "Tc": 4625.1666670000004
        },
        "20210524": {
            "Mc": 2,
            "Av": 11.728395000000001,
            "Sq": 1,
            "Cl": 2.4691360000000002,
            "Sov": 0.92485099999999998,
            "Tr": 1596.666667,
            "Tc": 3659.166667
        },
        "Diff": {
            "Mc": -2,
            "Av": 0.27160500000000098,
            "Sq": -1,
            "Cl": -2.4691360000000002,
            "Sov": -0.47497599999999995,
            "Tr": -820,
            "Tc": -966.00000000000045
        }
    },
    "Cd": -2.4691360000000002,
    "Ur": "apple.com",
    "Ps": 5
  },
  "total":45,
  "state":"0",
  "limit":10,
  "offset":0,
  "keywords_count":200,
  "data":{
    "0":{
      "Dt":{
        "20210518":{
          "Mc":22,
          "Av":10.8,
          "Sq":3,
          "Cl":11,
          "Sov":1.0137587446283074,
          "Tr":629766.6666666666,
          "Tc":687222.3333333335
        },
        "20210524":{
          "Mc":16,
          "Av":11.13,
          "Sq":2,
          "Cl":8,
          "Sov":0.8335755093315385,
          "Tr":517833.3333333334,
          "Tc":515993.66666666657
        },
        "Diff":{
          "Mc":-6,
          "Av":0.33,
          "Sq":0,
          "Cl":-3,
          "Sov":-0.1801832352967689,
          "Tr":-111933.33333333326,
          "Tc":-171228.66666666692
        }
      },
      "Cd":-3,
      "Ur":"apple.com"
    },
    ...
  }
}

Price: 100 API units per request

This request returns a domain's visibility and visibility changes over the selected period.

About the Position Tracking Landscape report ›

Request parameters

Name	Value/Type	Description
key*	string	An identification key assigned to a user after subscribing to Semrush that is available via the Profile page
action*	report
type*	tracking_visibility_organic	Request type
url*	string	Tracked URL or competitor URL (with mask)
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '`\|`' symbol. The '`-`' symbol can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories.
display_tags_condition	string	This is a newer variation of the `display_tags` filter. Tags, separated by the '`\|`' symbol (the OR logic) or the '`&`' symbol (the AND logic). The '`!`' symbol can be used to exclude a tag.
display_filter	string	Filter for the Ph, Nq, Cp columns.
linktype_filter	0 - Include local pack and hotels ranki… 0 - Include local pack and hotels rankings. This is the default value 1 - Include only local pack and hotels rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotels rankings	Specifies whether the local pack and hotel rankings should be included in the report output or excluded from it
use_volume	national regional local	Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used
business_name	string	The business name associated with the domain. It should match the name from the Google My Business profile
serp_feature_filter	fsn: Featured snippet geo: Local pac… fsn: Featured snippet geo: Local pack hot: Hotels kng: Knowledge panel rev: Reviews amp: AMP stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer flg: Flights shp: Shopping ads adt: AdWords top adb: AdWords bottom job: Jobs ind: Indented	Filters the report output for keywords that have a specific SERP feature on the SERP

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	The number of results
data	array	An array of dates and a domain's metrics on them
Dt	Date in YYYYMMDD format	Date
Vi	float	Absolute visibility value
Vr	float	Relative visibility value
Av	float	Average position
Sov	float	Share of Voice
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_visibility_organic&date_begin=20210518&date_end=20210524&url=*.apple.com%2F*&linktype_filter=0

Response example

{
  "total": "7",
  "state": "0",
  "data": {
    "0": {
      "Dt": "20210518",
      "Vi": 33397900,
      "Vr": 45.8762,
      "Av": 8.075,
      "Sov": 5.89,
      "Tr": 3258225.0324,
      "Tc": 9745148.8893
    },
    "...": "...",
    "6": {
      "Dt": "20210524",
      "Vi": 32230100,
      "Vr": 44.2721,
      "Av": 8.165,
      "Sov": 5.55,
      "Tr": 3230495.1761,
      "Tc": 9866793.9995
    }
  }
}

Price: 100 API units per request

This report returns a domain's visibility and visibility changes over the selected period.

About the Position Tracking Landscape report ›

Request parameters

Name	Value/Type	Description
key*	string	An identification key assigned to a user after subscribing to Semrush that is available via the Profile page
action*	report
type*	tracking_visibility_adwords	Request type
url*	string	Tracked URL or competitor URL (with mask)
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '`\|`' symbol. The '`-`' symbol can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories.
display_tags_condition	string	This is a newer variation of the `display_tags` filter. Tags, separated by the '`\|`' symbol (the OR logic) or the '`&`' symbol (the AND logic). The '`!`' symbol can be used to exclude a tag.
display_filter	string	Filter for the Ph, Nq, Cp columns

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	The number of results
data	array	An array of dates and a domain's metrics on them
Dt	Date in YYYYMMDD format	Date
Vi	float	Absolute visibility value
Vr	float	Relative visibility value
Av	float	Average position
Sov	float	Share of Voice
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_visibility_adwords&date_begin=20140401&date_end=20140411&url=*.apple.com%2F*

Response example

{
  "total": "7",
  "state": "0",
  "data": {
    "0": {
      "Dt": "20210518",
      "Vi": 23000000,
      "Vr": 11.5,
      "Av": 10.745,
      "Sov": 1.11,
      "Tr": 690766.666,
      "Tc": 815932.3328
    },
    "...": "...",
    "6": {
      "Dt": "20210524",
      "Vi": 16000000,
      "Vr": 8,
      "Av": 11.13,
      "Sov": 0.83,
      "Tr": 517833.3329,
      "Tc": 515993.6663
    }
  }
}

Price: 1000 API units per landing page

This request lists all URLs from the Google's top 100 search results that the specified domain appears in for the keywords from the tracking campaign.

About the Position Tracking Pages report ›

Request parameters

Name	Value/Type	Description
key	string	An identification key assigned to a user after subscribing to Semrush that is available on the Profile page.
action	report
type	tracking_landing_pages_organic	Request type.
url	string	Tracked URL or competitor URL (without a mask).
date_begin	Date in YYYYMMDD format	Start date of the selected period.
date_end	Date in YYYYMMDD format	End date of the selected period.
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories.
display_tags_condition	string	This is a newer variation of the `display_tags` filter. Tags, separated by the '\|' symbol (the OR logic) or the '&' symbol (the AND logic). The '!' sign can be used to exclude a tag.
display_filter	string	Filter for the Ph, Nq, and Cp columns.
display_limit	integer	Number of returned results. Default value is 10.
display_offset	integer	Number of lines to skip in the report output.
display_sort	0_mc_asc 0_mc_desc 1_mc_asc 1_mc_des… 0_mc_asc 0_mc_desc 1_mc_asc 1_mc_desc md_asc md_desc 0_tr_asc 0_tr_desc 1_tr_asc 1_tr_desc trdiff_asc trdiff_desc 0_av_asc 0_av_desc 1_av_asc 1_av_desc ad_asc ad_desc 0_nq_asc 0_nq_desc 1_nq_asc 1_nq_desc rd_asc rd_desc	Report sorting.
newlost_filter	new, lost	Return only new or lost URLs.
linktype_filter	0 - Include local pack and hotels ranki… 0 - Include local pack and hotels rankings. Default value. 1 - Include only local pack and hotels rankings (organic rankings are excluded). 2 - Exclude local pack rankings. 524288 - Exclude hotels rankings. 524290 - Exclude local pack and hotels rankings.	Specifies whether the local pack and hotels rankings should be included in the report output or excluded from it
use_volume	national regional local	Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	Number of results.
limit	integer	Number of returned results.
offset	integer	Number of lines to skip in the report output.
new	integer	Number of new URLs (URLs that didn't rank for any keyword on the start date of the selected period, but rank for at least one keyword on the end date of the selected period).
lost	integer	Number of lost URLs (URLs that ranked for at least one keyword on the start date of the selected period, but don't rank for any keyword on the end date of the selected period).
keywords	integer	Number of keywords used to build this report.
Pc	integer	Number of HTTP and HTTPS URLs.
data	array	Array of landing URLs and their metrics.
Ur	string	URL that ranks for the keyword.
Tp	new, lost	"new": the URL didn't rank for any keyword on the start date of the selected period, but ranks for at least one keyword on the end date of the selected period. "lost": the URL ranked for at least one keyword on the start date of the selected period, but doesn't rank for any keyword on the end date of the selected period.
Mc	integer	Number of keywords the URL ranks for on the specified date.
Av	float	Average position for the keywords the URL ranks for on the specified date
Tr	float	Estimated traffic on the specified date.
Tc	float	Estimated traffic cost on the specified date.
Rq	integer	Total volume for the keywords the URL ranks for on the specified date.
Kw	array	List of keywords the URL ranks for.
Pi	string	Keyword ID.
Ph	string	Keyword the URL ranks for.
Kw -> Tp	new, lost	"new": the URL didn't rank for this keyword on the start date of the selected period, but ranks for this keyword on the end date of the selected period "lost": the URL ranked for this keyword on the start date of the selected period, but doesn't rank this keyword on the end date of the selected period>
Rq	integer	Keyword volume.
Gs	integer	Volume crawling status where 0 is crawled, and 1 is not crawled.
Tg	array	Keyword tags.
Kw -> Dt	array	Array of dates and positions.
Lt	array	Ranking type: fsn: Featured snippet geo: Local pack hot: Hotels kng: Knowledge panel rev: Reviews amp: AMP stl: Site links vid: Video vib: Featured video new: Top stories rel: People also ask img: Images twt: Twitter knw: Instant answer flg: Flights shp: Shopping ads adt: AdWords top adb: AdWords bottom job: Jobs ind: Indented
Kw -> In	array	Array of intents for the keyword: i: informational n: navigational t: transactional c: commercial
Dt -> [date] -> In	array	List of intents for the URL. Four items for each intent. Kc: keywords count Tr: traffic Kp: percent Na: name of intent (i for informational, n for navigational, t for transactional, c for commercial)

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_landing_pages_organic&date_begin=20210518&date_end=20210524&url=apple.com&linktype_filter=0&display_sort=1_mc_desc

Response example

{
  "total":310,
  "state":"0",
  "limit":100,
  "offset":0,
  "new":34,
  "lost":32,
  "keywords":200,
  "Pc":{
    "http":2,
    "https":308
  },
  "data":{
    "0":{
      "Ur":"https://apps.apple.com/us/app/zillow-real-estate-rentals/id310738695",
      "Tp":"",
      "Dt":{
        "20210518":{
          "Mc":1,
          "Av":3,
          "Tr":52566.666666666664,
          "Tc":9987.666666666666,
          "Rq":16600000,
           "In": [
              {
                "Kc": 1,
                "Tr": 269.36,
                "Kp": 50,
                "Na": "i"
              },
              {
                "Kc": 0,
                "Tr": 0,
                "Kp": 0,
                "Na": "n"
              },
              {
                "Kc": 1,
                "Tr": 269.36,
                "Kp": 50,
                "Na": "t"
              },
              {
                "Kc": 0,
                "Tr": 0,
                "Kp": 0,
                "Na": "c"
              }
          ]
        },
        "20210524":{
          "Mc":1,
          "Av":4,
          "Tr":43713.333333333336,
          "Tc":8305.533333333333,
          "Rq":16600000,
           "In": [
              {
                "Kc": 1,
                "Tr": 269.36,
                "Kp": 50,
                "Na": "i"
              },
              {
                "Kc": 0,
                "Tr": 0,
                "Kp": 0,
                "Na": "n"
              },
              {
                "Kc": 1,
                "Tr": 269.36,
                "Kp": 50,
                "Na": "t"
              },
              {
                "Kc": 0,
                "Tr": 0,
                "Kp": 0,
                "Na": "c"
              }
           ]
        },
        "Diff":{
          "Mc":0,
          "Av":-1,
          "Tr":-8853.333333333328,
          "Tc":-1682.1333333333332,
          "Rq":0,
           "In": [
              {
                "Kc": 0,
                "Tr": -176.86,
                "Na": "i"
              },
              {
                "Kc": 0,
                "Tr": 0,
                "Na": "n"
              }
           ]
        }
      },
      "Kw":[
        {
          "Pi":"5243708147689083041",
          "Ph":"zillow",
          "Tp":"",
          "Rq":16600000,
          "Gs":1,
          "Tg":{
            
          },
          "In": {
            "0": "i",
            "1": "t"
         },
          "Dt":{
            "20210518":3,
            "20210524":4,
            "Diff":-1
          },
          "Tr":{
            "20210518":52566.666666666664,
            "20210524":43713.333333333336,
            "Diff":-8853.333333333328
          },
          "Tc":{
            "20210518":9987.666666666666,
            "20210524":8305.533333333333,
            "Diff":-1682.1333333333332
          },
          "Lt":{
            "20210518":[
              "rev"
            ],
            "20210524":[
              "rev"
            ]
          }
        }
      ],
      "Amp":0
    },
    ...
  }

Price: 1000 API units per landing page

This request lists all URLs from the Google paid search results that the specified domain appears in for the keywords from the tracking campaign.

About the Position Tracking Pages report ›

Request parameters

Name	Value/Type	Description
key	string	An identification key assigned to a user after subscribing to Semrush that is available via Profile page
action	report
type	tracking_landing_pages_adwords	Request type
url	string	Tracked URL or competitor URL (with mask)
date_begin	Date in YYYYMMDD format	Start date of the selected period
date_end	Date in YYYYMMDD format	End date of the selected period
display_tags	string	Tags, separated by the '\|' symbol. The '-' sign can be used to exclude a tag. If only the included tags are present in the expression, then the OR logic is used to group them. If both included and excluded tags are present, then each category is grouped using the OR logic, but then the AND logic is used to join the categories.
display_tags_condition	string	This is a newer variation of the `display_tags` filter. Tags, separated by the '\|' symbol (the OR logic) or the '&' symbol (the AND logic). The '!' sign can be used to exclude a tag.
display_filter	string	Filter for columns Ph, Nq, Cp
display_limit	integer	The number of returned results, the default value is 10
display_offset	integer	The number of lines to skip in the report output
display_sort	0_mc_asc, 0_mc_desc, 1_mc_asc, 1_mc_des… 0_mc_asc, 0_mc_desc, 1_mc_asc, 1_mc_desc, md_asc, md_desc, 0_tr_asc, 0_tr_desc, 1_tr_asc, 1_tr_desc, trdiff_asc, trdiff_desc, 0_av_asc, 0_av_desc, 1_av_asc, 1_av_desc, ad_asc, ad_desc, 0_nq_asc, 0_nq_desc, 1_nq_asc, 1_nq_desc, rd_asc, rd_desc,	Report sorting
newlost_filter	new, lost	Return only new or lost urls

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
total	integer	The number of results
limit	integer	The number of returned results
offset	integer	The number of lines to skip in the report output
new	integer	The number of new URLs (URLs that didn't rank for any keyword on the start date of the selected period, but rank for at least one keyword on the end date of the selected period)
lost	integer	The number of lost URLs (URLs that ranked for at least one keyword on the start date of the selected period, but don't rank for any keyword on the end date of the selected period)
keywords	integer	The number of keywords used to build this report
Pc	integer	The number of http and https URLs
data	array	An array of landing URLs and their metrics
Ur	string	The URL that the keyword ranks for
Tp	new, lost	"new" - the URL didn't rank for any keyword on the start date of the selected period, but ranks for at least one keyword on the end date of the selected period "lost" - the URL ranked for at least one keyword on the start date of the selected period, but doesn't rank for any keyword on the end date of the selected period
Mc	integer	The number of keywords the URL ranks for on the specified date
Av	float	The average position for the keywords the URL ranks for on the specified date
Tr	float	Estimated traffic on the specified date
Tc	float	Estimated traffic cost on the specified date
Rq	integer	Total volume for the keywords the URL ranks for on the specified date
Kw	array	A list of keywords the URL ranks for
Pi	string	Keyword ID
Ph	string	A keyword the URL ranks for
Kw -> Tp	new, lost	"new" - the URL didn't rank for this keyword on the start date of the selected period, but ranks for this keyword on the end date of the selected period "lost" - the URL ranked for this keyword on the start date of the selected period, but doesn't rank this keyword on the end date of the selected period>
Rq	integer	Keyword volume
Gs	integer	Volume crawling status; 0 - crawled, 1 - not crawled
Tg	array	Keyword tags
Kw -> Dt	array	An array of dates and positions
Lt	array	Ranking type - org: Organic - adt: AdWords top - adb: AdWords bottom

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/

Request example

GET /?key=YOUR_API_KEY&action=report&type=tracking_landing_pages_adwords&date_begin=20210518&date_end=20210524&url=*.apple.com%2F*&linktype_filter=0&display_sort=1_mc_desc

Response example

{
  "total":4,
  "state":"0",
  "limit":500,
  "offset":0,
  "new":0,
  "lost":2,
  "keywords":200,
  "Pc":{
    "http":0,
    "https":3
  },
  "data":{
    "0":{
      "Ur":"https://music.apple.com/",
      "Tp":"lost",
      "Dt":{
        "20210518":{
          "Mc":1,
          "Av":1,
          "Tr":18333.333333333332,
          "Tc":30433.333333333332,
          "Rq":550000
        },
        "20210524":{
          "Mc":0,
          "Av":"-",
          "Tr":0,
          "Tc":0,
          "Rq":0
        },
        "Diff":{
          "Mc":-1,
          "Av":-11,
          "Tr":-18333.333333333332,
          "Tc":-30433.333333333332,
          "Rq":-550000
        }
      },
      "Kw":[
        {
          "Pi":"11540482552829684149",
          "Ph":"apple music",
          "Tp":"lost",
          "Rq":550000,
          "Gs":1,
          "Tg":{
            
          },
          "Dt":{
            "20210518":1,
            "20210524":"-",
            "Diff":-11
          },
          "Tr":{
            "20210518":18333.333333333332,
            "20210524":0,
            "Diff":-18333.333333333332
          },
          "Tc":{
            "20210518":30433.333333333332,
            "20210524":0,
            "Diff":-30433.333333333332
          },
          "Lt":{
            "20210518":[
              "adt"
            ],
            "20210524":[
              
            ]
          }
        }
      ],
      "Amp":0
    },
    ...
  }
}

Position Tracking

Basic doc

About Position Tracking API

Project and campaign IDs

Formatting

Sortings

Filters

Create a Position Tracking campaign in a project

Request parameters

Enable email-sending containing tracking campaign statistics

Request parameters

Disable email-sending containing tracking campaign statistics

Request parameters

Add keywords to an existing tracking campaign

Request parameters

Response parameters

Remove keywords from an existing tracking campaign

Request parameters

Response parameters

Add tags to keywords in an existing tracking campaign

Request parameters

Response parameters

Remove tags from keywords in an existing project

Request parameters

Response parameters

Add competitors to an existing tracking campaign

Request parameters

Response parameters

Remove competitors from an existing tracking campaign

Request parameters

Response parameters

Get a list of campaigns

Request parameters

Response parameters

Get a list of countries

Request parameters

Response parameters

Get a list of regions

Request parameters

Response parameters

Get a list of cities

Request parameters

Response parameters

Campaign dates

Request parameters

Response parameters

Organic overview

Request parameters

Response parameters

Organic positions report

Request parameters

Response parameters

Adwords positions report

Request parameters

Response parameters

Organic competitors discovery report

Request parameters

Response parameters

Adwords competitors discovery report

Request parameters

Response parameters

Organic visibility index report

Request parameters

Response parameters

Adwords visibility index report

Request parameters

Response parameters

Organic landing pages report

Request parameters

Response parameters

Adwords landing pages report

Request parameters

Response parameters