Project/Site Management API

Project Management API allows to manage projects (create, edit, delete), get statistics on individual projects or keywords.

List of user sites

The method allows to get a list of all user projects.

Request

GET https://api4.seranking.com/sites

Result

If successful, the server returns HTTP 200 and a list of sites.

Response example

[

    {

        “id”: 1,

        “title”: “zniqpf tfallp mykqeg”,

        “name”: “Cronin.info”,

        “group_id”: 0,

        “is_active”: 1,

        “exact_url”: 0,

        “subdomain_match”: 0,

        “depth”: 100,

        “check_freq”: “check_daily”,

        “check_day”: null,

        “guest_link”: “https://seranking.com/guest.html?site_id=1&hv=0&hash=432&tab=detailed”,

        “keyword_count”: 0,

    }

]

Name	Description
id	Unique site ID
title	Website name
name	Website URL
group_id	Website group ID
is_active	Website status 1 – active, 0 – delayed
exact_url	1 – Ranking positions will be checked only for the specified URL, excluding subfolders and subdomains.
subdomain_match	1 – Take SERP subdomains into account
depth	Ranking position collection depth
check_freq	Checking the search volume
check_day	If weekly checks are represented as check_weekly, this parameter represents the day of the week. (from 1 – Monday to 7 – Sunday) If monthly checks are represented as check_monthly, indicate the day of the week in this parameter (1 – 31)
guest_link	Guest link to view site statistics without authorization
keyword_count	Number of keywords added to the project

List of site search engines

The method allows to get a list of search engines employed by a project.

Request format

GET https://api4.seranking.com/sites/{site_id}/search-engines

Result

If successful, the server returns the 200 HTTP code and a list of a project’s search engines.

Response example

{

        “site_engine_id”: 1,

        “search_engine_id”: 339,

        “region_name”: null,

        “lang_code”: “ru”,

        “merge_map”: 0,

        “business_name”: null,

        “phone”: null,

        “paid_results”: 0,

        “featured_snippet”: 0

        “keyword_count”: 10,

 }

Parameters

Name	Description
search_engine_id	Search engine ID (refer to GET /system/search-engines)
region_name	Region. Only for Google
lang_code	Language code (refer to /system/google-langs)
merge_map	Take Google Maps SERPs into account. 0 – don’t take into account, 1 – take into account, 2 – take into account and display separately.
business_name	Business name for Google Maps SERPs
phone	Company phone number for Google Maps SERPs
paid_results	Track rankings in Google Ads (1 – yes, 0 – no)
featured_snippet	Take Featured snippet into account (1 – take into account, 0 – don’t take into account)

Errors

HTTP-code	Error message
400	Invalid keyword_id
400	Invalid date
400	No ids in request
404	Unknown search_engine_id
404	Unknown site_engine_id

Adding a search engine to projects

The method allows to add new search engines to a project.

Request format

POST https://api4.seranking.com/sites/{site_id}/search-engines

Response example

{

    “search_engine_id”: 339,

    “region_name”: null,

    “lang_code”: “ru”,

    “merge_map”: 0,

    “business_name”: null,

    “phone”: null,

    “paid_results”: 0,

    “featured_snippet”: 0

}

Parameters

Name	Required	Description
search_engine_id	Yes	Search engine ID (refer to GET /system/search-engines)
region_name	No	Geographical name (region / city) in English. Only for Google
lang_code	No	Language code (refer to /system/google-langs)
merge_map	No	Take Google Maps SERPs into account. 0 – don’t take into account, 1 – take into account, 2 – take into account and display separately.
business_name	No	Business name for Google Maps SERPs
phone	No	Company phone number for Google Maps SERPs
paid_results	No	Track rankings in Google Ads (1 – yes, 0 – no)
featured_snippet	No	Take Featured snippet into account (1 – take into account, 0 – don’t take into account)

Result

If successful, the server returns the 201 HTTP code and the site_engine_id of the added search engine.

Errors

HTTP code	Error message
400	Unknown search_engine_id

Changing a search engine in projects

The method allows to add new search engines to a project.

Request format

PUT https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

{

    “region_name”: null,

    “lang_code”: “ru”,

    “merge_map”: 0,

    “business_name”: null,

    “phone”: null,

    “paid_results”: 0,

    “featured_snippet”: 0

}

Parameters

Refer to Adding a search engine to projects.

Result

If successful, the server returns the 200 HTTP code.

Deleting search engines from projects

Request format

DELETE https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

Result

If successful, the server returns the 204 HTTP code.

Website keyword list

The method allows to get a list of keywords with the target pages of a particular project.

Request format

GET https://api4.seranking.com/sites/{site_id}/keywords?site_engine_id=NNN

Request parameters

Name	Description
search_engine_id	Optional parameter. Search engine ID (see GET /system/search-engines) If it is passed, the first_check_date will be returned

Result

If successful, the server returns an array of project keywords with statistics on each one of them.

Name	Description
id	Unique query ID
name	Keyword
group_id	Query group ID
link	Target URL
first_check_date	Date of first check query
tags	List of ID tags
site_engine_ids	List of search engines IDs

Response example

[

    {

        “id”: “1”,

        “name”: “key1”,

        “group_id”: “2”,

        “link”: null,

        “first_check_date”: “2015-02-17”,

        “tags”: [

            “11”,

            “12”

        ]

    },

    {

        “id”: “2”,

        “name”: “key2”,

        “group_id”: “2”,

        “link”: “http://mysite.com/”,

        “first_check_date”: null,

        “tags”: []

    },

    …

]

Summary statistics

The method allows to obtain a project’s summary statistics.

Request format

GET https://api4.seranking.com/sites/{site_id}/stat

Result

Name	Description
site_id	Unique website ID
today_avg	Average position for the last ranking check date (today)
yesterday_avg	Average position for the previous ranking check date (yesterday)
total_up	Total number of positions that went up in SERPs
total_down	Total number of positions that dropped in SERPs
process	Current percentage of processed website positions
top5	Keywords in the TOP 5
top10	Keywords in the TOP 10
top30	Keywords in the TOP 30
visibility	Traffic forecast
visibility_percent	Visibility in %
index_google	Number of pages in Google’s index

Response example

{

    “site_id”: 123,

    “name”: “site1.com”,

    “group_id”: null,

    “title”: “my site”,

    “today_avg”: 123,

    “yesterday_avg”: 111,

    “total_up”: 0,

    “total_down”: 5,

    “process”: “99.9”,

    “top5” : 1,

    “top10” : 2,

    “top30” : 3,

    “visibility” : 2,

    “visibility_percent” : 30.0,

    “da” : 4,

    “index_google” : 200,

    “index_x” : null,

}

Keyword statistics

The method allows to obtain the statistics on a project’s keyword ranking check for a specified time period.

Request format

GET https://api4.seranking.com/sites/{site_id}/positions?date_from=2018-01-01&date_to=2018-01-07&site_engine_id=1&with_landing_pages=1&with_serp_features=1

Query parameters

All parameters are optional.

Name	Type	Description
date_from	yyyy-mm-dd	Time period start date (today minus one week by default
date_to	yyyy-mm-dd	Time period end date (today by default)
site_engine_id		Search engine ID. If not specified, data for all search engines will be returned.
in_top		Filter by ranking position. For example, in_top=10 will return data only on keywords that are in the TOP 10 at the time of the last check for the selected time period.
with_landing_pages		URL information of pages in SERPs
with_serp_features		Google SERP features found in keyword search results.

Result

If successful, the server returns an array of all (or specified) search engines of a project, containing keyword statistics for the specified time period.

Name	Description
id	Unique query ID
position	Array with elements
date	Date
change	Change in position compared to previous date (could be negative)
pos	Current position
price	Price calculated from financial report settings
is_map	Indicates where the position was found; 0 value is set for organic search results, 1 – for the maps block
map_position	Position in the maps block with the “Display organic and maps search results separately” option enabled (merge_map = 2)
paid_position	Position in paid Google SERPs
landing_pages	Array with elements date – date in the yyyy-mm-dd format url – page URL in SERPs by keyword
features	Array with elements. If the value is true, a SERP feature contains a link to a project’s website
volume	Search volume
competition	Competition
suggested_bid	Cost per click
kei	Keyword Efficiency Index
results	Number of results for a given keyword in Google
total_sum	Price per keyword, calculated from financial report settings

Response example

[{

    “site_engine_id”: 1,

        “keywords”: [

        {

            “id”: “12”,

            “positions”: [{

                “date”: “2017-12-19”,

                “pos”: 18,

                “change”: 0,

                “price”: 0,

                “is_map”: 0,

                “map_position”: 0,

                “paid_position”: 0

            }

        ],

        “volume”: 390,

        “competition”: 3,

        “suggested_bid”: 1,

        “kei”: 1,

        “results”: 100,

        “total_sum”: 0,

        “landing_pages”: [

        {

            “url”: “https://domain.com/page.html”,

            “date”: “2017-12-14”

            }

        ],

        “features”: {

            “tads”: true,

            “knowledge_graph”: true,

            “images”: true,

            “sitelinks”: true,

            “reviews”: false

    },

},

…

]

Errors

HTTP code	Error message
400	Invalid site_engine_id

Total number of ads chart

The method allows to get data on the total number of top and bottom advertisements by day.

Request format

 GET https://api4.seranking.com/sites/{site_id}/ads?date_from=2020-05-20&date_to=2020-05-21&site_engine_ids[]=1&site_engine_ids[]=2&keywords_ids[]=1&keywords_ids[]=1

Parameters

Query parameters. All parameters are optional.

Name	Type	Description
date_from	yyyy-mm-dd	Time period start date (today minus one week by default)
date_to	yyyy-mm-dd	Time period end date (today by default)
site_engine_ids		Search engine ID filter. If not specified, data for all search engines will be returned.
keywords_ids		Keyword ID filter. If not specified, data for all keywords will be returned.

Result

If successful, the server returns an array of data from all (or specified) search engines of the project. This array contains data on the number of top and bottom advertisements in the search results for all (or selected) keywords by dates in the specified period.

Returns a maximum of 100,000 results. If the project has a large number of keywords, it is advisable to indicate the ID of search engines, keywords and the verification period.

Name	Description
site_engine_id	Search engine ID
keywords	Array of keywords with data on the number of ads
id	Keyword_id
ads	Data array on the number of ads by dates
date	Date
tabs	Total number of top ads
bads	Total number of bottom ads

Response example



[{

  “site_engine_id”: 1,

  “keywords”: [

    {

      “id”: 1,

      “ads”: [

        {

          “date”: “2020-05-20”,

          “tads”: 2,

          “bads”: 3

        },

        {

          “date”: “2020-05-21”,

          “tads”: 3,

          “bads”: 2

        },

      ]

    },

    {

      “id”: 2,

      “ads”: [

        {

          “date”: “2020-05-20”,

          “tads”: 0,

          “bads”: 0

        },

        {

          “date”: “2020-05-21”,

          “tads”: 0,

          “bads”: 1

        },

      ]

    },

  ]

},

{

  “site_engine_id”: 2,

  “keywords”: [

    {

      “id”: 1,

      “ads”: [

        {

          “date”: “2020-05-20”,

          “tads”: 1,

          “bads”: 1

        },

        {

          “date”: “2020-05-21”,

          “tads”: 2,

          “bads”: 2

        },

      ]

    },

    {

      “id”: 2,

      “ads”: [

        {

          “date”: “2020-05-20”,

          “tads”: 0,

          “bads”: 2

        },

        {

          “date”: “2020-05-21”,

          “tads”: 5,

          “bads”: 1

        },

      ]

    },

  ]

}]

Historical dates

The method returns a list of dates necessary to build a graph of historical ranking positions. The dates correspond to the following list: today, yesterday, 7 days ago, 1 month ago, 3 months ago, 6 months ago, the first day of the check. If no ranking position check took place on a given date, the closest ranking position check date will be returned.

Request format

GET https://api4.seranking.com/sites/{site_id}/historicalDates

Request parameters

Name	Required	Description
site_engine_id	No	ID of the search engine in the project. If site_engine_id is not specified, searches dates for all search engines.

Result

If successful, the server returns an array of available dates. The array can include the following elements: ‘current’, ‘day_ago’, ‘7days’, ’30days’, ’90days’, ‘180days’, ‘first’. Values displayed in the list will be transmitted as dates expressed in the YYYY-MM-DD format.

Response example

{

    “current” : “2019-02-20”,

    “day_ago” : “2019-02-19”,

    “7days” : “2019-02-14”,

}

Adding queries to projects

The method allows to add new keywords to projects.

Request form

POST https://api4.seranking.com/sites/{site_id}/keywords

[{

    “keyword”:”text”,

    “group_id”:1,

    “target_url”: “http://site.com/”,

    “is_strict”: 0,

    “site_engine_ids”: [20,21]

}]

Request parameters

Name	Required	Description
keyword	Yes	Keyword (query)
group_id	No	Keyword group ID (if the parameter is not specified, the default group will be used)
target_URL	No	Target link
is_strict	No	Check positions only for the selected target links (0 or 1; 0 be default)
site_engine_ids	No	Array of search engine IDs. The keyword will only be in these search engines.

Result

If successful, the server returns an array of added keywords and their project ID.

Name	Required	Description
added	Yes	Number of successfully added queries to the project
ids	No	Array of IDs of added queries

Response example

{

    “added”: 3,

    “ids”: [

        123,

        456,

        789

    ]

}

Errors

HTTP code	Error message
400	No keywords specified

Changing a keyword in a project

The method allows to change the settings of a keyword in a project.

Request format

PATCH https://api4.seranking.com/sites/{site_id}/keywords/{keyword_id}

{

    “keyword”:”text”,

    “target_url”: “http://site.com/”

}

Request parameters

Name	Description
keyword	Keyword (search query)
group_id	Keyword group ID used when transferring a keyword to another project’s keyword group (use the value from the list of project keyword group IDs)
target_url	Target link
is_strict	Check rankings only for the specified target links (0 or 1 with 0 being the default option)

Result

If successful, the server returns the 200 HTTP code.

Errors

HTTP-code	Error message
400	Invalid or empty keyword data
403	Access denied (wrong site_id)
404	Unknown keyword (wrong keyword_id)

Adding a project

The method allows to add a new project to a user account.

Request format

POST https://api4.seranking.com/sites

{

    “url”:”http://test.site/”,

    “title”:”seo site”

}

Request parameters

Name	Required	Description
url	Yes	Website URL
title	Yes	Project name
depth	No	Ranking position collection depth (100, 200), 100 by default
match_mode	Yes	Verification type for the found URL: domain, subdomain, exact, path
check_freq	No	Position check frequency (‘check_daily’,’check_1in3′,’check_weekly’, ‘check_monthly’, ‘manual’), check_daily set by default
auto_reports	No	Weekly report? (0 or 1), 1 by default
site_group_id	No	ID of the group where a new project will be added
check_day	No	If weekly checks are represented as check_weekly, this parameter represents the day of the week. (from 1 – Monday to 7 – Sunday). If monthly checks are represented as check_monthly, indicate the day of the week in this parameter (1 – 31)
is_active	No	Project status 1 – active, 0 – delayed

Result

If successful, the server returns the 201 HTTP code and the ID of the project that was added to the account.

Name	Required	Description
site_id	Yes	ID of the project added to the account

Response example

{

    “site_id”: 507052

}

Changing project settings

The method allows to change/update the project settings.

Request format

PUT https://api4.seranking.com/sites/{site_id}

{

    “title”:”new site title”

}

Request parameters

Name	Description
url	Website URL
title	Project name
depth	Ranking position collection depth (100, 200), 100 by default
match_mode	Matching type for the found URL in the search results:: domain, subdomain, exact, path
check_freq	Position check frequency (‘check_daily’,’check_1in3′,’check_weekly’, ‘check_monthly’, ‘manual’), check_daily set by default
site_group_id	ID of the group where a new project will be added
check_day	If weekly checks are represented as check_weekly, this parameter represents the day of the week. (from 1 – Monday to 7 – Sunday). If monthly checks are represented as check_monthly, indicate the day of the week in this parameter (1 – 31)
is_active	1, 0

Result

If successful, the server returns the 200 HTTP code.

Deleting a project

The method allows to delete a project from a user account.

Request format

DELETE https://api4.seranking.com/sites/{site_id}

Result

If successful, the server returns the 204 HTTP code.

Deleting keywords

The method allows to delete keywords from a project.

Request format

DELETE https://api4.seranking.com/sites/{site_id}/keywords?keywords_ids[]=1&keywords_ids[]=2&keywords_ids[]=3

Request parameters

Name	Required	Description
keywords_ids	Yes	Array of IDs of keywords to be deleted

If successful, the server returns the 204 HTTP code.

Errors

HTTP code	Error message
400	No ids in request

Manual position setting

The method allows to set positions for a project’s keywords.

Request format

https://api4.seranking.com/sites/{site_id}/position/

{

    “keyword_id”: 1,

    “date”: “2018-01-01”,

    “position”:100,

    “site_engine_id”: 1

}

Request parameters

Name	Required	Type	Description
keyword_id	Yes		Unique keyword ID (refer to GET https://api4.seranking.com/sites/{site_id}/keywords)
date	Yes	yyyy-mm-dd	The date the positions need to be set for
site_engine_id	Yes		Unique project search engine ID (refer to GET https://api4.seranking.com/sites/{site_id}/search-engines)
position	Yes		Position from 0 to 200. 0 is considered as “not found”

Result

If successful, the server returns the 200 HTTP code.

Errors

HTTP code	Error message
400	Invalid date
400	Invalid keyword_id
400	Unknown site_engine_id

Running a position check

The method allows to run a ranking position check for specified keywords or for the entire project.

Request format

POST https://api4.seranking.com/sites/{site_id}/recheck/

{

    “keywords”:[

        {

            “site_engine_id”:1,

            “keyword_id”:2

        }

    ]

}

Parameters

Name	Required	Description
site_engine_id	No	Unique project search engine ID. If an API request contains this parameter, the position check will run only for the given search engine.
keywords	Yes	An array of separate keywords that need a position check. Several definitions are indicated for every keyword: site_engine_id (unique project search engine ID) and keyword_id (unique keyword ID). If an API request contains this parameter, the site_engine_id parameter is ignored.

Result

If successful, the server returns an array of keywords for which the position check was launched.

Name	Required	Description
total	Yes	The number of keywords for which the position check was launched

Response example

{

    “total”: 5

}

Errors

HTTP code	Error message
400	Unknown site_engine_id