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 |
| domain_trust | Yes | 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, } ] |
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 |
| 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 |
Response example
| [ { “url”: “https://www.tests.com/login”, “position”: 1, “keyword_id”: 1,”alexa”: “46890”,”da”: null,”backlinks”: “328”,”domains”: “32” }, …] |
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&top={10} |
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 |
| domain_trust | Competitor Domain Trust |
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 }, …] |
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 |
Response example
| [ { “domain”: “www.tests.com”, “domain_id”: 10, “visibility”: 0,”alexa”: “46890”,”da”: null,”backlinks”: “328”,”domains”: “32” }, …] |