Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Accessing the Archive via an API

Before you can use the API

You must set your billing information.

Important Note

Some data fields where added along the way and don't exist before certain dates.

  • Performance Score didn't exist before May 2015
  • Sentiment didn't exist before June 2016
  • Review Ratings didn't exist before Feb 2017
  • Social Signals & Site Categories didn't exist before Aug 2016

Accessing the archive via an API is very simple. Just follow these 3 steps:

Step 1: Set the Query & Timeframe

Accessing the archive via an API is very simple. Just follow these 3 steps:

https://webhose.io/setArchiveQuery?q=Microsoft&sm=05&sy=2015&em=09&ey=2015&token=xxx-xxxxx-xxxxxx-xxxx-xxx

HTTP GET Parameters

Parameter
Description
Example

q

A Boolean query containing the filters that define which posts will be returned

&q=(ipod OR ipad) -android

sm

Start Month: a two digit number between 01 - 12. The number defines the start month (inclusive) of the requested data-set timeframe.

&sm=05 (Start month is May)

sy

Start Year: a four digit number between 2014 and the current year. The number defines the start year (inclusive) of the requested data-set timeframe.

&sy=2015 (Start Year is 2015)

em

End Month: a two digit number between 01 - 12. The number defines the last month (inclusive) of the requested data-set timeframe.

&em=7 (End month is July)

ey

End Year: a four digit number between 2014 and the current year. The number defines the ending year (inclusive) of the requested data-set timeframe.

&ey=2015 (End Year is 2015)

format (optional)

The output format of the results set. It can be either JSON or XML (the default is json)

&format=xml

token

Your private access token. You get a unique access token when you sign up.

Request Output

Parameter
Description

costInUSD

The cost in USD for the data retrieval from the archive

estimatedTotalPostCount

The estimated total posts matching your query for the period of time you defined.

confirmationToken

The token you will use in step 2, to confirm the transaction

{
    "costInUSD":"30",
    "estimatedTotalPostCount":"32544",
    "confirmationToken":"e7044de3-e611-4e3c-9817-78e09e2cbb2e"
}
    

Step 2: Transaction Approval

Call this endpoint to confirm and pay (payment details must be set beforehand in the settings console) for the retrieval process of the data defined on step 1. The confirmation will be done by supplying the endpoint with the confirmation token (confirmationToken) you received as an output on step 1.

https://webhose.io/confirmArchiveQuery?confirmationToken=xxxx-xxx-xxxx-xxxxx-xxxx

HTTP GET Parameters

Parameter
Description

confirmationToken

The token you received as an output in step 1.

Request Output

Parameter
Description

confirmationToken

The token you will use in step 3, to check on your order status

{
"confirmationToken":"e7044ee6-e691-493c-9817-78e09e2cbb2e"
}
                    

Step 3: Monitor order status

Call this endpoint to confirm and pay (payment details must be set beforehand in the settings console ) for the retrieval process of the data defined on step 1. The confirmation will be done by supplying the endpoint with the confirmation token (confirmationToken) you received as an output on step 1.

https://webhose.io/getArchiveOrderStatus?confirmationToken=xxxx-xxx-xxxxx-xxxxx-xxxxx

HTTP GET Parameters

Parameter
Description

confirmationToken

The token you received as an output in step 2.

Request Output

Parameter
Description

statusCode

A numerical code stating the status of the job:

  • 0 - the data retrieval process is queued and didn't start yet.
  • 1 - the process has started and the system is retrieving the data
  • 2 - the process is done and you can download the data from the link presented on the "downloadLink" parameter.

statusText

A textual explanation about the job status.

downloadLink

A link to a zip file that contains the data. The link will appear when the job is done (statusCode = 2). The link contains zip files (one for each month) holding either JSONs or XMLs representing the posts.

{
    "statusCode":"2",
    "downloadLink":"https://s3.amazonaws.com/xxxxxxxxx.zip",
    "statusText":"Complete"
}
                    

Accessing the Archive via an API