Competitors API

Adding a competitor to a project

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

Parameters

Name	Required	Description
site_id	Yes	Unique project ID
url	Yes	Competitor’s website URL
name	No	Competitor’s website name (if not specified, the URL will be used)
subdomain_match	No	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.

Name	Required	Description
id	Yes	Unique identifier of a competitor

Response example

{

    “id”: 123456

}

Errors

HTTP code	Error 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.

Name	Required	Description
id	Yes	Competitor ID
name	Yes	Competitor name
url	Yes	Competitor 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

Name	Required	Type	Description
date_from	No	yyyy-mm-dd	Time period start date (today minus one week by default)
date_to	No	yyyy-mm-dd	Time period end date (today by default)
site_engine_id	No		Search engine ID. If not specified, data for all search engines will be returned.
with_serp_features	No		Google SERP features found in keyword search results

Result

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

Name	Required	Description
id	Yes	ID of the query added to the project
position	Yes	Array of positions containing statistics on competitor keyword rankings
date	Yes	Date of the keyword rankings check
change	Yes	Change in position compared to previous date (could be negative)
pos	Yes	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 code	Error message
400	Invalid site_engine_id
404	Incorrect 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 code	Error message
404	Incorrect 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

Name	Required	Type	Description
date	Yes	yyyy-mm-dd	Date of getting a list of sites from the TOP 10
keyword_id	Yes		The ID of the query added to the project (use GET /sites/{site_id}/keywords to get it).
site_engine_id	Yes		Search engine ID

Result

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

Name	Description
url	Page URL
position	Position in the SERP
keyword_id	Unique keyword ID
backlinks	Total backlinks
domains	Number 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,

        “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

Name	Required	Type	Description
date	Yes	yyyy-mm-dd	Date
keyword_id	Yes		The ID of the keyword added to the project (use GET /sites/{site_id}/keywords to get it).
site_engine_id	Yes		Search engine ID
top	No	0…100	Maximum position

Result

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

Name	Description
url	Page URL
position	Position in the SERP
date	Date 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

Name	Required	Type	Description
date	Yes	yyyy-mm-dd	Date when the list of sites from the TOP 10 was received.
group_id	No		Keyword group ID. If not specified, data for all keyword groups will be returned.
site_engine_id	No		Search engine ID. If not specified, data for all search engines will be returned.
tags	No		Array of tags

Result

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

Name	Description
domain_id	Domain ID
domain	Competitor’s domain
visibility	Competitor’s visibility
backlinks	Total backlinks
domains	Number 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,

        “da”: null,

        “backlinks”: “328”,

        “domains”: “32”,

        “yandex_x”: null

    },

…

]