Note
Please be aware that the following fields and filters are not available in our Open Web Archive product:
- Sentiment - Document level sentiment
- Category - Document level category
- Topic - Document level topic
- Trust - Document level trust object
- Breaking news
- Also the following: num_chars , webz_reporter , ai_allow , has_canonical
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://app.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. |
JSON Output Example:
{
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://app.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://app.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) |
JSON Output Example:
{
statusCode: "2"
downloadLink: "https://s3.amazonaws.com/xxxxxxxxx.zip"
statusText: "Complete"
}