Search Query API
is a direct query rank on-demand API method that returns the HTML of the search results for a keyword and search engine query. This is a real time tracking API method that features a callback URL option for automation with your software.
: 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.
: one time on-demand.
: this is a stand-alone API-only package, it does not include access to our reporting platform reports or Reporting API methods
: data generated by this API is stored for 24 hours
XML is the default format, and JSON can be obtained by adding an output parameter to the request
- Recurring monthly fee is based on the number of units purchased (1 unit = 1 keyword tracked 1 time on 1 search engine).
- Units are available in multiples of 1000.
- At the beginning of each month the package capacity is reset (unused capacity is not transferable from previous month).
with the number keyword queries you want to run per month and we'll provide you with pricing.
API Options & Restrictions
API package capacity can be upgraded at any time.
Search API packages do not include access to Rank Ranger's reporting platform or white label features, these are data-only packages.
This on-demand API does not require campaign set up, it is used for one-time queries on one search engine per query so it can be built into your software or website, and as such there is no data storage.
||The unique API key assigned to your account
||Search Engine ID (get search engine ID list)
||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)
||Optional: When &callback=true is included in the request, the system will send a callback to the URL that is defined for your account as the 'callback_url'.
A callback is a POST request sent to your machine informing it that the data extraction task has been completed, and it provides the URL for downloading the HTML of the search results pages.
Important! Account Setup - when you subscribe to the Search Query API, if you want to use the Callback URL option you must send a message to email@example.com with the URL that you want us to sent the callback URL to so we can set it up in our system.
Keyword Query with Callback URL
To receive the URL for downloading the HTML of the search results when the data extraction task has been completed, add the callback parameter to your keyword query and a POST response will be sent to your machine.
Example of Keyword Query to obtain Callback URL
Sample Callback URL Response
Keyword Query Examples without Callback
Run Keyword Query for XML output
Run Keyword Query for JSON outputhttps://www.rankranger.com/api/v2/?search_api_query&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&se_id=XXX&output=json
Run Keyword Query for specific USA locationhttps://www.rankranger.com/api/v2/?search_api_query&key=YOUR-API-KEY&keyword=YOUR-KEYWORD&se_id=XXX&geo=nashville, tn
Run Keyword Query for specific city for a non-USA location when using a country-specific search engine (e.g., Google UK)
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.
Response: Successful Query Processing
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.
||Search Engine ID (get search engine ID list)
||Query ID is used to request rank results after submitting a keyword query
||To obtain parsed results, add &parse_results=true&se_id=XXX to the request
||Optional: Adding &parse_serp_features=true to the search_query-api_results request provides the special SERP indicators from our Google SERP Features API and Related Search API when those features are present in the search results for the query.
||To obtain JSON format, add &output=json to the request
HTML Results Request Example
The Parse Results, Parse SERP Features and/or Output parameters can be added to the Callback URL or it can be used in its original form to obtain the HTML SERP results.
Example of a Callback URL
HTML Results Example
The Callback URL produces the full HTML results inside of content tags. For example:
Example of saved HTML results viewed in a web browser
Parsed Results Request Example
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.
Example of Search Query API Parsed Results including SERP Features
In this example viewed in a JSON editor, are
- organic search results with rank, URL, title, description and any page extras that display in the SERP (e.g., HTTP, breadcrumbs, sitelinks, etc.)
- plus Google SERP Features such as knowledge panel, answer boxes, (e.g., related questions, featured snippets, people also search for, etc.), top stories, videos, related search, and Google Ads
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, this Not available error is the response:
Question: With your Rank Top 50, Rank Top 100 or Search Query API, how can I distinguish between a keyword that organically ranked in position 1 vs. one that ranked in position 1 because it was in a featured snippet?
- In the search_results for each rank position, our Rank Top 50, Rank Top 100 and Search Query APIs provide rank, url, extra and title. SERP indicators are recorded as extra data, extra: Featured Snippet is the indicator you will see when a keyword ranks in position 1 inside of a Featured Snippet.
- For APIs that have Google SERP Features included, Featured Snippets are identified in the google_serp_features > answer boxes > answer_box > ab_type: Featured Snippet. Included in that result is the title, url and image_url when they exist in the Featured Snippet.
This illustration provides an example of our Rank Top 50 API results, demonstrating how results from the SERP are presented (Rank Top 100 and Search Query APIs deliver that data in the same way).
If you'd like to help determining which of our API plans is most appropriate for your needs, contact our service team
and an account manager will be happy to assist you.
If you already have a Rank Ranger plan and see an error message when accessing the Account > Connections > API & Connected Apps screen, then to obtain API access you will need to upgrade to a package that includes API access by completing a custom package request
form or contacting Rank Ranger support
with your requirements.
If your company has API services included in a plan and you aren't able to access the screen, contact your company's Rank Ranger acccount administrator to request that your user permissions
be set to include access to the Account > API and Connected Apps screen.
You can obtain API Keys per user if your Rank Ranger account has API access by navigating to
2. Connections > API & Connected Apps
3. Click the Generate Key
4. Select a User and add a note (optional)
5. Click the Add
To make construction of API requests easy, we offer this API testing tool. Most parameters are included in the options of the console, however, you may need to add custom option parameters to your API requests based on the specific API you're using. Referencing the parameters information that is listed in the specific API method documentation, you can construct and test API requests in Rank Ranger's API Console
by navigating to:
3. API Console
4. Select the Method and complete the applicable fields
5. Click the Generate button
6. Test your API method by clicking the launch URL icon and view your results. Once your results are as you want them, copy that URL into your own application and modify as needed for each request.
Getting Started: Samples of APIs used for Creating Campaigns
We recommend reviewing our Best Practices Guide
prior to structuring campaigns.
Get Packages Info
: Required when there is more than 1 package in an account
Add a Profile
: An option for adding an identifier to your campaigns for categorization (e.g., by language, country, etc)
Get Profile ID list
: Optional Data needed for Add a Campaign
Obtain the Search Engine List
: Data needed for Add a Campaign
Add a Campaign
: Create a new campaign, response will include the Campaign ID number that is needed for adding a search engine and keywords
*Note that Profile ID is an optional field that you may use, if you choose not to use it, then please remove "&profile_id=ProfileIDnumber” from the end of this call
Add a Search Engine
: Add search engine to a campaign
Add a Keyword
: An optional field is available for keyword_identifier field, allowing you to add your own unique identifier to each keyword
Bulk Add Keywords
: You may download and use the spreadsheet found on the Campaign Settings > Keywords screen to organize and import your keywords, or use this API
You'll find additional API methods in the Account Management and Data documentation
Rank Ranger APIs can pull up to 100 queries per minute. If more than 10,000 API GET requests per hour is required, then there is an option available at an additional throughput fee, contact customer service for assistance.
Rank Reporting Method Limits
Research API Methods
- Rank Data & Research Reporting API methods can only provide data from campaigns tracking in your Rank Ranger account.
- You can run an unlimited number of queries through the API.
Search API Method Limits
- The variety of Research Method APIs have limits on the number of queries per day based on the capacity of your package. If you require additional units, please contact customer service and an account manager will provide you with package upgrade pricing.
- SEO Intelligence API method query limits are based on the number of units purchased for your custom plan (e.g., 1 unit = 1 keyword tracked on 1 search engine, 1 time).
- Search API plans do not include access to the reporting platform.