Create a new keyword request.

post

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

Create a single Keyword request, that is asynchronous by default, and receive an incomplete Keyword object, where its ID can be used to download the full data, later.
There are two types of keyword requests:
KEYWORD SEARCH VOLUME

INPUT: from 1 to 20 keywords; and,
OUTPUT: Competition, CPC and Search Volume (monthly and annually).

NOTE: The output will contain the exact number of keywords as the input, up to 20.

Click here to check out a JSON response example.

ABOUT THE CREDIT SYSTEM
The base value for every Keyword request is 3 CREDITS, but this value can change based on priority:

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

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

Body Params

The keyword request parameters

keywords

array of strings

required

The list of keywords. The keyword cannot be longer than 80 characters. The list can contain up to 20 items.

keywords*

url

string

A valid URL from a web site that will be analyzed by Google. Keyword suggestions will automatically be retrieved based on the content of the target web site. This command must use google as source and the suggestions flag must be true. The keywords field can be used together with the URL to guide the results, or it can be left null.

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.

language

string

Two letters ISO 639-1 language code. If this field is not provided or contains an unsupported language, we will not filter by language.

source

string

required

Defaults to google

The data source used to collect the data. If the source is not set, we will assume the data needs to come from google. Possible Values: "google","baidu".

searchPartners

boolean

Defaults to true

If you specify the true value in the field, the results delivered will include the search partners data. By default, search partners are not considered.

suggestions

boolean

Defaults to false

If true, we will return suggestions based on the keyword list.

callback

string

A URL that will be called when this Keyword Request is ready to be downloaded. We will do a POST HTTPS request sending the id from the request in a key called 'id' and telling its type which is 'keyword' to the callback URL as soon the data is ready on our database.

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.

Metadata

apikey

string

required

The user account apikey

Responses

200Keyword 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.