Report API

How to run & fetch an Insites SEO audit using our API

Andrew Waite avatar
Written by Andrew Waite
Updated over a week ago

This page explains how to use our API to request, fetch and check the status of website reports in Insites.

The common use-case for our API is to generate a website report and consume the resulting data. There are two technical approaches you may use to achieve this:

  • Request a report via our API and receive a callback on completion

  • Request a report via our API and then poll for the analysis results

All requests to our API should be authenticated. Our API is RESTful and communicates using JSON.


Fetch an existing audit

Method: GET
Endpoint: https://api.insites.com/api/v1/report/[REPORT ID]

The following parameters can be passed via GET to bring back more detailed results:

Property

Definition

Required

include_datasets

Boolean – if true, this includes additional datasets in the results (e.g. a table of broken links discovered).

No (defaults to false)

available_versions

Boolean – if true, this includes the available version IDs (if the report has been run multiple times).

No (defaults to false)

version_id

String – if provided, the API will provide the results for this specific report version.

No (defaults to latest version)

staging

Boolean – if true, this will return the staging report associated with this business.

No (defaults to false)

categories

Boolean – if true, this will return the categories as defined in the account’s Overview layout.

No (defaults to false)

percentiles

Boolean – if true, this will return the percentiles for this business.

No (defaults to false)

Example

curl "<https://api.insites.com/api/v1/report/>[REPORT ID]" --header "api-key:[YOUR API KEY]"


Expected response

If successful, you would expect a 200 response, with a body like this:

{
"report_status": "complete",
"status":"success",
"report": [REPORT DATA]
}

Note: For an example of the report data, please see “Example report data” below.

All possible responses

Code

Reason

200

Report is complete.

202

Report is still running (note: this response will also return data for an old report on this business, if one is available).

400

Malformed request – e.g. report ID is not provided.

404

Report does not exist.


Start a new audit

Please note, the ability to use custom report fields is only available to Enterprise level customers.


Request body should be JSON encoded, and can include the following fields:

Property

Definition

Required

url

String – URL to analyze

No

check_for_existing

ISO8601 – The analysis will not run if the website has already been tested after the supplied date.

No

on_completion

String – Insites will make a POST callback to this URL with the JSON report data.

No

allow_path

Boolean – if true, Prospect will run an audit on a subsection of a site, e.g. https://mywebsite.com/part-of-my-site. Note that this feature is currently experimental.

No (defaults to false)

priority

String – valid options are “normal” or “batch”. If your request is time sensitive, use the option “normal”. If you want to run multiple reports in a batch which isn’t time sensitive, use the option “batch”.

No (defaults to normal)

dedupe_method

String – valid options are “none” or “match_hostname”. By default Insites tries to match your request to an existing report, if you’ve tested the same hostname before. If you’d like to force Insites to create a completely fresh report regardless of existing data, pass this option with the value set to “none”.

No (defaults to match_hostname)

name

String – Business name, some checks will not work without this, e.g Local presence, Reviews

No

phone

String – Business phone number, some checks will not work without this, e.g Local presence, Reviews

No

address

String – First line of business address, some checks will not work without this, e.g Local presence, Reviews

No

number

String – Building number, enhances accuracy in some checks, e.g Local presence, Reviews

No

street

String – Street, enhances accuracy in some checks, e.g Local presence, Reviews

No

city

String – City, enhances accuracy in some checks, e.g Local presence, Reviews

No

state

String – State or county, enhances accuracy in some checks, e.g Local presence, Reviews

No

zip

String – Zip of postcode, enhances accuracy in some checks, e.g Local presence, Reviews

No

country_code

ISO 2 letter code – Country, enhances accuracy in some checks, e.g Local presence, Reviews

No

lat

String – Latitude, enhances accuracy in some checks, e.g Local presence, Reviews

No

lng

String – Longitude, enhances accuracy in some checks, e.g Local presence, Reviews

No

products

String – Products and services this business offers, some checks will not work without this, e.g Content keywords. Note: multiple products and services should be comma separated

No

locations

String – Locations served, some checks will not work without this, e.g Content keywords. Note: multiple locations should be comma separated

No

is_competitor_of

String – the Report ID of a another report that already exists. If set, this report will be added as a competitor of the existing business.

No

pages_to_analyse

Integer – if valid, this is the number of pages that will be included in the report

No

_[custom_field_name]

String – Pass values to set as one of your custom report fields. Note: custom report fields must be prefixed with an underscore.

No

Example

curl "https://api.insites.com/api/v1/report" --header "api-key:[YOUR API KEY]" --data "{\"url\\":\"mywebsite.com\"}"


Expected response

If successful, you would expect a 202 response, with a body like this:

{
"status": "running",
"reportId": "3076c8dc5f1c433589245797d938debacb25ed91"
}


All possible responses

Code

Reason

202

Report has been requested and is now running.

303

Recent results already exist for this business, so it will not be retested (see check_for_existing parameter).

400

Your request was un-processable, usually because you’ve requested analysis on a website with a path, which we can’t currently accept.

422

Your request was un-processable, usually because the website doesn’t exist or redirects. See the error returned in the response.


Re-analyze an existing business

Method: POST
Endpoint: https://api.insites.com/api/v1/report/[REPORT ID]

Request body should be JSON encoded, and can include the following fields:

Property

Definition

Required

onCompletion

String – Insites will make a POST callback to this URL with the JSON report data.

No

_[custom_field_name]

String – Pass values to set as one of your custom report fields. Note: custom report fields must be configured in your account before they can be used. When passed to the API, the field ID must be prefixed with an underscore.

No

If you’re not passing any data, you don’t need to include the JSON body in your POST request.

Example

curl "<https://api.insites.com/api/v1/report/>[REPORT ID]" --header "api-key:[YOUR API KEY]" --data ""

This request returns the same responses as “Start a new business analysis” above.


Search all reports

The following parameters can be passed via GET to bring back more refined results:

Property

Definition

Required

filter

JSON encoded string – attributes by which the reports should be filtered by. This should be an array of objects and each object should contain an operator, property and target value.

No (defaults to [])

order

JSON encoded string – the attributes by which the results should be ordered by. This should be an array of objects and the filters will be applied in the order they appear in the array.

No (defaults to [{“run_date”:”desc”}])

limit

Integer – The maximum number of results that should be returned.

No (defaults to 100)

offset

Integer – The number of rows that the results should be offset by.

No (defaults to 0)

include_historic

Boolean – Whether the results should contain old versions of the business reports.

No (defaults to false)

list_id

String – Will filter the results and return only those in the given list. Note: list ID should be the 32-character hexadecimal ID provided by Insites (not the list name which is assigned by the user).

No (defaults to false)

Supported filter operators:

  • equal

  • not_equal

  • more_than

  • less_than

  • str_contains

Supported filter properties:

  • domain

  • overall_score

  • report_id

  • requested_by

  • analysis_country

  • report_completed_at

  • detected_name

  • detected_address

  • detected_phone

  • [test_name].[test_property]

Supported order properties:

  • id

  • user_email

  • report_hash

  • run_date

  • overall_score

  • overall

Supported order directions:

  • asc

  • desc


Example

curl "https://api.insites.com/api/v1/reports?filter=\[{\"operator\":\"equal\",\"property\":\"mobile.is_mobile\",\"targetValue\":false}\]&order=\[{\"run_date\":\"desc\"}\]" --header "api-key:[YOUR API KEY]"


Expected response

If successful, you would expect a 200 response, with a body like this:

{
"status": "success",
"reports": [REPORTS DATA]
}

Note: For an example of the report data, please see “Example report data” below.

All possible responses

Code

Reason

200

Report search has successfully completed

400

An invalid filter property was passed in as a filter parameter.


Fetch the settings for a business

Method: GET
Endpoint: https://api.insites.com/api/v1/report-settings/[REPORT ID]


Example

curl "<https://api.insites.com/api/v1/report-settings/>[REPORT ID]" --header "api-key:[YOUR API KEY]"


Expected response

If successful, you would expect a 200 response, with a body like this:

{
"fields": {
"mobile_optimised": {
"type": "enum",
"value": "auto",
"options": {
"auto": "Automatic detection",
"yes": "Yes",
"no": "No"
}
},
"name": {
"type": "text",
"value": "Example Business"
},
"phone": {
"type": "text",
"value": "100-800-1234"
},
"address": {
"type": "text",
"value": null
},
"sublocality": {
"type": "text",
"value": null
},
"city": {
"type": "text",
"value": null
},
"state": {
"type": "text",
"value": null
},
"zip": {
"type": "text",
"value": null
},
"country_code": {
"type": "ISO3166-1",
"value": "US"
}
},
"status": "success"
}


All possible responses

Code

Reason

200

The current settings for this report / business.

404

Report does not exist.


Update settings for a business

Method: PUT

Request body should be JSON encoded. The options available will be specific to your account configuration. Please make a request to the GET endpoint above to reveal which settings are available.

Property

Definition

Required

name

String – Business name, some checks will not work without this, e.g Local presence, Reviews

No

phone

String – Business phone number, some checks will not work without this, e.g Local presence, Reviews

No

address

String – First line of business address, some checks will not work without this, e.g Local presence, Reviews

No

number

String – Building number, enhances accuracy in some checks, e.g Local presence, Reviews

No

street

String – Street, enhances accuracy in some checks, e.g Local presence, Reviews

No

city

String – City, enhances accuracy in some checks, e.g Local presence, Reviews

No

state

String – State or county, enhances accuracy in some checks, e.g Local presence, Reviews

No

zip

String – Zip of postcode, enhances accuracy in some checks, e.g Local presence, Reviews

No

country_code

ISO 2 letter code – Country, enhances accuracy in some checks, e.g Local presence, Reviews

No

lat

String – Latitude, enhances accuracy in some checks, e.g Local presence, Reviews

No

lng

String – Longitude, enhances accuracy in some checks, e.g Local presence, Reviews

No

products

String – Products and services this business offers, some checks will not work without this, e.g Content keywords. Note: multiple products and services should be comma separated

No

locations

String – Locations served, some checks will not work without this, e.g Content keywords. Note: multiple locations should be comma separated

No

_[custom_field_name]

String – Pass values to set as one of your custom report fields. Note: custom report fields must be configured in your account before they can be used. When passed to the API, the field ID must be prefixed with an underscore.

No

Example

curl "https://api.insites.com/api/v1/report-settings/[REPORT ID]" --header "api-key:[YOUR API KEY]" --data "{\"name\\":\"Business Ltd\"}"

This request returns the new, modified settings in the same format as “Fetch the settings for a report” above.

All possible responses

Code

Reason

200

The settings for this report / business have been persisted.

404

Report does not exist.


Callback

When Insites has finished running the report, it can make a callback to an endpoint of your choice.

To get a callback on completion, just add your callback URL to the request as the parameter “onCompletion” or .

For an example of the data we post, please see “Example report data” below.


Example report data

The exact data returned via the API or sent via callback will depend on the configuration of your Insites account (e.g. country of operation and sections enabled. For your reference, here is an example:

{
"domain": "insites.com",
"contact_details": {
"email": false
},
"local_presence": {
"detected_phone": "+44 1322 460460",
"detected_address": "Insites LTD, Brunel Parkway, Pride Park, DE24 8HR, United Kingdom, United Kingdom",
"detected_name": "Insites"
},
"facebook_page": {
"page_link": "https:\\/\\/www.facebook.com\\/getinsites\\/",
"page_likes": 46560
},
"organic_search": {
"average_monthly_traffic": 5835
},
"mobile": {
"is_mobile": true,
"is_tablet": true
},
"analytics": {
"analytics_tool": "Google Analytics"
},
"incoming_links": {
"total_backlinks": 156152
},
"social_sharing": {
"url_likes": 14
},
"domain_age": {
"domain_age_days": 5560
},
"page_count": {
"pages_discovered_count": 31
},
"video": {
"has_video": false
},
"amount_of_content": {
"total_word_count": 1295,
"average_words_per_page": 259
},
"last_updated": {
"days_since_update": 108
},
"website_speed": {
"average_homepage_load_time_seconds": 4.934
},
"reviews": {
"reviews_found_count": 1,
"probably_more_reviews": false
},
"server_behaviour": {
"uses_gzip_compression": true,
"error_page_sends_404": true
},
"page_titles_and_descriptions": {
"homepage_title_tag": "Insites - making the web a better place",
"homepage_meta_description": "Helping to make the web a better place.",
"pages_missing_title_count": 0,
"pages_missing_description_count": 0,
"pages_duplicated_title_count": 0,
"pages_duplicated_description_count": 0
},
"report_id": "7b8cf004712790702635a495d6e1bf1572f67c7a",
"account_id": "prospect_testing",
"meta": {
"analysis_country": "GB",
"started_processing_at": "2016-05-27T10:04:43+00:00",
"report_requested_at": "2016-05-27T10:04:29+00:00",
"report_completed_at": "2016-05-27T10:05:08+0000",
"requested_by": "someguy@insites.com"
},
"overall_score": 83,
"analysed_page_count": 5
}
Did this answer your question?