Create a new Search Engine Ranking Page (SERP) request.

post

https://api.highvolume.georanker.com/serp/new

Create a single SERP request, that is asynchronous by default and receives an incomplete SERP object, where its ID can be used to download the full data, later.
Click here and check out a JSON response example.

ABOUT THE CREDIT SYSTEM
The base value for every SERP request is 1 CREDIT, but this value can change based on the following parameters:

Priority
Max Results
Search Engine

Priority (multipliers):

LOW PRIORITY = multiplies costs by 1
NORMAL PRIORITY = multiplies costs by 1
REALTIME PRIORITY = multiplies costs by 2
INSTANT PRIORITY = multiplies costs by 3

Max Results:

Credits can increase as maxResults grows, based on incremental
pricing rules configured for your account.

Search Engine:
The costs can change depending on the search engine, based on credit rules configured for your account.

LIMITS AND RULES
Our API has a few limitations depending on your plan, you can see more about this on our onboarding page here. Please get in touch with us for any further information or questions.

Rules:
Our API has two different policies when the limits are exceeded:

Overcharge: The system will allow you to continue using the API but every request above the limit will cost extra. (prices and what policy is used depends on your plan and agreement)
Reject: The system will reject any further request after the limit is exceeded (prices and what policy is used depends on your plan and agreement)

NOTE: To use the custom region search, do not set the region parameter, otherwise the region will be used by default.

Body Params

The SERP request parameters.

keyword

string

required

The keyword to be used when doing the search. We will not automatically append any city name to the keyword. The search will be done using the exact same keyword sent. NOTE: This parameter cannot be encoded, we already encode on our side. Example: pizza delivery

region

string

required

A valid canonical region name or a ISO-3166-1 alpha-2 country code. If the name does not match with a canonical name from our list, we will try to match with its formatted name, local name, criteria id or a country code. You can check a list of valid canonical regions in our API or in the Google Geolocation . Example: London,England,United Kingdom

regionSearch

object

OPTIONAL - To be used as an alternative to CANONICAL REGIONS ONLY. Search for the nearest Region provided by its longitude, latitude, maximum distance in meters (optional) and a list containing the allowed target types, which are: autonomous community, canton, city, congressional district, country, county, department, governorate, municipality, prefecture, province, region, state, territory, tv region and union territory.

priority

string

Defaults to NORMAL

The request's priority level. Choose one of the available priorities: LOW, NORMAL, REALTIME and INSTANT. Pay attention to REALTIME and INSTANT levels that double and quintuple the cost of the request, respectively. See more.

asynchronous

boolean

Defaults to true

This flag controls the request's behavior. If its value is TRUE, the API won't wait for a response from the Crawler, retrieving the data immediately, otherwise, if its value is FALSE the API will wait for up to 300 seconds or if the Crawler answer before the wait time finishes. Also, if this flag is not sent within the request, the default values will be used to: LOW or NORMAL priorities this flag will be set to TRUE and REALTIME or INSTANT priorities this flag will be set to FALSE. NOTE: We recommend to set this flag to FALSE if the request uses the priority REALTIME or INSTANT.

searchEngine

string

required

The search engine used to search the content. Complete list of available Search Engines: sogou, googlelocal, googleimages, bing, google, yahoo, naver, youtube, google-aimode, baidu. Examples: sogou, googlelocal, googleimages, bing, google, yahoo, naver, youtube, google-aimode, baidu

callback

string

A URL that will be called when this SERP Request is ready to be downloaded. We will do a POST HTTP request sending the id from the request in a key called 'id' and telling its type which is 'serp' to the callback URL as soon the data is ready on our database.The URL can also deliver the 'id' and 'type' information as parameters inside the URL. Examples: mysite.com/process.php or mysite.com/process.php?youridparam={: id :}&yourtypeparam={:type:}

callbackFormat

string

This flag determines if the callback response will return the type and the object id or the full object response as JSON. This flag allow two values 'SIMPLE' or 'JSON'. Anything different from that it will use the default value 'SIMPLE'
NOTE: This flag default value is 'SIMPLE' but is subject to change to 'JSON' in the near future.

maxResults

int32

≥ 10

The maximum amount of organic results we will collect from the search engine. The maximum value of this variable is determined by the user plan. This parameter counts only organic results. Default: Value defined by the search engine. Max value for this parameter depends on the search engine being used, as displayed in this link. NOTE: For maxResults >100 and <=200 it'll be charged twice the cost. For maxResults >200 and <=300 it'll be charged three times the cost, and so on.

isMobile

boolean

Defaults to false

If True, we will do the search using a mobile browser. By default, this variable is False. Note that, if a customUserAgent is set, this flag is ignored

language

string

The language code is following ISO 639-1 standards and must be active in our system. You can see the full list of active languages here. If this field is not provided,we will use the default language for the country. Default: en

saveRawData

boolean

Defaults to false

True if you want the raw data to be saved. If you use a custom user-agent, we recommend turning this flag on.

customUserAgent

string

(Advanced) Force our crawlers to use a specific User-Agent header for this SERP. By default, and in most situations, this field should be NULL. If you use a custom user-agent, our parsers may not be able to parse the results automatically. You should implement your own parser using the raw data provided, thus, please make sure the saveRawData field is true when using a custom user-agent. This field cannot have more than 250 characters.

customUrlParameter

array of objects

(Advanced) An array of objects with "name" and "value" fields. The parameters inside the array will be appended to the end of the URLs of all requests made during the SERP resolution. The parameters should not be encoded, as the encoding will be done on our side. A Parameter with the same name of a default engine parameter will replace it. Parameters with null value will remove the corresponding orignial parameters. Some default URL parameters cannot be replaced or removed. If you plan to use this feature, please note that our parser may not work well and we recommend doing the parsing and data extraction on your side using the rawHtml flag. Example: [{"name":"var1","value":"1"},{"name":"var2","value":"2"}].

customUrlParameter

customCookieParameter

array of objects

(Advanced) An array of objects with "name" and "value" fields. The parameters inside the array will be used along with the default search engine cookies to build the cookies header of the SERP requests. The parameters should not be encoded, as the encoding will be done on our side. A Parameter with the same name of a default engine parameter will replace it. Parameters with null value will remove the corresponding orignial parameters. Some default cookies cannot be replaced or removed. If you plan to use this feature, please note that our parser may not work well and we recommend doing the parsing and data extraction on your side using the rawHtml flag. Example: [{"name":"var1","value":"1"},{"name":"var2","value":"2"}].

customCookieParameter

voiceSearchHighFidelity

boolean

Defaults to false

If true, the voice search transcription will be more reliable. Important note, this feature only works in the google voice search engine.

Metadata

apikey

string

required

The user account apikey

Responses

200SERP Request created

402Credit limit exceeded or insufficient credits. The user exceeded their available hourly or daily requests and should try again later. Or the user account has no credits left to complete the request.

403Bad API Key. Your key may have been mistyped or you do not have access to our API. Retrying the request will not solve the issue.

429Too many requests or connections. Your server made too many requests or opened too many connections. Please slow it down and close the unused connections. Enabling the 'keep-alive' mechanism may help to reuse connections.

500Internal server error. This is a generic error for some unexpected action that might happen at our side. This error should never appear to you, but if it does, you should retry later and contact us if it persists.

502Internal server error due a database timeout. This error should never appear to you, but if it does, you should retry later and contact us if it persists.

504Internal server error similar to error 502. This error should never appear to you, but if it does, you should retry later and contact us if it persists.