Report API

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

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 business report

Method: GET
Endpoint: https://api.prospect.silktide.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.prospect.silktide.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 business analysis

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

Method: POST
Endpoint: https://api.prospect.silktide.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 – Silktide Prospect 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)
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 prefixed with an underscore. No

Example

curl "https://api.prospect.silktide.com/api/v1/report" --header "api-key: [YOUR API KEY]" --data "{\"url\":\"prospect.silktide.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.prospect.silktide.com/api/v1/report/[REPORT ID]
Request body should be JSON encoded, and can include the following fields:

Property Definition Required
onCompletion String – Silktide Prospect 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 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.prospect.silktide.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 business reports

Method: GET
Endpoint: https://api.prospect.silktide.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 Silktide Prospect (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.prospect.silktide.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.

Callback

When Silktide Prospect 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”. 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 Silktide Prospect account (e.g. country of operation and sections enabled. For your reference, here is an example:

{
   "domain":"silktide.com",
   "contact_details":{
      "email":false
   },
   "local_presence":{
      "detected_phone":"+44 1322 460460",
      "detected_address":"Silktide LTD, Brunel Parkway, Pride Park, DE24 8HR, United Kingdom, United Kingdom",
      "detected_name":"Silktide"
   },
   "facebook_page":{
      "page_link":"https:\/\/www.facebook.com\/silktide\/",
      "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":"Silktide - 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@silktide.com"
   },
   "overall_score":83,
   "analysed_page_count":5
}

 

  • Was this helpful?
  • Yes   No

Contact our support team

Have more questions? Paid users can log in and email or chat with us.