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