< 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, 50, 100, 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]",
                "[email protected]"
            ],
            "frequency": "d",
            "project_id": 100,
            "view": "url",
            "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
    • 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"

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"

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 Competitor Top Keywords Results

Request Path: /competitor_top_keywords

Parameters:

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

Example Successful Response:

{
    {
    "success": true,
    "total": 5,
    "results": [
        {
            "id": 23686,
            "domain": "example.com",
            "country_code": "US",
            "language": "en",
            "orderby": "position,asc",
            "limit": 200,
            "count": 200,
            "addtime": 1534143328,
            "country_language": "United States, English",
            "user": {
                "id": 10253,
                "email": "[email protected]"
            }
        },
        ...
    ]
}
}
  • total: total number of competitor top keywords results
  • results:
    • id: unique identifier
    • domain: competitor domain
    • country_code: ISO country code
    • language: Language code
    • limit: result limit
    • count: actual result rows
    • addtime: timestamp of creation
    • country_language: Country and language
    • user: creator for this competitor top keywords, may be user or sub user
      • id: unique identifier
      • email: creator email

Create Competitor Top Keywords

Method: POST

Request Path: /competitor_top_keywords

Parameters:

  • data:
    • domain: string
      competitor domain
    • country_lang: string
      country and language, possible values:
      - DZ_fr: Algeria, French
      - AR_es: Argentina, Spanish
      - AU_en: Australia, English
      - AT_de: Austria, German
      - BD_bn: Bangladesh, Bengali
      - BE_fr: Belgium, French
      - BE_nl: Belgium, Dutch
      - BO_es: Bolivia, Spanish
      - BR_pt: Brazil, Portuguese
      - BG_bg: Bulgaria, Bulgarian
      - CA_en: Canada, English
      - CL_es: Chile, Spanish
      - CO_es: Colombia, Spanish
      - CR_es: Costa Rica, Spanish
      - HR_hr: Croatia, Croatian
      - CZ_cs: Czechia, Czech
      - DK_da: Denmark, Danish
      - EC_es: Ecuador, Spanish
      - EG_ar: Egypt, Arabic
      - SV_es: El Salvador, Spanish
      - EE_et: Estonia, Estonian
      - FI_fi: Finland, Finnish
      - FR_fr: France, French
      - DE_de: Germany, German
      - GR_el: Greece, Greek
      - GT_es: Guatemala, Spanish
      - HK_zh_tw: Hong Kong, Chinese (Traditional)
      - HU_hu: Hungary, Hungarian
      - IN_en: India, English
      - ID_id: Indonesia, Indonesian
      - IE_en: Ireland, English
      - IL_iw: Israel, Hebrew
      - IL_ar: Israel, Arabic
      - IT_it: Italy, Italian
      - JP_ja: Japan, Japanese
      - MY_ms: Malaysia, Malay
      - MT_en: Malta, English
      - MX_es: Mexico, Spanish
      - NL_nl: Netherlands, Dutch
      - NZ_en: New Zealand, English
      - NI_es: Nicaragua, Spanish
      - NO_no: Norway, Norwegian
      - PY_es: Paraguay, Spanish
      - PE_es: Peru, Spanish
      - PL_pl: Poland, Polish
      - PT_pt: Portugal, Portuguese
      - RO_ro: Romania, Romanian
      - RU_ru: Russia, Russian
      - SA_ar: Saudi Arabia, Arabic
      - RS_sr: Serbia, Serbian
      - SG_en: Singapore, English
      - SK_sk: Slovakia, Slovak
      - SI_sl: Slovenia, Slovenian
      - ZA_en: South Africa, English
      - ES_es: Spain, Spanish
      - LK_en: Sri Lanka, English
      - SE_sv: Sweden, Swedish
      - CH_fr: Switzerland, French
      - CH_de: Switzerland, German
      - TW_zh_tw: Taiwan, Chinese (Traditional)
      - TH_th: Thailand, Thai
      - TN_ar: Tunisia, Arabic
      - TR_tr: Turkey, Turkish
      - UA_ru: Ukraine, Russian
      - UA_uk: Ukraine, Ukrainian
      - AE_ar: United Arab Emirates, Arabic
      - AE_en: United Arab Emirates, English
      - GB_en: United Kingdom, English
      - US_en: United States, English
      - UY_es: Uruguay, Spanish
      - VE_es: Venezuela, Spanish
      - VN_vi: Vietnam, Vietnamese
    • limit: int
      result limit, possible values: 10, 100, 200, 500, 1000
    • orderby: string
      order of results, possible values and meaning:
      - position,asc: keyword position, high → low
      - position,desc: keyword position, low → high
      - search_volume,desc: search volume, high → low
      - search_volume,asc: search volume, low → high
      - results_count,desc: results count, high → low
      - results_count,asc: results count, low → high
      - competition,asc: competition, low → high
      - competition,desc: competition, high → low
      - cpc,desc: keyword cpc, high → low
      - cpc,asc: keyword cpc, low → high

Example Successful Response:

{
    "success": true,
    "results": {
        "competitor_top_keywords_id": 10001
    }
}
  • results:
    • competitor_top_keywords_id: unique identifier

Get a Competitor Top Keywords Result

Request Path: /competitor_top_keywords/{competitor_top_keywords_id}

Parameters:

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

Example Successful Response:

{
    "success": true,
    "total": 10
    "results": {
        "competitor_top_keywords": {
            "id": 10001,
            "domain": "example.com",
            "country_code": "US",
            "language": "en",
            "limit": 100,
            "orderby": "position,asc",
            "addtime": 1534143328,
            "result": {
                "meta": {
                    "domain": "example.com",
                    "actual_metric": {
                        "etv": 66147,
                        "pos1": 801,
                        "pos2_3": 696,
                        "pos4_10": 1217,
                        "pos11_20": 883,
                        "pos21_30": 625,
                        "pos31_40": 542,
                        "pos41_50": 514,
                        "pos51_60": 549,
                        "pos61_70": 517,
                        "pos71_80": 521,
                        "pos81_90": 523,
                        "pos91_100": 507
                    }
                },
                "ranked": [
                    {
                        "key": "example keywords",
                        "position": 1,
                        "url": "https://example.com/",
                        "relative_url": "/",
                        "results_count": 342000,
                        "etv": 304,
                        "competition": 0.139455,
                        "cpc": 7.782717,
                        "date": "2018-08-13T00:00:00+00:00",
                        "search_volume": 1000,
                        "title": "Page Title",
                        "results_count_short": "342 K"
                    },
                    ...
                ]
            }
        }
    }
}
  • total: total number of ranked keywords
  • results:
    • competitor_top_keywords:
      • id: unique identifier
      • domain: competitor domain
      • country_code: ISO country code
      • language: Language code
      • limit: result limit
      • orderby: result order
      • addtime: timestamp of creation
      • results:
        • meta:
          • domain: competitor domain
          • actual_metric:
            • etv: estimated monthly visits
            • pos1: keywords count ranking 1
            • pos2_3: keywords count ranking 2-3
            • pos4_10: keywords count ranking 4-10
            • pos11_20: keywords count ranking 11-20
            • pos21_30: keywords count ranking 21-30
            • pos31_40: keywords count ranking 31-40
            • pos41_50: keywords count ranking 41-50
            • pos51_60: keywords count ranking 51-60
            • pos61_70: keywords count ranking 61-70
            • pos71_80: keywords count ranking 71-80
            • pos81_90: keywords count ranking 81-90
            • pos91_100: keywords count ranking 91-100
        • ranked:
          • key: ranked keyword
          • position: rank position
          • url: url
          • relative_url: relative url
          • results_count: total results count for this keyword
          • etv: estimated monthly visit for this keyword
          • competition: Google Adwords competition
          • cpc: Google Adwords cost per click value
          • search_volume: monthly searches
          • title: title in SERP
          • results_count_short: short for results count

List Keyword Research Results

Request Path: /keyword_research

Parameters:

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

Example Successful Response:

{
    {
    "success": true,
    "total": 5,
    "results": [
        {
            "id": 23686,
            "type": "related",
            "keyword": "example keyword",
            "country_code": "US",
            "language": "en",
            "orderby": "search_volume,desc",
            "limit": 200,
            "count": 200,
            "addtime": 1534143328,
            "country_language": "United States, English",
            "user": {
                "id": 10253,
                "email": "[email protected]"
            }
        },
        ...
    ]
}
}
  • total: total number of keyword research results
  • results:
    • id: unique identifier
    • type: related or similar
    • keyword: keyword term
    • country_code: ISO country code
    • language: Language code
    • limit: result limit
    • count: actual result rows
    • addtime: timestamp of creation
    • country_language: Country and language
    • user: creator for this keyword research, may be user or sub user
      • id: unique identifier
      • email: creator email

Create Keyword Research

Method: POST

Request Path: /keyword_research

Parameters:

  • data:
    • keyword: string
      keyword term
    • country_lang: string
      country and language, possible values:
      - DZ_fr: Algeria, French
      - AR_es: Argentina, Spanish
      - AU_en: Australia, English
      - AT_de: Austria, German
      - BD_bn: Bangladesh, Bengali
      - BE_fr: Belgium, French
      - BE_nl: Belgium, Dutch
      - BO_es: Bolivia, Spanish
      - BR_pt: Brazil, Portuguese
      - BG_bg: Bulgaria, Bulgarian
      - CA_en: Canada, English
      - CL_es: Chile, Spanish
      - CO_es: Colombia, Spanish
      - CR_es: Costa Rica, Spanish
      - HR_hr: Croatia, Croatian
      - CZ_cs: Czechia, Czech
      - DK_da: Denmark, Danish
      - EC_es: Ecuador, Spanish
      - EG_ar: Egypt, Arabic
      - SV_es: El Salvador, Spanish
      - EE_et: Estonia, Estonian
      - FI_fi: Finland, Finnish
      - FR_fr: France, French
      - DE_de: Germany, German
      - GR_el: Greece, Greek
      - GT_es: Guatemala, Spanish
      - HK_zh_tw: Hong Kong, Chinese (Traditional)
      - HU_hu: Hungary, Hungarian
      - IN_en: India, English
      - ID_id: Indonesia, Indonesian
      - IE_en: Ireland, English
      - IL_iw: Israel, Hebrew
      - IL_ar: Israel, Arabic
      - IT_it: Italy, Italian
      - JP_ja: Japan, Japanese
      - MY_ms: Malaysia, Malay
      - MT_en: Malta, English
      - MX_es: Mexico, Spanish
      - NL_nl: Netherlands, Dutch
      - NZ_en: New Zealand, English
      - NI_es: Nicaragua, Spanish
      - NO_no: Norway, Norwegian
      - PY_es: Paraguay, Spanish
      - PE_es: Peru, Spanish
      - PL_pl: Poland, Polish
      - PT_pt: Portugal, Portuguese
      - RO_ro: Romania, Romanian
      - RU_ru: Russia, Russian
      - SA_ar: Saudi Arabia, Arabic
      - RS_sr: Serbia, Serbian
      - SG_en: Singapore, English
      - SK_sk: Slovakia, Slovak
      - SI_sl: Slovenia, Slovenian
      - ZA_en: South Africa, English
      - ES_es: Spain, Spanish
      - LK_en: Sri Lanka, English
      - SE_sv: Sweden, Swedish
      - CH_fr: Switzerland, French
      - CH_de: Switzerland, German
      - TW_zh_tw: Taiwan, Chinese (Traditional)
      - TH_th: Thailand, Thai
      - TN_ar: Tunisia, Arabic
      - TR_tr: Turkey, Turkish
      - UA_ru: Ukraine, Russian
      - UA_uk: Ukraine, Ukrainian
      - AE_ar: United Arab Emirates, Arabic
      - AE_en: United Arab Emirates, English
      - GB_en: United Kingdom, English
      - US_en: United States, English
      - UY_es: Uruguay, Spanish
      - VE_es: Venezuela, Spanish
      - VN_vi: Vietnam, Vietnamese
    • type: string
      keyword research type, possible values: related, similar
    • limit: int
      result limit, possible values: 10, 100, 200, 500, 1000
    • orderby: string
      order of results, possible values and meaning:
      - search_volume,desc: search volume, high → low
      - search_volume,asc: search volume, low → high
      - competition,asc: competition, low → high
      - competition,desc: competition, high → low
      - cpc,desc: keyword cpc, high → low
      - cpc,asc: keyword cpc, low → high

Example Successful Response:

{
    "success": true,
    "results": {
        "keyword_research_id": 10001
    }
}
  • results:
    • keyword_research_id: unique identifier

Get a Keyword Research Result

Request Path: /keyword_research/{keyword_research_id}

Parameters:

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

Example Successful Response:

{
    "success": true,
    "total": 10
    "results": {
        "keyword_research": {
            "id": 10001,
            "type": "related",
            "keyword": "example keyword",
            "country_code": "US",
            "language": "en",
            "limit": 100,
            "orderby": "search_volume,desc",
            "addtime": 1534143328,
            "result": {
                "meta": {
                    "keyword": "example keyword",
                },
                "related": [
                    {
                        "key": "example related keyword",
                        "country_code": "US",
                        "language": "en",
                        "search_volume": 1000,
                        "competition": 0.15521093441976605,
                        "cpc": 8.744439,
                        "history": [
                            1000,
                            1300,
                            1300,
                            1900,
                            1600,
                            2400,
                            1900,
                            2400,
                            2400,
                            1900,
                            2400,
                            2400
                        ]
                    },
                    ...
                ]
            }
        }
    }
}
  • total: total number of ranked keywords
  • results:
    • keyword_research:
      • id: unique identifier
      • type: keyword research type
      • keyword: keyword term
      • country_code: ISO country code
      • language: Language code
      • limit: result limit
      • orderby: result order
      • addtime: timestamp of creation
      • results:
        • meta:
          • keyword: keyword term
        • related: or similar, related or similar keywords list
          • key: keyword term
          • country_code: ISO country code
          • language: keyword language
          • search_volume: monthly searches
          • competition: Google Adwords competition
          • cpc: Google Adwords cost per click value
          • history: monthly searches for the last 12 months

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_top_keywords": {
                        "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_top_keywords": 0,
                "create_keyword_research": 1,
                "terms_limit": 10,
                "competitor_top_keywords_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_top_keywords: bool
        if sub account can access competitor top keywords feature
      • competitor_top_keywords_limit: int
        daily competitor top keywords 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_top_keywords: bool
        if sub account can access competitor top keywords feature
      • competitor_top_keywords_limit: int
        daily competitor top keywords 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_top_keywords": {
                "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_top_keywords": {
                "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.