While Insites will try and suggest the best competitors it can in all scenarios, the relevance of the suggestions will vary according to the information Insites knows about a business, and the audits you have enabled in your Audit Designer.
While it is not strictly necessary to take all these actions, for optimum suggestions it is recommended to:
Ensure the industry is set for all businesses audited in your Insites account
Enable the Organic Search audit
Enable Local Ranking Grid audit
Fetch competitor suggestions
Method: GET
The following parameters can be passed via GET to override default detected values:
Property | Definition | Required |
keyword | String - a keyword to use when searching for competitor businesses | No (defaults to a keyword suggested by Insites based on the industry sector & location) |
country | String – 2 letter ISO country code (e.g. FR, GB, US) | No (defaults to detected country for the audit) |
language | String - 2 letter language code (e.g. en, fr) | No (defaults to en) |
excludeDomains | String array – a list of domains to ignore in the results | No (defaults to the website for the primary audit, so that business is not suggested as its own competitor) |
Example
curl "https://api.insites.com/api/v1/report/[REPORT ID]/competitor-suggestions" --header "api-key:[YOUR API KEY]"
All possible responses
Code | Reason |
200 | Competitor suggestions available. |
400 | Malformed request – e.g. audit ID is not provided. |
404 | Audit does not exist. |
Add competitor suggestions to an Insites audit
Method: POST
Request body should be JSON encoded, and can include the following fields:
Property | Definition | Required |
competitor_suggestions | Array – An array of competitor suggestion objects (see below) | Yes |
Competitor suggestion
Each competitor suggestion object should follow the following structure:
Property | Definition | Required |
name | String – Name of the competitor | Yes |
phone | String – Phone number of the competitor | No |
address | String – Address of the competitor | No |
city | String – City of the competitor | No |
state | String – State or county of the competitor | No |
country_code | String – ISO 2 letter country code of the competitor | No |
zip | String – Zip code of the competitor | No |
url | String – URL / web address of the competitor | No |
latitude | Float – Latitude GPS coordinate of the competitor | No |
longitude | Float – Longitude GPS coordinate of the competitor | No |
Example
curl "https://api.insites.com/api/v1/report/[REPORT ID]/competitor-suggestions" \
--header "api-key:[YOUR API KEY]" \
--header "Content-Type: application/json" \
--data '{
"competitor_suggestions": [
{
"name": "Cheval Blanc by Peter Knogl",
"phone": "+41 61 260 50 07",
"address": "Blumenrain 8",
"city": "Basel",
"state": "Basel",
"country_code": "CH",
"zip": "4001",
"url": "https://www.lestroisrois.com/en/cheval-blanc-by-peter-knogl",
"latitude": 47.5596,
"longitude": 7.5886
}
]
}'
Expected response
If successful, you would expect a 201 response.
All possible responses
Code | Reason |
201 | Competitor suggestions stored |
422 | Malformed competitor or competitor(s) |