Report API | Insites Help Center

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.

Method: POST
Endpoint: https://api.insites.com/api/v1/report

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

Method: GET
Endpoint: https://api.insites.com/api/v1/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

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

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
}