Project Management
Project Management API allows to manage projects (create, edit, delete), get statistics on individual projects or keywords.
List projects
The method allows to get a list of all user projects.
Request
| GET https://api4.seranking.com/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 |
| keyword_count | Number of keywords added to the project |
List project 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,
“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
{
“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_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_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.
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 seacrh engines IDs |
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”: 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 % |
| da | Moz Domain Authority |
| 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 |
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_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 elementsdate – date in the yyyy-mm-dd formaturl – 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 |
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 |
| tads | 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 format
| POST https://api4.seranking.com/api/sites/{site_id}/keywords [{“keyword”:”text”,”group_id”:1,”target_url”: “http://site.com/“,”is_strict”: 0,”comment”:”text”,”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) |
| comment | No | Comments |
| 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 |
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 |
Result
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” |
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/api/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 |