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
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.
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
| 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
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
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.
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.
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
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:
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:
|
| useragent | string | Related only to mobile search engines requests. To obtain a search query for IOS, add &useragent=ios to the search query request. |
| 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 |
Comments
Article is closed for comments.