Project/Site Management

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"
    }
]
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

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_id": 0,
        "region_name": null,
        "lang_code": "ru",
        "merge_map": 0,
        "business_name": null,
        "phone": null,
        "paid_results": 0,
        "featured_snippet": 0
    }
]

Parameters

Name Description
search_engine_id Search engine ID (refer to GET /system/search-engines)
region_id Region ID. Only for Yandex (refer to GET /system/yandex-regions)
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-код 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_id": 0,
    "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_id No Region ID. Only for Yandex (refer to GET /system/yandex-regions)
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
404 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_id": 0,
    "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 – OK.

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

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

Response example

[
    {
        "id": "1",
        "name": "key1",
        "group_id": "2",
        "link": null,
        "first_check_date": "2015-02-17"
    },
    {
        "id": "2",
        "name": "key2",
        "group_id": "2",
        "link": "http://mysite.com/",
        "first_check_date": "2016-02-04"
    },
    ...
]

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 %
da Moz Domain Authority
index_yandex Number of pages in Yandex’s index
yandex_x Yandex X
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_yandex" : 100,
    "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
positions 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,
        "resultsi": 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

Adding queries to projects

The method allows to add new keywords to projects.

Request format

POST https://api4.seranking.com/sites/{site_id}/keywords
[{
    "keyword":"text",
    "group_id":1,
    "target_url": "http://site.com/",
    "is_strict": 0,
    "comment":"text"
}]

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)
comment No Comments

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

HHTTP code Error message
400 No keywords specified

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
subdomain_match No Take subdomains in SERPs into account? (0 or 1), 0 by default
exact_url No Exact URL? (0 or 1), 0 by default
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
subdomain_match Take subdomains in SERPs into account (0 or 1), 0 by default
exact_url Exact URL? (0 or 1), 0 by default
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

PUT 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”

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
By continuing to use this site you consent to the use of cookies in accordance with our Cookie policy. close notification