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 API method features a callback URL option for automation with your software.
: data is available for Google Desktop, and Google Mobile.
: one time on-demand.
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 in the account settings 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.
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
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 run an unlimited number of queries through the API.
- Only data from your Rank Ranger account can be pulled through the API.
- Rank Ranger APIs can pull up to 10 queries per minute.
If more than 10,000 API GETs per hour is required, then there is an option available at an additional throughput fee.
You can obtain API Keys per user if your Rank Ranger account has API access.
To do this, go to Account Settings
--> API & Connected Apps
and select Generate Key
- Add Notes (optional)
- Click the Add button
API Keys successfully generated