The Request Object in detail

Note

A POST request requires a json object to be set in the request body, which allows you to define the parameters of the parsed SERPs you wish to receive.

A GET Request is much simpler and does not require a json object, just a url with a jid.


Three levels of priority

The API provides three levels of priority for every request:

  • regular priority (asynchronous request)
  • high priority (asynchronous request) available on request
  • instant priority (synchronous request) available on request

Example regular Request

POST /serps/ HTTP/1.1
Host: v3.api.analyticsseo.com
Content-Type: application/json
Authorization:  KeyAuth publicKey=XXX hash=XXXXXXXXXXXX ts=1234567890

{
    "search_engine":"google",
    "region":"global",
    "language":"en",
    "max_results":100,
    "phrase":"How good is your SEO",
    "user_agent": "pc"
}

As you can see our request contains two important elements, the Request Object itself and the Authorization header.

The Request Object

The following parameters will allow you to fine tune how the SERPs page is requested

Field Type Default Required Description Allowed values
search_engine string   yes the search engine to query see Supported Search Engines, Regions, Languages and Towns
phrase string   yes the search term / keyword  
region string   yes the region code to use see Supported Search Engines, Regions, Languages and Towns
language string   yes the language code to use see Supported Search Engines, Regions, Languages and Towns
town string null no the town to use see Supported Search Engines, Regions, Languages and Towns, must match exactly the name provided
latitude string null no the latitude of the location to geolocate results to a decimal between -90.0 and 90.0
longitude string null no the longitude of the location to geolocate results to a decimal between -180.0 and 180.0
max_results integer 100 no the number of results to return any number up to 500
user_agent string pc no the user agent to use see User Agents
use_cache boolean True no whether to use cached data, if available True or False
include_all_in_universal boolean False no whether to incude ads in universal section True or False
callback string   no the url to call after request is ready valid http or https url i.e. http://www.example.com/callback

Attention

All string values are case sensitive, so Web will yield an error

max_results is a soft limit, due to the way search engine works it is not possible to get an exact value back, so max_results=100 will fetch 10 pages of results which may have more or less than 100 results

The Authorization header

In order to request SERPs results you have to first be authenticated, you can set the following HTTP header to identify yourself.

Field Value Notes
Authorization KeyAuth publicKey=XXX hash=XXXXXXXXXXXX ts=1234567890 see Authentication and Authorization

Search Engine

Because the SERPs pages have to be parsed you cannot freely specify any search engine, please see Supported Search Engines, Regions, Languages and Towns for more information.

Region, language and town

You can specify a region, language and town to narrow down your search results.

Not all regions and languages are supported in all search engines, please see Supported Search Engines, Regions, Languages and Towns for more information on supported options.

Ads in universal

If include_all_in_universal is set to True, ads will also be included in the Universal Results section.

Example high priority Request

POST /serps/ HTTP/1.1
Host: v3.api.analyticsseo.com
Content-Type: application/json
Authorization:  KeyAuth publicKey=XXX hash=XXXXXXXXXXXX ts=1234567890

{
    "search_engine":"google",
    "region":"global",
    "language":"en",
    "max_results":100,
    "phrase":"How good is your SEO",
    "user_agent": "pc",
    "parameters": {"high_priority": true}
}

The only difference between regular and high priority request is additional "parameters" field.

Example instant priority Request

POST /serps_instant/ HTTP/1.1
Host: instant.v3.api.authoritas.com
Content-Type: application/json
Authorization:  KeyAuth publicKey=XXX hash=XXXXXXXXXXXX ts=1234567890

{
    "search_engine":"google",
    "region":"global",
    "language":"en",
    "max_results":100,
    "phrase":"How good is your SEO",
    "user_agent": "pc"
}

The differences between regular and instant priority request are: