serpstat-api-3 v0.4.0

Serpstat SDK it is powerfull JS-library for Internet marketing, SEO, Search Analitics and Keywords Research. Works in Node.js and Browsers.

Install

Node.js

Node.js >= 4.9.1

  npm install serpstat-api-3

  var SerpstatAPI = require('serpstat-api-3');

Browser

Or Browser with ES6 support (will work with 95-99% of users)

   <script src="https://cdn.jsdelivr.net/npm/serpstat-api-3@0.4/serpstat-api.js"></script>

Usage

Init api

It is recommended to use SerpstatAPI.init({...}), not new SerpstatAPI({...}). The second SerpstatAPI.init call with the same token will not create a new object, but return the old one.

	var api = SerpstatAPI.init({
		token   :token,
		requestsPerSecond: 9
	});

token

You need enter Serpstat API Token. How To Get a Token

requestsPerSecond

SDK has an automatic frequency limiter. But in this version you nead to enter Rate Limit manualy when init API.

• Plan B have 1 request per second limit.
• Other plans have 10 request per second limit

Get left lines

	var api = SerpstatAPI.init({
		...
	}).then(function(){
		console.log(api.userStats.left_lines);
	});

api.userStats.left_lines automatically updated after each request.

Call API method

For methods names see API documentation

api.createTask(methodName, opts) returns Promise.

	api.createTask('domain_keywords',{
		limit : 100,
		se    : 'g_us',
		query : 'serpstat.com'
	}).then(function(results){
		console.log(results);
	}).catch(function(err){
		console.error(err);
	});

OR api.methodName(opts) OR api.method_name(opts)

	api.domainKeywords({
		...
	}).then(function(results){
		console.log(results);
	},function(err){
		console.error(err);
	});

se

List of Search Engines and Regions

limit

SDK supports loading more than 1000 results in a single method call. In this case, SDK will automatically download several results pages from the server.

Multi regions and queries

	api.domain_keywords({
		limit : 100,
		se    : ['g_us','g_ru','g_ua'],
		query : ['serpstat.com','netpeak.com']
	})

This code can return up to 3x2x100 = 600 rows.

Due to the support of many regions and queries in one request, columns _se and _query are added to the results.

async/await

For Node.js >= 7.6 you can use async/await

	var results = await api.createTask('domain_keywords',{
		limit : 100,
		se    : 'g_us',
		query : 'serpstat.com'
	});
	console.log(results)

Methods

Domain

In query list of domain

Keyword

URL

In query list of URLs

Integration with alaSQL

//include and init SDK
//include alasql

api.patchAlasql(alasql);

alasql.serpstatPromise('SELECT * FROM Serpstat("competitors",{"se":"g_us","query":"serpstat.com"} ').then(console.log);

alasql.serpstatPromise(
  'SELECT * FROM Serpstat("competitors",{"limit":2, "query" : "~GUI~",    \
      "se"    : "<<<    --nested SQL request                                                    \
          SELECT `db_name` FROM Serpstat("databases_info")                       \
          WHERE (`db_name` LIKE "y_%")                                                         \
          LIMIT 3                                                                                               \
  >>>"})').then(console.log);

Warnings

Safari

May not work on Safari

Big data

Browser Tab may fall if downloaded rows > 100,000

Spend more rows than return

Some new features as *_keywords_match_sdk spend more rows than return.

Slow methods

Methods get_top_urls, domains_intersection, domains_uniq_keywords can take up to 10 minutes

limit < 1000 || limit%1000===0

The limit must be less than 1000 OR be divided by 1000: 1,2,3,...,999,1000,2000,3000, ... Not 1001, 2100, 5999. Offset must be be divided by 1000.

Downloaded rows > limit

If you enter few regions or se or use methods and SDK can load more then limit rows.

keyword_top and limit

In keywords_top and keyword_top_and_info no limit parameteres. This methods can demand up to 101 rows per query and se combination.

Differences from API

• Supports multi regions (se) and queries
• Retry on some errors
• Client-side cache
• Can download more than 1000 rows
• All results in array of object format {...},{...},...
• Added 2 columns in results (_se and _query)
• In some methods added column traff
• New method keyword_top_and_info - join of keyword_top and keyword_info methods
• New method domains_keywords_match_sdk - join of keyword_top and keyword_info methods
• You can enter keywords in Generator syntax (ny|n y) (hotel|hostel)
• In some domain methods you can enter URL part (serpstat.com/blog/)

*_keywords_match_sdk

There are new methods that make a comparison of keywords of several domains or Url on a local machine. They first download data to the local machine, and then compare keywords.

domains_keywords_match_sdk

More fast, advances alternative to domains_intersection and domains_uniq_keywords.

domains_ad_keywords_match_sdk

Same as previus method but match Google Ads keywords (not organic).

urls_keywords_match_sdk

Match urls keywords

hits_from

The minimum number of domains or urls that have this keyword.

expand

*_keywords_match_sdk and domains_intersection has expend param. It param intcrease result rows (not spend)

expend=false

expend=true

remove_duplicates

All methods has param remove_dublicates. When remove_dublicates=true SDK will delete dublicate rows

Browser Cases

Use intermediate backend

If you use SDK in browser you may want to hide you token. You can use intermediate backend. Download backend.php and config it.

	var api = SerpstatAPI.init({
	    ...
		backend: 'https://site.com/backend.php?method=',
	});

Controls

Have 2 controls Token Input and Regions Input. As in Bootstrap API Console Controls dont not require other libs (as JQuery), but controls supports Bootstrap styles.

    <!-- bootstrap (not required, for styling only) -->
	<link href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">	
	<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
	<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
	<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.bundle.min.js" integrity="sha384-pjaaA8dDz/5BgdFUPX6M/9SUZv4d12SUPF0axWc+VRZkx5xU3daN+lYb49+Ax+Tl" crossorigin="anonymous"></script>
    <!--/bootstrap-->

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/serpstat-api-3@0.4/controls.css">
    <script src="https://cdn.jsdelivr.net/npm/serpstat-api-3@0.4/serpstat-api.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/serpstat-api-3@0.4/controls.js"></script>

    <form style="padding:40px">
        <div class="form-group row" id="row-token">
            <label class="col-sm-2 col-form-label">Token</label>
        </div>
        <div class="form-group row" id="row-se">
            <label class="col-sm-2 col-form-label">SE</label>
        </div>
    </form>

    <script>
        window.SerpstatControls.token({
            'id':'row-token'
        });
        window.SerpstatControls.se({
            'id':'row-se'
        });
    </script>