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
titleWebsite name
nameWebsite URL
group_idWebsite group ID
is_activeWebsite 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_freqChecking 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_linkGuest link to view site statistics without authorization
keyword_countNumber 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_idSearch engine ID (refer to GET /system/search-engines)
region_nameRegion. 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_snippetTake Featured snippet into account (1 – take into account, 0 – don’t take into account)

Errors


HTTP-code

Error message
400Invalid keyword_id
400Invalid date
400No ids in request
404Unknown search_engine_id
404Unknown 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

RequiredDescription
search_engine_idYesSearch engine ID (refer to GET /system/search-engines)
region_nameNoGeographical 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 NoTake 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 codeError 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

NameDescription
search_engine_idOptional 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.

NameDescription
id Unique query ID
nameKeyword
group_idQuery group ID
linkTarget URL
first_check_date Date of first check query
tagsList of ID tags
site_engine_idsList 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

NameDescription
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
top5Keywords in the TOP 5
top10 Keywords in the TOP 10
top30 Keywords in the TOP 30
visibilityTraffic forecast
visibility_percentVisibility 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.

NameTypeDescription
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.

NameDescription
idUnique query ID
positionArray with elements
dateDate
change Change in position compared to previous date (could be negative)
posCurrent 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_pagesArray 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
volumeSearch volume
competitionCompetition
suggested_bidCost 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 codeError 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.

NameTypeDescription
date_fromyyyy-mm-ddTime period start date (today minus one week by default)
date_toyyyy-mm-ddTime period end date (today by default)
site_engine_idsSearch engine ID filter.
If not specified, data for all search engines will be returned.
keywords_idsKeyword 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.

NameDescription
site_engine_idSearch engine ID
keywordsArray of keywords with data on the number of ads
idKeyword_id
adsData array on the number of ads by dates
dateDate
tabsTotal number of top ads
badsTotal 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

NameRequiredDescription
site_engine_id

NoID 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

RequiredDescription
keywordYesKeyword (query)
group_idNo Keyword group ID (if the parameter is not specified, the default group will be used)
target_URLNoTarget link
is_strict No Check positions only for the selected target links (0 or 1; 0 be default)
site_engine_idsNoArray 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.

NameRequiredDescription
addedYes Number of successfully added queries to the project
idsNo Array of IDs of added queries

Response example

{

    “added”: 3,

    “ids”: [

        123,

        456,

        789

    ]

}

Errors

HTTP codeError 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

NameDescription
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_urlTarget 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-codeError 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

RequiredDescription
urlYesWebsite URL
titleYesProject name
depthNo Ranking position collection depth (100, 200), 100 by default
match_mode Yes Verification type for the found URL: domain, subdomain, exact, path
check_freqNo Position check frequency (‘check_daily’,’check_1in3′,’check_weekly’, ‘check_monthly’, ‘manual’), check_daily set by default
auto_reportsNo Weekly report? (0 or 1), 1 by default
site_group_idNo ID of the group where a new project will be added
check_dayNo 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_activeNo 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.

NameRequiredDescription
site_idYes 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
urlWebsite URL
titleProject name
depth Ranking position collection depth (100, 200), 100 by default
match_modeMatching 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_active1, 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

NameRequiredDescription
keywords_idsYes Array of IDs of keywords to be deleted

If successful, the server returns the 204 HTTP code.

Errors

HTTP codeError 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

NameRequiredTypeDescription
keyword_idYes 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 codeError 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

NameRequiredDescription
site_engine_idNo
Unique project search engine ID. If an API request contains this parameter, the position check will run only for the given search engine.


keywordsYes
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.

NameRequiredDescription
totalYes

The number of keywords for which the position check was launched



Response example

{

    “total”: 5

}

Errors

HTTP codeError message
400 Unknown site_engine_id