Similarweb’s Rank Tracking API allows you to track, tag, and evaluate your site's SERP performance at scale within your own internal tools and interfaces. Compare your performance against competitors and see exactly where your site stands across keywords, devices, search engines, geographies, and more.

There are two Rank Tracking APIs detailed in this article:

  • Top 100 Rank

  • Search Query

line.png

Getting Started

In order to get started, obtain a designated Rank Tracking API key. Reach out to your Similarweb Account Manager for more information, or to request a key.

It is not possible to use your existing Similarweb API key.

Top 100 Rank

Use the rank_top100 method to gain access to the top 100* SERP results that rank on a specific date for a campaign keyword and search engine. You can query daily, weekly, bi-weekly or monthly data.

Data is currently available for Google. Note: this offering will soon be expanded to include data for Yahoo!, Bing, Yandex & Baidu.

Results include the date, search engine ID, rank, landing page URL, and SERP meta title. For Google desktop and mobile search engines, the results will also include a comprehensive list of SERP features results (e.g. Site Links, Featured Snippets, Top Stories, Search Box, Local Pack, Google Ads, etc.), along with the meta titles and descriptions of the organic search results.

Data Retention: Data generated by this API is stored for 60 days.

Charging: 1 unit = 1 keyword tracked 1 time on 1 search engine

Note

If the search engine provides less than 100 results for a keyword, then the API returns only the number of results that were available during the rank tracking for that keyword.

GET Rank Top 100 for specific date

https://www.rankranger.com/api/v2/?rank_top100&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&date=YYYY-MM-DD&se_id=SEARCH-ENGINE-ID&campaign_id=YOUR-CAMPAIGN-ID

GET Rank Top 100 for a date range

https://www.rankranger.com/api/v2/?rank_top100&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&se_id=SEARCH-ENGINE-ID&campaign_id=YOUR-CAMPAIGN-ID

GET Rank Top 100 Batch request

https://www.rankranger.com/api/v2/?rank_top100&key=YOUR-API-KEY&se_id=SEARCH-ENGINE-ID&campaign_id=YOUR-CAMPAIGN-ID&show_title=true&batch_start=1&batch_limit=200

The request for the next batch would start with 201, for example:

https://www.rankranger.com/api/v2/?rank_top100&key=YOUR-API-KEY&se_id=SEARCH-ENGINE-ID&campaign_id=YOUR-CAMPAIGN-ID&show_title=true&batch_start=201&batch_limit=200

GET Rank Top 100 for a specific date including SERP Link Title

https://www.rankranger.com/api/v2/?rank_top100&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&date=YYYY-MM-DD&se_id=SEARCH-ENGINE-ID&campaign_id=YOUR-CAMPAIGN-ID&show_title=true

Parameters

key

string

The unique API key assigned to your account

keyword

string

Keyword

date

yyyy-mm-dd

Requested data date

Optional: Date Range can be called using &start_date=YYYY-MM-DD&end_date=YYYY-MM-DD(for up to a span of 10 days)

If date is used, then do not include the results parameter

se_id

int

Search Engine ID

campaign_id

int

Campaign ID number

results

int

Number of days' data (up to 10)

Do not use with date parameter

show_title

string

Option to include SERP Link Title in top 100 results

pi

string

Option to include SERP Features in the results. If you want the presence of answer boxes, snippets, local packs, etc. included in the API results, then add &pi=true to the request.

batch_start

batch_limit

string

Optional: The Batch request may be used to obtain results in batches of 200 keywords at a time. This option requires the parameters batch_start=X&batch_limit=200, where X equals the beginning of the batch.  To request the first 200 keywords in a campaign, this is an example request:

https://www.rankranger.com/api/v2/?rank_top100&key=YOUR-API-KEY&se_id=SEARCH-ENGINE-ID&campaign_id=YOUR-CAMPAIGN-ID&show_title=true&batch_start=1&batch_limit=200

The request for the next batch would start with 201, for example: &batch_start=201&batch_limit=200

Do not use date and keyword parameters when choosing the batch option

exclude_nr_ind=true

string

Option to exclude the "no results" text string from the API response

The default output is in XML format, if you would like the output to be JSON then you will need to add "&output=json” at the end of the string

Example Response

Including Google SERP Features:

RankTracking1.png
RankTracking2.png
RankTracking5.png
RankTracking4.png
Responses with less than 100 Results

Google SERP results may display less than 100 organic results depending on keyword-specific factors determined by Google algorithms.

Search Query

The search_api_query is a direct query rank on-demand API method that returns parsed search results for a keyword and search engine pair. This is a real-time tracking API method.

Search Engines: data is available for Google Desktop, and Google Mobile. Note that desktop and mobile can vary in the type of SERP features available in the results, for example, desktop results may include an image URL in a Featured Snippet, but mobile does not.

Frequency: one-time on-demand.

Data Retention: data generated by this API is stored for 24 hours

Data Format: XML is the default format, and JSON can be obtained by adding an output parameter to the request

User-Agent: Only used for mobile search engines. By default the user agent is Android, however, if the data is required for iOS then the user agent has to be set.

Charging: 1 unit = 1 keyword tracked 1 time on 1 search engine

line.png
GET Keyword Query for XML output

https://www.rankranger.com/api/v2/?search_api_query&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&se_id=XXX

GET Keyword Query for JSON output

https://www.rankranger.com/api/v2/?search_api_query&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&se_id=XXX&output=json

GET Keyword Query for specific USA location

https://www.rankranger.com/api/v2/?search_api_query&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&se_id=XXX&geo=nashville, tn

GET Keyword Query for a specific city for a non-USA location when using a country-specific search engine (e.g., Google UK)

https://www.rankranger.com/api/v2/?search_api_query&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&se_id=XXX&geo=london

The default output is in XML format, if you would like the output to be JSON then add "&output=json” at the end of the string.

line.png

 

Example Response: Successful Query Processing

Query ID

A successful search_api_query request returns a status of success, along with a Query ID (query_id) that can be used to call the rank results.

Ranktracking_QueryID.png
Get Results Parameters

se_id

int

Search Engine ID (get search engine ID list)

query_id

int

Query ID is used to request rank results after submitting a keyword query

parse_results

string

To obtain parsed results, add &parse_results=true&se_id=XXX to the request

parse_serp_features

string

Adding the paramater&parse_serp_features=true

to the search_query-api_results request causes all the SERP features appearing on the search results page at the time of the query to be included in the results.

output

string

To obtain JSON format, add &output=json to the request

HTML Results

The Parse Results, Parse SERP Features, and/or Output parameters can be added to the API request which will be used in its original form to obtain the HTML SERP results.  

Example of the API request:

https://www.rankranger.com/api/v2/?search_api_query_results&key=YOUR-API-KEY&query_id=QUERY-ID

HTML Results Example Response
RankTracking_HTMLResponse.png
Parsed Results

Parsed results can be requested manually in the following format using the query_id received via the search_api_query request, plus the parse_results and se_id parameters.

https://www.rankranger.com/api/v2/?search_api_query_results&key=YOUR-API-KEY&query_id=QUERY-ID&output=json&parse_results=true&se_id=XXX&parse_serp_features=true

Results for Mobile Data

Querying results for Google mobile retrieves data for Android by default. If iOS data is required, then the parameter ‘&useragent=ios’ should be added to the request.

Results Not Available

Depending upon the queue, results may be returned in a matter of seconds to a minute or slightly more for the query to process, so your results request should be set to repeat until results are returned.

When results are not ready, the following Not Available error is the response presented:

RankTracking_ResultsNotAvailable.png
Query Parameters

key

string

The unique API key assigned to your account

&key=yourAPIkey

keyword

string

Keyword

&keyword=your keyword

se_id

int

Search Engine ID (get search engine ID list)

&se_id=XXX

geo

string

Optional: custom Location can be entered to target a specific location by adding &geo=location name or postal code. For example:

  • miami, fl  OR 90210 (specific postal code within the area of Google USA)

  • california (the entire state)

  • london or wc1n (specific postal code within the area of Google.co.uk)

  • amsterdam or 1012nx (specific postal code within the area of Google.nl)

useragent

string

Related only to mobile search engines requests. To obtain a search query for IOS, add &useragent=ios to the search query request.

Rank Tracking API Error codes

Code

Text

Description

101

Invalid Method

Method does not exist, check your syntax

102

Invalid API Key

The API Key inserted is invalid, check for key accuracy

103

Invalid Domain

The Domain requested is invalid or does not exist in your account

104

Invalid Date

The selected date range or syntax is invalid

105

Invalid Keyword

The Keyword does not exist in this campaign

202

Invalid Campaign Name

The Campaign name is invalid or missing

203

Invalid Primary URL

The Primary URL is invalid or missing

204

Invalid Campaign ID

The Campaign ID is invalid or missing

208

Invalid Search Engine

Invalid Search Engine ID

210

Keyword already exists

The Keyword already exists in this campaign

211

Keyword exists in campaign

You need to delete Keywords from this campaign before trying to delete the campaign

212

Invalid Package ID

Invalid Package ID

215

Custom White Label URL is already in use for another campaign

The Custom URL that you have selected for your White Label Portal is in use by another campaign, please select a different URL

400

No Results

No results were found

401

Limit Reached

You have reached the maximum number of Campaigns allowed in your package

Was this article helpful?
26 out of 36 found this helpful