Position Tracking

Jump to Basic docBasic doc

Jump to About Position Tracking APIAbout Position Tracking API

The Position Tracking API lets you monitor keyword rankings, visibility, and competitors’ performance across search engines and locations. It provides access to ranking data for specific keywords, devices, and regions.

Learn more about Position Tracking ›

Jump to MethodsMethods

The Position Tracking API methods require you to replace the {campaignID} placeholder in the method URL with your campaign ID. Learn how to get your campaign ID ›

The Position Tracking API methods are divided into three groups:

  • Management
  • Available regions
  • Reports

Management

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

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

Available regions

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

Base URL
HTTP
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.

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

Jump to URL parameter maskURL parameter mask

Use a proper mask in requests with the url parameter:

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

In some requests, such as Organic landing pages report, Organic competitors discovery report, or Adwords competitors discovery report, you need to specify a URL without a mask. For example, the url parameter for the rootdomain URL type will be ebay.com.

Jump to URL encodingURL encoding

Encode parameter values containing special characters such as / in the URL. Learn more in the Encode special characters section on the Construct your API call page.

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.

Jump to TagsTags

All tags used in either campaign update or filter parameters are sanitized before use following these rules:

  • Any characters other than letters, digits, spaces, or specific allowed symbols, such as .,&,-,$,+,', and #, are removed.
  • Sequences of two or more spaces are replaced with a single space.
  • Three or more underscores in a row are replaced with two underscores.
  • Underscores at the beginning or end of tags are trimmed.
  • All tags are converted to lowercase and spaces are trimmed.

Jump to SortingsSortings

{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

Jump to FiltersFilters

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 filter
HTTP
display_filter=+|Ph|Co|phone|+|Nq|Gt|10000|+|Cp|Gt|2
Example filter encoded for adding it to a request
HTTP
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 USD that the advertisers pay for a user’s click on an ad containing the given keyword (Google Ads). Nq: Average number of times users have searched for a given keyword per month. The value is calculated over the last 12 months.
operation
For metrics fields: Eq, Gt, Lt For text fields: Bw, Ew, Eq, Co
For metrics fields: Eq: Exactly matching Gt: Greater than Lt: Less than For text fields: Bw: Begins with Ew: Ends with Eq: Exactly matching Co: Containing
value
string
Value to filter for.

Jump to SERP FeaturesSERP Features

The table provides a list of supported SERP features with their letter-based codes and descriptions.

Code
Name
Description
aai
Ask AI
An AI-generated response.
adb
Google Ads bottom
A series of ads that appear at the bottom of the first search results page.
adt
Google Ads top
A series of ads that appear at the top of the first search results page.
aic
AI chat
An AI-generated chat response.
aim
AI summary
A brief AI-generated summary.
aio
AI overview
A summarized AI-generated overview.
ais
AI stories
AI-generated stories.
amp
AMP
Pages that are more mobile-friendly. Google doesn’t distinguish them from other search results.
app
Apps block
A block that displays apps among organic search results.
asr
AI search results
A block that contains links used by Google AI to generate the answer.
car
Organic carousel
A row of horizontally scrollable images displayed at the top of search results.
ctt
Citations
A block that contains links referenced by ChatGPT in its quotes.
drp
Double response
A block that contains two ChatGPT answers for selection.
flg
Flights
A block that displays flights related to a search query. Flight results include information on flight dates, duration, the number of transfers and prices. Data is taken from Google Flights.
fsn
Featured snippet
A short answer to a user’s search query with a link to the third-party website it is taken from that appears at the top of all organic search results.
geo
Local pack
A map with three local results that appears at the top of organic search results for a local search query.
hot
Hotels
A block that displays hotels related to a search query. Hotel results include information on prices and rating, and allows users to check availability for certain dates.
img
Images
A collection of images is usually displayed at the top of the SERP if Google considers visual results to be more relevant than text results.
ind
Indented
A list of related pages from the highest organic search result.
job
Jobs
A number of job listings related to a search query that appear at the top of the search results page. Job listings include the job title, the company offering the job, a site where the listing was posted, etc.
kng
Knowledge panel
A block with brief information related to a searched topic that appears to the right of organic search results.
knw
Instant answer
A direct answer to a user’s search query that is usually displayed at the top of organic search results in the form of a gray-bordered box.
mac
Media actions
A block showing details about movies or TV shows and links to platforms where they can be watched.
new
Top stories
A card-style snippet presenting up to three news-related results relevant to user’s search query, which is usually displayed between organic search results.
org
Organic
An organic search result.
rel
People also ask
A series of questions that may relate to a search query that appears in an expandable grid box labeled “People also ask” between search results.
res
Related searches
A list of related searches displayed among organic search results.
rev
Reviews
Organic search results marked with star ratings and including the number of reviews the star rating is based on.
rsp
Response
A block that contains a ChatGPT answer.
shp
Shopping ads
A row of horizontally scrollable paid shopping results that appear at the top of a search results page for a brand or product search query, and include the website’s name, pricing, and product image.
spb
Sports Onebox
A block showing platforms where a live sporting event can be streamed or watched.
stl
Sitelinks
A set of links to other pages of a website that is displayed under the main organic search result and for brand-related search queries.
tea
Teaser
A map with three local business results (mainly hotels and restaurants) that appears at the top of organic search results for a local search query.
twt
Twitter
A carousel of tweets displayed among organic search results.
vib
Featured video
A video result to a search query that is displayed at the top of all organic search results.
vid
Video
Video results with a thumbnail displayed along with other organic search results.

You can filter the Organic positions and Organic visibility index reports for keywords based on a specific SERP feature on SERP. The serp_feature_filter can include or exclude keywords containing specified SERP features, and optionally, it can be refined to target keywords where a specific domain appears within that feature.

The serp_feature_filter consists of -<sf>,<domain>, where:

  • - (optional): Excludes the specified SERP feature if present.
  • sf: SERP feature code, such as geo for Local Pack or fsn for Featured Snippet.
  • domain (optional): The position of a domain in the url parameter list of values. Note that the numbering of domains starts with 0.

Jump to Example requestsExample requests

Retrieve keywords that include a Featured Snippet for the first domain (apple.com)
HTTP
https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/?type=tracking_position_organic&key=YOUR_API_KEY&action=report&url=*.apple.com%2F*:*.amazon.com&serp_feature_filter=fsn,0
Retrieve keywords that include a Featured Snippet for the second domain (amazon.com)
HTTP
https://api.semrush.com/reports/v1/projects/{campaignID}/tracking/?type=tracking_position_organic&key=YOUR_API_KEY&action=report&url=*.apple.com%2F*:*.amazon.com%2F*&serp_feature_filter=fsn,1

Jump to Create a Position Tracking campaign in a projectCreate a Position Tracking campaign in a project

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 with one or more tracking campaigns, make sure that a combination of its location 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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

tracking_url_typeRequired

Type of the tracked URL.

Value/Type: rootdomain, subdomain, subfolder, url

tracking_urlRequired

Tracked URL.

Value/Type: string

location_idRequired

To get the location ID, use the Universal location search method.

Value/Type: integer

weekly_notification

true (default): Enable weekly emails.

false: Disable weekly emails.

Value/Type: boolean

timezone

Time zone. The crawling starts at 05
in the specified time zone.

Value/Type: integer

device

Target device.

Value/Type: desktop, phone, tablet

business_name

Business name.

Value/Type: string

Request example
{
"tracking_url": "example.com",
"tracking_url_type": "rootdomain",
"location_id": 2840,
"weekly_notification": true,
"device": "desktop",
"business_name": "example.com"
}
Response exampleJSON
{
  "status": "SUCCESS",
  "action": "tracking_enable",
  "result": {
    "campaign_id": "103345921_15710"
  }
}

Jump to Enable email-sending containing tracking campaign statisticsEnable email-sending containing tracking campaign statistics

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

Jump to Disable email-sending containing tracking campaign statisticsDisable email-sending containing tracking campaign statistics

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

Jump to Add keywords to an existing tracking campaignAdd keywords to an existing tracking campaign

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

keywords

Keywords.

Value/Type: array

tags

Tags for a keyword.

Value/Type: array

Request example
{"keywords":[{"keyword":"seo", "tags":["seo"]},{"keyword":"seotool", "tags":["seo"]}]}
Response exampleJSON
{
  "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
    }
  ]
}

Jump to Remove keywords from an existing tracking campaignRemove keywords from an existing tracking campaign

Price: 100 API units per request

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

About the Position Tracking configuration ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

keywords

Keywords.

Value/Type: array

Request example
{"keywords":[{"keyword":"seo"},{"keyword":"seotool"}]}
Response exampleJSON
{
  "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
    }
  ]
}

Jump to Add tags to keywords in an existing tracking campaignAdd tags to keywords in an existing tracking campaign

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

keywords

Keywords.

Value/Type: array

tags

Tags.

Value/Type: array

Request example
[{"tag":"seo", "keywords":["search tool", "search engine"]},{"tag":"seo tool", "keywords":["search tool", "search engine"]}]
Response exampleJSON
{
  "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
    }
  ]
}

Jump to Remove tags from keywords in an existing projectRemove tags from keywords in an existing project

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

keywords

Keywords.

Value/Type: array

tags

Tags.

Value/Type: array

Request example
[{"tag":"seo", "keywords":["search tool", "search engine"]},{"tag":"seo tool", "keywords":["search tool", "search engine"]}]
Response exampleJSON
{
  "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
    }
  ]
}

Jump to Add competitors to an existing tracking campaignAdd competitors to an existing tracking campaign

Price: 100 API units per request

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

About adding competitors to a Position Tracking campaign ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

competitors

List of competitors. The maximum number of domains is 20.

Value/Type: array

Request example
{"competitors":["yahoo.com"]}
Response exampleJSON
{
  "url": "mysite.com",
  "tools": [
    {
      "tool": "tracking"
    }
  ],
  "project_id": 643526670283248,
  "project_name": "myproject",
  "campaign_id": 643526670283248_17238,
  "competitors": [
    "google.com",
    "ebay.com",
    "yahoo.com"
  ],
  
}

Jump to Remove competitors from an existing tracking campaignRemove competitors from an existing tracking campaign

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

campaignIDRequired

Campaign ID. Learn how to get your campaign ID ›

Value/Type: string

competitors

List of competitors.

Value/Type: array

Request example
{"competitors":["ebay.com","yahoo.com"]}
Response exampleJSON
{
  "url": "mysite.com",
  "tools": [
    {
      "tool": "tracking"
    }
  ],
  "project_id": 643526670283248,
  "project_name": "myproject",
  "campaign_id": 643526670283248_17238,
  "competitors": [
    "google.com"
  ],
  
}

Jump to Get a list of campaignsGet a list of campaigns

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.

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type:

Response exampleJSON
{
  "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
  }
}

Jump to Universal location searchUniversal location search

Price: 100 API units per request

This request lets you search for locations by ID, type (region, city, country, ZIP code, and more), or name.

If used without parameters, the request returns top locations ordered by location weight.

Jump to EndpointEndpoint

GEThttps://api.semrush.com/position-tracking/management/v1/info/locations?key=YOUR_API_KEY

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

location_id

Location ID

Value/Type: integer

name

Location name

Value/Type: string

country_code

Country code, as defined by ISO 3166-1 code reference (column Alpha-2 code).

Value/Type: AD, AE, AF, AG, AI, AL, AM, AN, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW

type

Location type

Value/Type: autonomous community, barrio, borough, canton, city, city region, country, county, department, district, governorate, municipality, municipality district, neighborhood, okrug, postal code, prefecture, province, quarter, region, state, sub-district, sub-ward, territory, union territory

filter_engine

Search engine

Value/Type: google, bing, baidu

Request example
https://api.semrush.com/position-tracking/management/v1/info/locations?key=API_KEY&type=postal%20code&country_code=us
Response exampleJSON
{
  "locations": [
    {
      "available_volume_types": [
        "national"
      ],
      "location": {
        "id": 2840,
        "name": "United States",
        "formatted_name": "United States",
        "reversed_name": "United States",
        "canonical_name": "United States",
        "parent_id": 0,
        "country_code": "us",
        "type": "country",
        "languages": [
          {
            "id": 0,
            "hl": "en",
            "name": "English",
            "is_default": true
          },
          {
            "id": 0,
            "hl": "es",
            "name": "Spanish",
            "is_default": false
          }
        ],
        "weight": 2774
      }
    }
  ]
}

Jump to Campaign datesCampaign dates

Price: 100 API units per request

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

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_campaign_dates

Request example
GET /?key=YOUR_API_KEY&action=report&type=tracking_campaign_dates
Response exampleJSON
{
  "total": "9",
  "last_crawl": "2",
  "data": {
    "0": {
      "Dt": "20140401",
      
    },
    "1": {
      "Dt": "20140402",
      
    },
    "2": {
      "Dt": "20140403",
      
    },
    "3": {
      "Dt": "20140404",
      
    },
    ...
  }
}

Jump to Organic overview reportOrganic overview report

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_overview_organic

url

Tracked URL or competitor URL (with a mask). To specify multiple domains, use the following format: url={domain1}:{domain2}.
If omitted, the value from the campaign settings is used by default.

Value/Type: string

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

linktype_filter

Specifies whether the local pack and hotel rankings should be included in the report output or excluded from it.

Value/Type: 0 - Include local pack and hotel rankings. This is the default value 1 - Include only local pack and hotel rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotel rankings 536870912 - Exclude AI Overview rankings 536870914 - Exclude local pack and AI Overview rankings 537395202 - Exclude local pack, hotels, and AI Overview rankings

business_name

Business name associated with the domain. It must match the name in Google Business Profile.

Value/Type: string

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 exampleJSON
{
  "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
  }
}

Jump to Adwords overview reportAdwords overview report

Price: 100 API units per request

This request returns the number of keywords that land the specified domain on each of the Google’s paid search rankings 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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_overview_adwords

url

Tracked URL or competitor URL (with a mask).
If omitted, the value from the campaign settings is used by default.

Value/Type: string

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

business_name

Business name associated with the domain. It must match the name in Google Business Profile.

Value/Type: string

Request example
GET /?key=YOUR_API_KEY&action=report&type=tracking_overview_adwords&url=*.apple.com%2F*&date_begin=20140405&date_end=20140411&linktype_filter=0
Response exampleJSON
{
  "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
  }
}

Jump to Organic positions reportOrganic positions report

Price: 100 API units per keyword added

This request lists all keywords from a Position Tracking campaign, top 100 rankings of the specified URLs for those keywords, and position changes over the selected timeframe.

In addition to Google, this endpoint supports campaigns targeted to all Search Engine options available in Position Tracking, including ChatGPT. Rankings and visibility data will be returned based on the specific search engine selected in the campaign configuration.

About the Position Tracking Overview report ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_position_organic

url

Tracked URL or competitor URL (with a mask). To specify multiple domains, use the following format: url={domain1}:{domain2}.
If omitted, the value from the campaign settings is used by default.

Value/Type: string

top_filter

Positions filter.

Value/Type: 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

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

display_filter

Filter for the following columns: Ph, Nq, and Cp.

Value/Type: string

display_limit

Number of returned results. The default value is 10.

Value/Type: integer

display_offset

Number of lines to skip in the report output.

Value/Type: integer

display_sort

Report sorting.

Value/Type: 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

linktype_filter

Specifies whether the local pack and hotel rankings should be included in the report output or excluded from it.

Value/Type: 0 - Include local pack and hotel rankings. This is the default value 1 - Include only local pack and hotel rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotel rankings 536870912 - Exclude AI Overview rankings 536870914 - Exclude local pack and AI Overview rankings 537395202 - Exclude local pack, hotels, and AI Overview rankings

use_volume

Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used.

Value/Type: national regional local

business_name

Business name associated with the domain. It must match the name in Google Business Profile.

Value/Type: string

serp_feature_filter

Filters the report output for keywords that have a specific SERP feature on the SERP.

For a full list of available SERP features, refer to Basic doc > SERP features.

Value/Type: string

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 exampleJSON
{
  "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.851599999999999,
          "*.amazon.com/*": 1.0713999999999999
        },
        ..."20210527": {
          "*.apple.com/*": 13.0494,
          "*.amazon.com/*": 0.90649999999999997
        },
        "Diff": {
          "*.apple.com/*": 2.1978,
          "*.amazon.com/*": -0.16489999999999999
        }
      },
      "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.65999999997,
          "*.amazon.com/*": 48100
        },
        ..."20210527": {
          "*.apple.com/*": 585833.32999999996,
          "*.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"
          ]
        }
      }
    },
    ...
  }
}

Jump to Adwords positions reportAdwords positions report

Price: 100 API units per keyword added

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.

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_position_adwords

url

Tracked URL or competitor URL (with a mask). To specify multiple domains, use the following format: url={domain1}:{domain2}.

If omitted, the value from the campaign settings is used by default.

Value/Type: string

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_tags

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 the 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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

display_filter

Filter for the following columns: Ph, Nq, Cp.

Value/Type: string

display_limit

The number of returned results. The default value is 10.

Value/Type: integer

display_offset

The number of lines to skip in the report output.

Value/Type: integer

display_sort

Report sorting.

Value/Type: 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

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 exampleJSON
{
  "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"
          ]
        }
      }
    },
    
  }
}

Jump to Organic competitors discovery reportOrganic competitors discovery report

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

An identification key assigned to a user after subscribing to Semrush that is available via the Profile page

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type

Value/Type: tracking_competitors_organic

url_type

Type of competitor URLs. If omitted, the value from the campaign’s settings is used.

Value/Type: rootdomain subdomain subfolder url

url

Competitor(s) (with a mask) to be returned in the report.

To specify multiple domains, use the following format: url={domain1}:{domain2}.

Value/Type: string

main_domain

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.

Value/Type: string

black_list

Exclude domains from the report output (separated by the ’|’ symbol).

Value/Type: string

top_start

The top of the position range to search for competitors on SERP.

Value/Type: integer

top_end

The bottom of the position range to search for competitors on SERP.

Value/Type: integer

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

display_limit

Number of returned results. Default value: 10.

Value/Type: integer

display_offset

Number of lines to skip in the report output.

Value/Type: integer

display_sort

Report sorting.

Value/Type: 1_mc_asc 1_mc_desc av_asc av_desc cd_asc cd_desc cl_asc cl_desc {DATE}_asc {DATE}_desc sov_asc sov_desc sovdiff_asc sovdiff_desc tr_asc tr_desc trdiff_asc trdiff_desc ur_asc ur_desc

linktype_filter

Specifies whether the local pack and hotel rankings should be included in the report output or excluded from it.

Value/Type: 0 - Include local pack and hotel rankings. This is the default value 1 - Include only local pack and hotel rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotel rankings 536870912 - Exclude AI Overview rankings 536870914 - Exclude local pack and AI Overview rankings 537395202 - Exclude local pack, hotels, and AI Overview rankings

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 exampleJSON
{
  "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"
    },
    ...
  }
}

Jump to Adwords competitors discovery reportAdwords competitors discovery report

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

An identification key assigned to a user after subscribing to Semrush that is available via the Profile page.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_competitors_adwords

url_type

Type of competitor URLs. If omitted, the value from the campaign’s settings is used.

Value/Type: rootdomain subdomain subfolder url

main_domain

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.

Value/Type: string

url

Competitor(s) (with a mask) to be returned in the report.

To specify multiple domains, use the following format: url={domain1}:{domain2}.

Value/Type: string

black_list

Exclude domains from the report output (separated by the ’|’ symbol).

Value/Type: string

top_start

The top of the position range to search for competitors on SERP.

Value/Type: integer

top_end

The bottom of the position range to search for competitors on SERP.

Value/Type: integer

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_limit

The number of returned results, the default value is 10.

Value/Type: integer

display_offset

The number of lines to skip in the report output.

Value/Type: integer

display_sort

Report sorting.

Value/Type: av_asc av_desc cd_asc cd_desc cl_asc cl_asc {DATE}_asc {DATE}_desc ur_asc ur_desc

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 exampleJSON
{
  "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"
    },
    ...
  }
}

Jump to Organic visibility index reportOrganic visibility index report

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

An identification key assigned to a user after subscribing to Semrush that is available via the Profile page

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_visibility_organic

url

Tracked URL or competitor URL (with mask). To specify multiple domains, use the following format: url={domain1}:{domain2}.
If omitted, the value from the campaign settings is used by default.

Value/Type: string

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

display_filter

Filter for the Ph, Nq, and Cp columns.

Value/Type: string

linktype_filter

Specifies whether the local pack and hotel rankings should be included in the report output or excluded from it.

Value/Type: 0 - Include local pack and hotel rankings. This is the default value 1 - Include only local pack and hotel rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotel rankings 536870912 - Exclude AI Overview rankings 536870914 - Exclude local pack and AI Overview rankings 537395202 - Exclude local pack, hotels, and AI Overview rankings

use_volume

Specifies the level of CPC and volume to be used in the report. If omitted, the bottom-most available level is used.

Value/Type: national regional local

business_name

The business name associated with the domain. It should match the name from the Google My Business profile.

Value/Type: string

serp_feature_filter

Filters the report output for keywords that have a specific SERP feature on the SERP.

For a full list of available features, refer to Basic doc > SERP features.

Value/Type: string

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 exampleJSON
{
  "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
    }
  }
}

Jump to Adwords visibility index reportAdwords visibility index report

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

An identification key assigned to a user after subscribing to Semrush that is available via the Profile page

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_visibility_adwords

url

Tracked URL or competitor URL (with mask). To specify multiple domains, use the following format: url={domain1}:{domain2}.
If omitted, the value from the campaign settings is used by default.

Value/Type: string

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

display_filter

Filter for the Ph, Nq, and Cp columns.

Value/Type: string

Request example
GET /?key=YOUR_API_KEY&action=report&type=tracking_visibility_adwords&date_begin=20140401&date_end=20140411&url=*.apple.com%2F*
Response exampleJSON
{
  "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
    }
  }
}

Jump to Organic landing pages reportOrganic landing pages report

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_landing_pages_organic

urlRequired

Tracked URL or competitor URL (without a mask). To specify multiple domains, use the following format: url={domain1}:{domain2}.

Value/Type: string

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

display_filter

Filter for the Ph, Nq, and Cp columns.

Value/Type: string

display_limit

Number of returned results. Default value is 10.

Value/Type: integer

display_offset

Number of lines to skip in the report output.

Value/Type: integer

display_sort

Report sorting.

Value/Type: 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

newlost_filter

Return only new or lost URLs.

Value/Type: new, lost

linktype_filter

Specifies whether the local pack and hotels rankings should be included in the report output or excluded from it.

Value/Type: 0 - Include local pack and hotel rankings. This is the default value 1 - Include only local pack and hotel rankings (organic rankings are excluded) 2 - Exclude local pack rankings 524288 - Exclude hotels rankings 524290 - Exclude local pack and hotel rankings 536870912 - Exclude AI Overview rankings 536870914 - Exclude local pack and AI Overview rankings 537395202 - Exclude local pack, hotels, and AI Overview rankings

use_volume

Specifies the level of CPC and volume to use in the report. If omitted, the bottom-most available level is used.

Value/Type: national regional local

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 exampleJSON
{
  "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
    },
    ...
  }

Jump to Adwords landing pages reportAdwords landing pages report

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 ›

Jump to EndpointEndpoint

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

Request Parameters

keyRequired

Identification key assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units.

Value/Type: string

actionRequired

Type of action.

Value/Type: report

typeRequired

Request type.

Value/Type: tracking_landing_pages_adwords

urlRequired

Tracked URL or competitor URL (with a mask). To specify multiple domains, use the following format: url={domain1}:{domain2}.

Value/Type: string

date_begin

Start date of the selected period.

Value/Type: Date in YYYYMMDD format

date_end

End date of the selected period.

Value/Type: Date in YYYYMMDD format

display_tags

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.

Value/Type: string

display_tags_condition

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.

Value/Type: string

display_filter

Filter for Ph, Nq, and Cp columns.

Value/Type: string

display_limit

The number of returned results, the default value is 10.

Value/Type: integer

display_offset

The number of lines to skip in the report output.

Value/Type: integer

display_sort

Report sorting.

Value/Type: 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,

newlost_filter

Return only new or lost URLs.

Value/Type: new, lost

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 exampleJSON
{
  "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
    },
    ...
  }
}

Last updated: January 30, 2026

Was this page helpful?