Integrations / API

Report API

  • Applies to:
  • Premium
  • Enterprise

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)

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).
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 Yes
onCompletion String – Silktide Prospect will make a POST callback to this URL with the JSON report data. No
[account_name]_[custom_field_name] String – Pass values to set as one of your custom report fields. 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.
400 Your request was unprocessable, usually because you’ve requested analysis on a website with a path, which we can’t currently accept.
422 Your request was unprocessable, 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
[account_name]_[custom_field_name] String – Pass values to set as one of your custom report fields. 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)

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. RequestBin is great for trying out this feature.

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