This is important
Some data fields & filters were added along the way, and didn't exist before certain dates.
Thus, the following are applicable to filter Historical Data by, from the date added, onwards:
- country classification didn't exist before December 2014
- Entities didn't exist before March 2015.
- performance_score didn't exist before May 2015.
- domain_rank didn't exist before April 2016.
- Sentiment didn't exist before June 2016.
- has_video was added on July 2016 and didn't exist before.
- Social Signals & site_category didn't exist before August 2016.
- rating didn't exist before February 2017.
Before Using the Archive API
You must have credits available in your account to use the API. Please contact sales to purchase credits.
First Step: Set Your Query and Timeframe
To use the API, you need to call an endpoint URL with your private access token.
URL Structure -
https://webz.io/setArchiveQuery?token=xxxxx-xxxx-xxxxx&q=[QUERY]
HTTP GET Parameters
| Parameter | Description | Example |
|---|---|---|
| q | A string query containing the filters that define which posts will be returned. | Find any post containing either ipod or ipad, but not android: &q=(ipod OR ipad) -android |
| token | Your private access token that you received when you signed up. | &token=[MY TOKEN] |
| 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 in the last 5 years. The number defines the start year (inclusive) of the requested data-set timeframe. | &sy=2021 (Start Year is 2021) |
| em | End Month: a two-digit number between 01 - 12. The number defines the last month (inclusive) of the requested data-set timeframe. | &em=09 (End month is September |
| ey | End Year: a four-digit number in the last 5 years. The number defines the ending year (inclusive) of the requested data-set timeframe. | &ey=2022 (End Year is 2022) |
Request Output
| Parameter | Description |
|---|---|
| estimatedTotalPostCount | The estimated total posts matching your query for the period of time you defined. |
| confirmationToken | The token you will use in the second step to confirm the transaction. |
{
estimatedTotalPostCount: "376499",
confirmationToken: "e7044de3-e611-4e3c-9817-78e09e2cbb2e"
}
Second Step: Transaction Approval
Call the following endpoint to confirm the retrieval process of the data defined in the first step.
Confirmation will be effected by supplying the endpoint with the confirmation token (confirmationToken) that you received as an output in the first step.
URL Structure -
https://webz.io/confirmArchiveQuery?confirmationToken=xxxx-xxx-xxxx-xxxxx-xxxx
HTTP GET Parameters
| Parameter | Description |
|---|---|
| confirmationToken | The token you received as an output from the first step. |
Request Output
| Parameter | Description |
|---|---|
| confirmationToken | The token you will use in the third step to check on your order status: |
{
confirmationToken: "e7044de3-e611-4e3c-9817-78e09e2cbb2e"
}
Third Step: Monitor Order Status
Call this endpoint to monitor the status of your order:
URL Structure -
https://webz.io/getArchiveOrderStatus?confirmationToken=xxxx-xxx-xxxxx-xxxxx-xxxxx
HTTP GET Parameters
| Parameter | Description |
|---|---|
| confirmationToken | The token you received as an output from the second step. |
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) |
{
statusCode: "2"
downloadLink: "https://s3.amazonaws.com/xxxxxxxxx.zip"
statusText: "Complete"
}