API Reference

POST /serps/(.*)

Asynchronous SERPs processing request

Creates a new job to be processed. Upon successfully accepting the request you will receive a job id that can later be used to retrieve the SERPs data (see GET method below ).


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"
}

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


The Request Object

The request object although having a simple structure has complex rules and logic behind it, please read The Request Object in detail for more information.

The Authorization header

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


Response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "request": {
         "language": "en",
         "parameters": {},
         "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
         "search_engine": "google",
         "phrase": "how good is your SEO",
         "region": "gb",
         "max_results": 100,
         "town": null
   },
   "ready": false,
   "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
   "response": {}
}

Response Codes

Code Name Explanation
201 Created We successfully accept your SERPs request and a background job has been scheduled
400 Bad Request The sent request was not valid, please check for invalid parameters
401 Unauthorized Authentication is required and was not provided
403 Forbidden Authentication provided was not valid

The Response Object

Field Type Description Notes
jid string the unique identifier for your job (job id)  
ready boolean when false it means the job has not been processed yet  
request object contains a copy of your sent request  
error string contains an error message only present if there is an error
response object when ready it will contain the processed SERPs page results the response for this request is always an empty object
POST /search_results/(.*)

Asynchronous SERPs processing request

Creates a new job to be processed. Upon successfully accepting the request you will receive a job id that can later be used to retrieve the SERPs data (see GET method below ).


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"
}

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


The Request Object

The request object although having a simple structure has complex rules and logic behind it, please read The Request Object in detail for more information.

The Authorization header

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


Response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "request": {
         "language": "en",
         "parameters": {},
         "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
         "search_engine": "google",
         "phrase": "how good is your SEO",
         "region": "gb",
         "max_results": 100,
         "town": null
   },
   "ready": false,
   "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
   "response": {}
}

Response Codes

Code Name Explanation
201 Created We successfully accept your SERPs request and a background job has been scheduled
400 Bad Request The sent request was not valid, please check for invalid parameters
401 Unauthorized Authentication is required and was not provided
403 Forbidden Authentication provided was not valid

The Response Object

Field Type Description Notes
jid string the unique identifier for your job (job id)  
ready boolean when false it means the job has not been processed yet  
request object contains a copy of your sent request  
error string contains an error message only present if there is an error
response object when ready it will contain the processed SERPs page results the response for this request is always an empty object

GET /serps/(.*)

Returns information about an existing job.

After successfully requesting a job (see POST method on how to request a job), you can use this request to get available information for the returned jid

Example Request

GET /serps/XXXXXXX HTTP/1.1
Host: v3.api.analyticsseo.com

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "request": {
        "language": "en",
        "parameters": {},
        "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
        "search_engine": "google",
        "phrase": "how good is your SEO",
        "region": "gb",
        "max_results": 100,
        "town": null
  },
  "ready": false,
  "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
  "response": {"...."}
}

Response Codes

Code Name Explanation
200 OK We found the jid and returned available data
404 Not Found the jid does not exist or has already expired (they are kept at most for 24h)

The Response Object

Field Type Description Notes
jid string the unique identifier for your job (job id)  
ready boolean when false mean the job is being processed  
request object contains a copy of your request  
error string contains an error message only present if there is an error
response object when ready it will contain the processed SERPs page results see The Response Object in detail

Note

The response field named response will contain the parsed SERPs results. Read The Response Object in detail for more information.


The Response Structure

{
    "response": {
        "results": {
            "video": {},
            "organic":{
                .....
            },
            "universal": {
                "1": {
                    "rich_snippets": [

                    ],
                    "description": "How good is your SEO? enter your domain below to find out ... Domain ... Get this for your site! Want to offer free SEO audits to your users? Get in touch.",
                    "url": "http:\/\/howgoodisyourseo.com\/",
                    "title": "How good is your SEO?",
                    "type": "organic",
                    "page_number": 1,
                    "top_left": "150,176",
                    "bottom_right": "782,328"
                },
                ......

            },
            "news": {},
            "image": {},
            "place": {}
        },
        "summary": {
            "global": {
                "video": 0,
                "organic": 10,
                "total": 42200000,
                "image": 0,
                "news": 0,
                "place": 0
            },
            "pages": {
                "1": {
                    "video": 0,
                    "news": 0,
                    "image": 0,
                    "place": 0,
                    "organic": 10
                }
            }
        }
    }
}

The response object has two main elements results and summary

Results

The results element contains structured information about the search results entries found grouped by type.

The special type Universal contains all organic elements.

The special type Paid contains all paid elements.

Each result entry is structured with the position (ranking) as key and the search result parsed information as value.


Summary

The summary element contains the aggregated amount of elements found in the SERPs as well as a per page amount.

The total field of the global summary contains the total number of search results the selected search engine has, not the number of returned elements.


Note

Please read The Response Object in detail for more information.

GET /search_results/(.*)

Returns information about an existing job.

After successfully requesting a job (see POST method on how to request a job), you can use this request to get available information for the returned jid

Example Request

GET /serps/XXXXXXX HTTP/1.1
Host: v3.api.analyticsseo.com

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "request": {
        "language": "en",
        "parameters": {},
        "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
        "search_engine": "google",
        "phrase": "how good is your SEO",
        "region": "gb",
        "max_results": 100,
        "town": null
  },
  "ready": false,
  "jid": "7338aa04-d750-43c6-a3fc-e2762e16e503",
  "response": {"...."}
}

Response Codes

Code Name Explanation
200 OK We found the jid and returned available data
404 Not Found the jid does not exist or has already expired (they are kept at most for 24h)

The Response Object

Field Type Description Notes
jid string the unique identifier for your job (job id)  
ready boolean when false mean the job is being processed  
request object contains a copy of your request  
error string contains an error message only present if there is an error
response object when ready it will contain the processed SERPs page results see The Response Object in detail

Note

The response field named response will contain the parsed SERPs results. Read The Response Object in detail for more information.


The Response Structure

{
    "response": {
        "results": {
            "video": {},
            "organic":{
                .....
            },
            "universal": {
                "1": {
                    "rich_snippets": [

                    ],
                    "description": "How good is your SEO? enter your domain below to find out ... Domain ... Get this for your site! Want to offer free SEO audits to your users? Get in touch.",
                    "url": "http:\/\/howgoodisyourseo.com\/",
                    "title": "How good is your SEO?",
                    "type": "organic",
                    "page_number": 1,
                    "top_left": "150,176",
                    "bottom_right": "782,328"
                },
                ......

            },
            "news": {},
            "image": {},
            "place": {}
        },
        "summary": {
            "global": {
                "video": 0,
                "organic": 10,
                "total": 42200000,
                "image": 0,
                "news": 0,
                "place": 0
            },
            "pages": {
                "1": {
                    "video": 0,
                    "news": 0,
                    "image": 0,
                    "place": 0,
                    "organic": 10
                }
            }
        }
    }
}

The response object has two main elements results and summary

Results

The results element contains structured information about the search results entries found grouped by type.

The special type Universal contains all organic elements.

The special type Paid contains all paid elements.

Each result entry is structured with the position (ranking) as key and the search result parsed information as value.


Summary

The summary element contains the aggregated amount of elements found in the SERPs as well as a per page amount.

The total field of the global summary contains the total number of search results the selected search engine has, not the number of returned elements.


Note

Please read The Response Object in detail for more information.


GET /account

Returns account information

Example Request

GET /account HTTP/1.1
Host: v3.api.analyticsseo.com
Authorization:  KeyAuth publicKey=XXX hash=XXXXXXXXXXXX ts=1234567890

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
     "methods": [
         "serps.api"
     ],
     "account": {
         "name": "CompanyX",
         "public_key": "XXX"
         "current_monthly_usage": 497,
         "monthly_account_limit": 10000,
     }
 }

The Response Object

Field Type Description
name string account name
public_key string account public key
methods array the list of allowed API endpoints to request by this account
current_monthly_usage int credits used by this account from the beginning of the month
monthly_account_limit int monthly account credits limit