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.
: 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:
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
If you 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.
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.
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
Search API Method Limits
- 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.
- 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.