Skip to main content

Competitor suggestions API

Fetch Insites' default suggested competitors, or inject your own competitors (if known) so Insites shows these instead in the UI.

Andrew Waite avatar
Written by Andrew Waite
Updated this week

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)

Did this answer your question?