< Back to Knowledge Base

Overview

Endpoint is https://checkserp.com/api/v1.

All incoming and outgoing data is UTF-8 encoding.

All API calls must be made with HTTPS, request method is GET if not specified.

When sending data with POST, PUT, DELETE method, all data should be JSON encoded string and indicate Content-Type: application/json in Header.

Output result is the array in JSON format.

API Authentication

While calling each API method, Token is required by appending api_token=your-token parameter in API calls. You can manage your API Token here.

Unauthenticated API calls will get HTTP 401 Unauthenticated response.

API Requests Limits

Call to API limit is 60 per minute. Calls exceed this rate limit will get HTTP 429 Too Many Requests response.

Available API Operations:

Example Code in PHP:

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://checkserp.com/api/v1/projects',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ],
]);

$post_data = [
    'api_token' => 'your-token',
    'data' => [
        'name' => 'project_name'
    ]
];
curl_setopt_array($curl, [
    CURLOPT_POSTFIELDS => json_encode($post_data)
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    echo $response;
}

Example API Response:

Successful response:

{
   "success": true,
   "example_data": {
      "key": "value",
        ...
   }
}

Failed response:

{
   "success": false,
   "error": "Error message."
}

List Projects

Request Path: /projects

Parameters:

  • pagesize: int
    optional, possible values: 20, 100, 500, 1000, default 20
  • page: int
    optional, default 1

Example Successful Response:

{
    "success": true,
    "total": 125,
    "results": [
        {
            "id": 21049,
            "name": "project_name",
            "addtime": 1534816800,
            "trackings_count": 698
        },
        ...
    ]
}
  • total: total number of projects
  • results:
    • id: unique identifier
    • name: project name
    • addtime: timestamp of project creation
    • trackings_count: project tracking terms count

Create Project

Method: POST

Request Path: /projects

Parameters:

  • data:
    • name: string
      project name
    • assign_users: array
      optional, array of your sub account ids to assign this project to

Example Successful Response:

{
   "success": true,
   "project": {
      "id": 139
   }
}
  • project:
    • id: unique identifier

Update Project

Method: PUT

Request Path: /projects/{project_id}

Parameters:

  • data:
    • name: string
      required, project name
    • assign_users: array
      optional, array of your sub account ids to assign this project to, omit this field for no change, pass empty array to disconnect all sub accounts from this project

Example Successful Response:

{
   "success": true
}

Delete Project

Method: DELETE

Request Path: /projects/{project_id}

Parameters:

  • (no)

Example Successful Response:

{
   "success": true
}

Get Project Info

Request Path: /projects/{project_id}

Parameters:

  • pagesize: int
    optional, tracking terms pagesize, possible values: 100, 200, 500, 1000, default pagesize set in your settings page
  • view: string
    optional, how tracking terms are grouped, possible values: "url", "keyword", default view set in your settings page
  • sort: string
    optional, how tracking terms are sorted, possible values: "asc": older terms first, "desc": newer terms first, default sort set in your settings page

Example Successful Response:

{
    "success": true,
    "total": 8,
    "results": [{
         "title": "https://example.com/url_1",
         "trackings": [{
               "id": 8797,
               "url": "https://example.com/url_1",
               "engine": {
                  "showname": "Google.com",
                  "country_code": "US"
               },
               "keyword": "my keyword",
               "type": 2,
               "rank": 7,
               "indexed_url": "https://example.com/url_1",
               "day": 8,
               "week": 0,
               "month": 7,
               "last_check": 1524360980
            },
            ...
         ]
      },
      ...
    ]
}
  • total: total number of project tracking terms
  • results: terms grouped by url or keyword
    • title: terms group title, url if grouped by url, keyword if grouped by keyword
    • trackings:
      • id: unique identifier
      • url: tracking url
      • engine:
        • showname: search engine name
        • country_code: search engine country code
      • keyword: tracking term keyword
      • type: tracking type, 0: organic, 1: mobile, 2: map pack
      • rank: latest rank
      • indexed_url: URL indexed in SERPs
      • day: rank one day before
      • week: rank one week before
      • month: rank one month before
      • last_check: timestamp of last check

Add Tracking Terms to Project

Method: POST

Request Path: /trackings

Parameters:

  • data:
    • project_id: int
      target project id
    • url: string
      your URL to check position in search engines
    • exact_match: bool
      optional, if is exact match, default false, what is "exact match"
    • se_ids: array
      array of search engine ids to track the term in, list search engines
    • location_id: int
      optional, id of location used to search results in search engine
      required if search engine contains Google mobile or Google Map Pack
    • language: string
      optional, language used to search results in search engine
      possible values: en (English), ar (Arabic), bg (Bulgarian), ca (Catalan), zh-CN (Chinese Simplified), zh-TW (Chinese Traditional), hr (Croatian), cs (Czech), da (Danish), nl (Dutch), et (Estonian), fi (Finnish), fr (French), de (German), el (Greek), iw (Hebrew), hu (Hungarian), is (Icelandic), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), lv (Latvian), lt (Lithuanian), no (Norwegian), pl (Polish), ro (Romanian), pt (Portuguese), ru (Russian), sr (Serbian), sk (Slovak), sl (Slovenian), es (Spanish), sv (Swedish), tr (Turkish)
    • business_name: string
      optional, your business name in Google map pack results
      required if search engine contains Google map pack
    • keywords: array
      array of tracking term keywords

Example Successful Response:

{
    "success": true,
    "trackings": [
        1001,
        1002
    ]
}
  • trackings: array of added tracking term ids

Delete Tracking Terms from Project

Method: DELETE

Request Path: /trackings

Parameters:

  • project_id: int
    project id to delete tracking terms from
  • ids: array
    array of tracking term ids to delete

Example Successful Response:

{
    "success": true
}

List Automated Reports

Request Path: /reports

Parameters:

  • pagesize: int
    optional, possible values: 20, 50, 100, default 20
  • page: int
    optional, default 1

Example Successful Response:

{
    "success": true,
    "total": 23,
    "results": [
        {
            "id": 1001,
            "subject": "CheckSERP Campaign Report",
            "sender_email": 0,
            "send_to": [
                "[email protected]il.com",
                "[email protected]"
            ],
            "frequency": "d",
            "project_id": 100,
            "view": "url",
            "attach_pdf": 0,
            "pdf_only": 0,
            "last_sent": 1565747640,
            "next_send": 1565834040
        },
        ...
    ]
}
  • total: total number of automated reports
  • results:
    • id: unique identifier
    • subject: report subject
    • sender_email: sender email account id, 0: default CheckSERP sender email, send reports from your own email address
    • send_to: send to emails
    • frequency: report frequency, d: daily, w: weekly, b: biweekly, m: monthly
    • project_id: id of project to show in the report
    • view: how tracking terms grouped in report
    • attach_pdf: if attach pdf in report
    • pdf_only: if report is pdf only
    • last_sent: timestamp of last sent time
    • next_send: timestamp of next send time

Create Automated Report

Method: POST

Request Path: /reports

Parameters:

  • data:
    • subject: string
      report subject
    • sender_email: int
      sender email account id, 0 to use CheckSERP default email account, send reports from your own email address
    • send_to: array
      array of send to emails, max 5
    • frequency: string
      optional, report frequency, possible values: d: daily, w: weekly, b: biweekly, m: monthly, default "d"
    • project_id: int
      id of project to show in the report
    • view: string
      optional, how tracking terms grouped in report, possible values: "url", "keyword", default "url"
    • attach_pdf: bool
      optional, if attach pdf in report, default false
    • pdf_only: bool
      optional, if report is pdf only, default false

Example Successful Response:

{
    "success": true,
    "report": {
        "id": 1001
    }
}
  • report:
    • id: unique identifier

Update Automated Report

Method: PUT

Request Path: /reports/{report_id}

Parameters:

  • data:
    • subject: string
      report email subject
    • sender_email: int
      sender email account id, 0 to use CheckSERP default email account, send reports from your own email address
    • send_to: array
      array of send to emails, max 5
    • frequency: string
      report frequency, possible values: d: daily, w: weekly, b: biweekly, m: monthly
    • project_id: int
      id of project to show in the report
    • view: string
      how tracking terms grouped in report, possible values: "url", "keyword"
    • attach_pdf: bool
      optional, if attach pdf in email, default false
    • pdf_only: bool
      optional, if report is pdf only email, default false

Example Successful Response:

{
    "success": true
}

Delete Automated Report

Method: DELETE

Request Path: /reports/{report_id}

Parameters:

  • (no)

Example Successful Response:

{
   "success": true
}

List Shared Reports

Request Path: /shared_reports

Parameters:

  • pagesize: int
    optional, possible values: 20, 50, 100, default 20
  • page: int
    optional, default 1

Example Successful Response:

{
    "success": true,
    "total": 23,
    "results": [
        {
            "id": 1001,
            "name": "Shared report name",
            "project_id": 2001,
            "view_key": "IbG6GTi8uYSrsiBE",
            "password": "",
            "expiration": 0,
            "addtime": 1534143328,
            "project": {
                "id": 2001,
                "name": "Project name",
                "addtime": 1526731600
            }
        },
        ...
    ]
}
  • total: total number of shared reports
  • results:
    • id: unique identifier
    • name: shared report name
    • project_id: id of project assigned to the report
    • view_key: report view key
    • password: report view password
    • expiration: timestamp of report expiration, 0 for no expiration
    • addtime: timestamp of report creation
    • project: project assigned to the report

Create Shared Report

Method: POST

Request Path: /shared_reports

Parameters:

  • data:
    • name: string
      shared report name
    • password: string
      optional, view report password
    • expiration: int
      optional, timestamp of report expiration
    • project_id: int
      id of project to assign to the report

Example Successful Response:

{
    "success": true,
    "report": {
        "id": 1001
    }
}
  • report:
    • id: unique identifier

Update Shared Report

Method: PUT

Request Path: /shared_reports/{report_id}

Parameters:

  • data:
    • name: string
      shared report name
    • password: string
      optional, view report password, omit this field for no change, pass empty string for no password
    • expiration: int
      optional, timestamp of report expiration
    • project_id: int
      id of project to assign to the report
    • new_view_link: bool
      optional, set true to generate a new view link for report

Example Successful Response:

{
    "success": true
}

Delete Shared Report

Method: DELETE

Request Path: /shared_reports/{report_id}

Parameters:

  • (no)

Example Successful Response:

{
   "success": true
}

List Sub Accounts

Request Path: /sub_accounts

Parameters:

  • pagesize: int
    optional, possible values: 20, 50, 100, default 20
  • page: int
    optional, default 1

Example Successful Response:

{
    "success": true,
    "total": 23,
    "results": [
        {
            "id": 1001,
            "email": "[email protected]",
            "usage" {
                "individual": {
                    "terms": {
                        "capacity": 10,
                        "used": 10,
                        "remaining": 0
                    },
                    "competitor_analysis": {
                        "capacity": 0,
                        "used": 0,
                        "remaining": 0
                    },
                    "keyword_research": {
                        "capacity": 0,
                        "used": 0,
                        "remaining": 0
                    }
                }
            },
            "addtime": 1534816800,
            "permission": {
                "create_project": 0,
                "delete_project": 1,
                "create_tracking": 1,
                "delete_tracking": 1,
                "create_competitor_analysis": 0,
                "create_keyword_research": 1,
                "terms_limit": 10,
                "competitor_analysis_limit": 0,
                "keyword_research_limit": 0
            }
        },
        ...
    ]
}
  • total: total number of sub accounts
  • results:
    • id: unique identifier
    • email: sub account email
    • usage:sub account resource usage
    • addtime: timestamp of sub account creation
    • permission: sub account permission

Create Sub Account

Method: POST

Request Path: /sub_accounts

Parameters:

  • data:
    • user:
      • email: string
        sub account email
      • password: string
        sub account password
    • permissions:
      • create_project: bool
        if sub account can create new projects
      • delete_project: bool
        if sub account can delete projects from assigned projects, this is soft delete, only account owner can actually delete a project
      • create_tracking: bool
        if sub account can create new tracking terms to assigned projects
      • terms_limit: int
        how many tracking terms can this sub account create
      • delete_tracking: bool
        if sub account can delete tracking terms from assigned projects, this is hard delete
      • create_competitor_analysis: bool
        if sub account can access competitor analysis feature
      • competitor_analysis_limit: int
        daily competitor analysis report result rows limit
      • create_keyword_research: bool
        if sub account can access keyword research feature
      • keyword_research_limit: int
        daily keyword research report result rows limit
    • assign_projects: array
      optional, array of project ids that will be available for this sub account

Example Successful Response:

{
    "success": true,
    "sub_account": {
        "id": 1001
    }
}
  • sub_account:
    • id: unique identifier

Update Sub Account

Method: PUT

Request Path: /sub_accounts/{sub_account_id}

Parameters:

  • data:
    • user:
      • email: string
        sub account email
      • password: string
        optional, sub account password, omit this field for no change
    • permissions:
      • create_project: bool
        if sub account can create new projects
      • delete_project: bool
        if sub account can delete projects from assigned projects, this is soft delete, only account owner can actually delete a project
      • create_tracking: bool
        if sub account can create new tracking terms to assigned projects
      • terms_limit: int
        how many tracking terms can this sub account create
      • delete_tracking: bool
        if sub account can delete tracking terms from assigned projects, this is hard delete
      • create_competitor_analysis: bool
        if sub account can access competitor analysis feature
      • competitor_analysis_limit: int
        daily competitor analysis report result rows limit
      • create_keyword_research: bool
        if sub account can access keyword research feature
      • keyword_research_limit: int
        daily keyword research report result rows limit
    • assign_projects: array
      optional, array of project ids that will be available for this sub account, omit this field for no change, pass empty array to disconnect all projects from this sub account

Example Successful Response:

{
    "success": true
}

Delete Sub Account

Method: DELETE

Request Path: /sub_accounts/{sub_account_id}

Parameters:

  • (no)

Example Successful Response:

{
   "success": true
}

Account Usage

Request Path: /credits

Parameters:

  • (no)

Example Successful Response:

{
    "success": true,
    "credits": {
        "individual": {
            "terms": {
                "capacity": 1990,
                "used": 30,
                "remaining": 1960
            },
            "auto_reports": {
                "capacity": 100,
                "used": 1,
                "remaining": 99
            },
            "shared_reports": {
                "capacity": 100,
                "used": 2,
                "remaining": 98
            },
            "sub_accounts": {
                "capacity": 20,
                "used": 1,
                "remaining": 19
            },
            "competitor_analysis": {
                "capacity": 2000,
                "used": 0,
                "remaining": 2000
            },
            "keyword_research": {
                "capacity": 2000,
                "used": 0,
                "remaining": 2000
            }
        },
        "overall": {
            "terms": {
                "capacity": 2000,
                "used": 30,
                "remaining": 1970
            },
            "auto_reports": {
                "capacity": 100,
                "used": 1,
                "remaining": 99
            },
            "shared_reports": {
                "capacity": 100,
                "used": 2,
                "remaining": 98
            },
            "sub_accounts": {
                "capacity": 20,
                "used": 1,
                "remaining": 19
            },
            "competitor_analysis": {
                "capacity": 2000,
                "used": 0,
                "remaining": 2000
            },
            "keyword_research": {
                "capacity": 2000,
                "used": 0,
                "remaining": 2000
            }
        }
    }
}
  • credits:
    • individual: usage excluding sub account resources
    • overall: account overall usage, i.e., including sub account resources

List Search Engines

Request Path: /common/ses

Parameters:

  • (no)

Example Successful Response:

{
    "success": true,
    "results": [
        {
            "se_id": 1401,
            "se_group": "Google mobile",
            "se_showname": "Google.com mobile"
        },
        {
            "se_id": 1745,
            "se_group": "Google map pack",
            "se_showname": "Google.com map pack"
        },
        {
            "se_id": 14,
            "se_group": "Google",
            "se_showname": "Google.com"
        },
        {
            "se_id": 1012,
            "se_group": "Bing",
            "se_showname": "Bing US"
        },
        ...
    ]
}

Find Location

Request Path: /common/locations

Parameters:

  • q: string
    location keyword, min 3 characters, like "miami, florida"

Example Successful Response:

{
    "success": true,
    "results": [
        {
            "id": 1015116,
            "type": "City",
            "name": "Miami,Florida,United States"
        },
        {
            "id": 1015117,
            "type": "City",
            "name": "Miami Beach,Florida,United States"
        },
        ...
    ]
}

 

help icon

Need more help?

If you need more help, please contact us and we will be more than happy to help you.