Table of content
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=1Request 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=1Request 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=1Request 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[]=21Request 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
},
…
]