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 Haystack.

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.haystack.report/api/v1/report/[REPORT ID]

Example

curl "https://api.haystack.report/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

Method: POST
Endpoint: https://api.haystack.report/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 – Haystack will make a POST callback to this URL with the 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.haystack.report/api/v1/report" --header "api-key: [YOUR API KEY]" --data "{\"url\":\"haystack.report\"}"

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.haystack.report/api/v1/report/[REPORT ID]
Request body should be JSON encoded, and can include the following fields:

Property Definition Required
onCompletion String – Haystack will make a POST callback to this URL with the 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.haystack.report/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.


Callback

When Haystack 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 Haystack 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":"haystack_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":"andrewwaite@silktide.com"
   },
   "overall_score":83,
   "analysed_page_count":5
}
  • Was this helpful?
  • Yes   No