Competitors

Adding a competitor to a project

The method allows to add a competitor’s site to a project to track positions.

Parameters

NameRequiredDescription
site_idYes Unique project ID
urlYes Competitor’s website URL
nameNo Competitor’s website name (if not specified, the URL will be used)
subdomain_matchNo Take subdomains into account (1 – yes , 0 – no)

Request format

POST /competitors
{
site_id : 1,
name : “name”,
url : “http://site.test.com/”
}

Result

If successful, the server returns the 201 HTTP code and the ID of the added competitor.

NameRequiredDescription
idYes Unique identifier of a competitor

Response example

{
“id”: 123456
}

Errors

HTTP codeError message
400 Invalid site url

Getting a list of the project competitors

The method allows to get a list of all competitors added to the project.

Request format

GET /competitors/site/{site_id}

Result

If successful, the server returns an array with a list of competitors added to the project together with the statistics on the competitors’ sites.

NameRequiredDescription
idYesCompetitor ID
nameYesCompetitor name
urlYesCompetitor URL

Response example

[
{
“id”: 1,
“name”: “competitor1.com”,
“url”: “competitor1.com”,
},
{
“id”: 2,
“name”: “competitor2.com”,
“url”: “http://competitor2.com/”,
},
{
“id”: 3,
“name”: “competitor3.com”,
“url”: “http://competitor3.com”,
}
]

Competitor’s keyword positions

The method allows to get statistics on the positions of competitor keywords that were added to the project.

Request format

GET /competitors/{competitor_id}/positions?date_from=2018-07-25&date_to=2018-07-25&site_engine_id=1

Request query parameters

NameRequiredTypeDescription
date_fromNo yyyy-mm-dd Time period start date (today minus one week by default)
date_toNo yyyy-mm-dd Time period end date (today by default)
site_engine_idNo yyyy-mm-dd Search engine ID. If not specified, data for all search engines will be returned.

Result

If successful, the server returns the statistics on the positions of competitor keywords that were added to the project.

NameRequiredDescription
idYes ID of the query added to the project
positionYes Date of the keyword rankings check Array of positions containing statistics on competitor keyword rankings
dateYes Date of the keyword rankings check
changeYes Change in position compared to previous date (could be negative)
posYes Current position

Response example

[
{
“site_engine_id”: 123,
“keywords”: [
{
“id”: “123”,
“positions”: [
{
“date”: “2018-07-25”,
“pos”: 7,
“change”: 1
}
],
“name”: null,
“volume”: null
},

]

Errors

HTTP codeError message
400 Invalid site_engine_id
404Incorrect competitor id

Deleting a competitor from a project

The method allows to remove a competitor’s site from a user project.

Request format

DELETE /competitors/{competitor_id}

Result

If successful, the server returns the 204 HTTP code.

Errors

HTTP codeError message
404Incorrect competitor id

Getting TOP 10 for the keyword

The method allows to get a list of the TOP 10 results for the keywords that are tracked in a project.

Request format

GET /competitors/top10/{site_id}/?date=2018-01-01&site_engine_id=1&keyword_id=1

Request query parameters

NameRequiredTypeDescription
dateYes yyyy-mm-dd Date of getting a list of sites from the TOP 10
keyword_idNo The ID of the query added to the project (use GET /sites/{site_id}/keywords to get it). If not specified, the TOP 10 will be returned for all project keywords.
site_engine_idYes Search engine ID

Result

If successful, the server returns an array of sites from the TOP 10.

NameDescription
urlPage URL
positionPosition in the SERP
keyword_idUnique keyword ID
alexaAlexa
daMoz Domain Authority
backlinksTotal backlinks
domainsNumber of referring unique domains
yandex_x Site quality index by Yandex that shows how useful a competitor’s site is for visitors.

Response example

[
{
“url”: “https://www.tests.com/login”,
“position”: 1,
“keyword_id”: 1,
“alexa”: “46890”,
“da”: null,
“backlinks”: “328”,
“domains”: “32”,
“yandex_x”: null
},

]

Getting TOP 100 for the keyword

The method allows to get a list of the TOP 100 results for the keywords that are tracked in a project.

Request format

GET /competitors/top100/{site_id}/?date=2018-01-01&site_engine_id=1&keyword_id=1

Request query parameters

NameRequiredTypeDescription
dateYes yyyy-mm-dd Date of getting a list of sites from the TOP 10
keyword_idYes The ID of the query added to the project (use GET /sites/{site_id}/keywords to get it). If not specified, the TOP 10 will be returned for all project keywords.
site_engine_idYes Search engine ID
topNo0…100Maximum position

Result

If successful, the server returns an array of sites from the TOP 100.

NameDescription
urlPage URL
positionPosition in the SERP
dateDate of the positions check

Response example

[
{
“url”: “https://www.tests.com/login”,
“position”: 1,
“date”: “2018-01-01”
},
{
“url”: “https://www.test2.com,
“position”: 2,
“date”: “2018-01-01”
},

]

All competitors

Here you can find data on the sites that were ranked in the TOP 10 for each of the tracked queries. The history is stored for 14 days.

Request format

GET /competitors/all/{site_id}/?date=2018-01-01&site_engine_id=1&group_id=1&tags[]=21

Request query parameters

NameRequiredTypeDescription
dateYes yyyy-mm-dd Date when the list of sites from the TOP 10 was received.
group_idYes
Keyword group ID. If not specified, data for all keyword groups will be returned.
site_engine_idNo
Search engine ID. If not specified, data for all search engines will be returned.

tagsNoArray of tags

Result

If successful, the server returns an array of sites from the TOP 10.


NameDescription
domain_idDomain ID
domainCompetitor’s domain
keyword_idCompetitor’s visibilityrespon
alexaAlexa
daMoz Domain Authority
backlinksTotal backlinks
domainsNumber of referring unique domains
yandex_x Site quality index by Yandex that shows how useful a competitor’s site is for visitors.

Response example

[
{
“domain”: “www.tests.com”,
“domain_id”: 10,
visibility”: 0,
“alexa”: “46890”,
“da”: null,
“backlinks”: “328”,
“domains”: “32”,
“yandex_x”: null
},

]