Competitors

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 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.

Name Required Description
id Yes ID of the query added to the project
positions 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
site_engine_id Yes Search engine ID
keyword_id No 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.

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
alexa Alexa
da Moz Domain Authority
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,
        "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.

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
site_engine_id Yes Search engine ID
keyword_id Yes The ID of the keyword added to the project (use GET /sites/{site_id}/keywords to get it).
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.
site_engine_id No Search engine ID. If not specified, data for all search engines will be returned.
group_id No Keyword group ID. If not specified, data for all keyword groups 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
alexa Alexa
da Moz Domain Authority
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,
        "alexa": "46890",
        "da": null,
        "backlinks": "328",
        "domains": "32",
        "yandex_x": null
    },

...
] 
By continuing to use this site you consent to the use of cookies in accordance with our Cookie policy. close notification