Competitors
Competitors API provides endpoints to manage competitors and retrieve competitor ranking data within a project.
Add competitor
POST https://api4.seranking.com/competitors
Adds a competitor’s website to a project for position tracking.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| site_id | Integer | Yes | Unique project (site) ID. |
| url | String | Yes | Competitor website URL. |
| name | String | No | Competitor website name. If not specified, the URL is used. |
| subdomain_match | Integer | No | Include subdomains (1 – yes, 0 – no). |
Request example
POST https://api4.seranking.com/competitors
{
site_id : 1,
name : "name",
url : "http://site.test.com/"
}Response parameters
If successful, the server returns the 201 HTTP status code. Returns HTTP 400 if the URL is invalid.
| Parameter | Type | Description |
|---|---|---|
| id | Integer | Competitor ID. |
Response example
{ "id": 123456 }List competitors
GET https://api4.seranking.com/competitors/site/{site_id}
Returns a list of competitors added to the specified project.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| site_id | Integer | Yes | Unique project (site) ID (path parameter). |
Request example
GET https://api4.seranking.com/competitors/site/1Response parameters
If successful, the server returns the 200 HTTP status code and an array of competitors.
| Parameter | Type | Description |
|---|---|---|
| id | Integer | Competitor ID. |
| name | String | Competitor name. |
| url | String | Competitor URL. |
| domain_trust | Integer | Competitor Domain Trust. |
Response example
[
{
"id": 1,
"name": "competitor1.com",
"url": "competitor1.com",
"domain_trust" : 2
},
{
"id": 2,
"name": "competitor2.com",
"url": "http://competitor2.com/",
"domain_trust" : 4
},
{
"id": 3,
"name": "competitor3.com",
"url": "http://competitor3.com",
"domain_trust" : 6
}
]Get competitor keyword positions
GET https://api4.seranking.com/competitors/{competitor_id}/positions
Returns ranking statistics for competitor keywords added to the project.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| competitor_id | Integer | Yes | Competitor ID (path parameter). |
| date_from | String | No | Start date (in YYYY-MM-DD). Defaults to one week before today. |
| date_to | String | No | End date (in YYYY-MM-DD). Defaults to today. |
| site_engine_id | Integer | No | Search engine configuration ID. If not specified, all search engines are included. |
| with_serp_features | Integer | No | Include SERP features (1 – yes, 0 – no). |
Request example
GET https://api4.seranking.com/competitors/123/positions?date_from=2018-07-25&date_to=2018-07-25&site_engine_id=1Response parameters
If successful, the server returns the 200 HTTP status code and ranking data grouped by search engine. Returns HTTP 400 if the site_engine_id is invalid and HTTP 404 if the competitor is not found (for more information, see Error handling).
| Parameter | Type | Description |
|---|---|---|
| site_engine_id | Integer | Search engine configuration ID. |
| keywords | Array | List of keywords. |
| id | String | Keyword ID. |
| positions | Array | Array of positions containing statistics on competitor keyword rankings. |
| date | String | Check date (in YYYY-MM-DD). |
| pos | Integer | Current position. |
| change | Integer | Position change compared to previous check. |
| name | String | Keyword name (can be null). |
| volume | Integer | Search volume (can be null). |
Response example
[
{
"site_engine_id": 123,
"keywords": [
{
"id": "123",
"positions": [
{
"date": "2018-07-25",
"pos": 7,
"change": 1
}
],
"name": null,
"volume": null
},
...
]
}
]Delete competitor
DELETE https://api4.seranking.com/competitors/{competitor_id}
Removes a competitor from the specified project.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| competitor_id | Integer | Yes | Competitor ID (path parameter). |
Request example
DELETE https://api4.seranking.com/competitors/123Response parameters
If successful, the server returns the 204 HTTP status code. Returns HTTP 404 if the competitor is not found (for more information, see Error handling).
Response example
No response body.
Get TOP 10 results
GET https://api4.seranking.com/competitors/top10/{site_id}
Returns the TOP 10 ranking results for a tracked keyword.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| site_id | Integer | Yes | Project (site) ID (path parameter). |
| date | String | Yes | Date of getting a list of sites from the TOP 10 (in YYYY-MM-DD). |
| site_engine_id | Integer | Yes | Search engine configuration ID (refer to https://api4.seranking.com/sites/{site_id}/keywords). |
| keyword_id | Integer | Yes | Unique keyword ID (refer to https://api4.seranking.com/sites/{site_id}/keywords). |
Request example
GET https://api4.seranking.com/competitors/top10/1?date=2018-01-01&site_engine_id=1&keyword_id=1Response parameters
If successful, the server returns the 200 HTTP status code and an array of results.
| Parameter | Type | Description |
|---|---|---|
| url | String | Page URL. |
| position | Integer | Position in SERP. |
| keyword_id | Integer | Keyword ID. |
| backlinks | String | Total backlinks. |
| domains | String | Referring domains count. |
Response example
[
{
"position": 1,
"url": "https://anandaioga.com/ca/inici",
"keyword_id": 4843813,
"backlinks": "216",
"domains": "57"
},
...
]Get TOP 100 results
GET https://api4.seranking.com/competitors/top100/{site_id}
Returns a list of up to the TOP 100 results for keywords tracked in a project.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| site_id | Integer | Yes | Project (site) ID (path parameter). |
| date | String | Yes | Date of getting a list of the TOP 100 results (in YYYY-MM-DD). |
| site_engine_id | Integer | Yes | Search engine configuration ID (refer to https://api4.seranking.com/sites/{site_id}/keywords). |
| keyword_id | Integer | Yes | Unique keyword ID (refer to https://api4.seranking.com/sites/{site_id}/keywords). |
| top | Integer | No | Maximum position (0–100). |
Request example
GET https://api4.seranking.com/competitors/top100/1?date=2018-01-01&site_engine_id=1&keyword_id=1&top=50Response parameters
If successful, the server returns the 200 HTTP status code and ranking results.
| Parameter | Type | Description |
|---|---|---|
| url | String | Page URL. |
| position | Integer | Position in SERP. |
| date | String | Check date (in YYYY-MM-DD). |
| domain_trust | Integer | Domain Trust value. |
Response example
[
{
"url": "https://www.tests.com/login",
"position": 1,
"date": "2018-01-01",
"domain_trust": 2
},
{
"url": "https://www.test2.com",
"position": 2,
"domain_trust": 4
},
...
]Get all competitors
GET https://api4.seranking.com/competitors/all/{site_id}
Returns domains ranked in the TOP 10 for tracked keywords. History is stored for 14 days.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| site_id | Integer | Yes | Project (site) ID (path parameter). |
| date | String | Yes | Date of getting domains ranked in the TOP 10 (in YYYY-MM-DD). |
| site_engine_id | Integer | Yes | Search engine configuration ID. |
| group_id | Integer | No | Keyword group ID. |
| tags | Array | No | Keyword tag IDs. |
Request example
GET https://api4.seranking.com/competitors/all/1?date=2018-01-01&site_engine_id=1&group_id=1&tags[]=21Response parameters
If successful, the server returns the 200 HTTP status code and an array of domains.
| Parameter | Type | Description |
|---|---|---|
| domain_id | Integer | Domain ID. |
| domain | String | Domain name. |
| visibility | Integer | Visibility value. |
| backlinks | String | Total backlinks. |
| domains | String | Referring domains count. |
Response example
[
{
"domain": "www.tests.com",
"domain_id": 10,
"visibility": 0,
"backlinks": "328",
"domains": "32"
},
...
]