Create a preview of a Historics query.
|Check out What is Historics Preview? and read our Historics API step-by-step page to learn more.|
All calls to the API must be versioned. The current version is v1.
An HTTPS request sent to
UTC timestamp to start the report from; this will be rounded to the previous hour. The start must be on or after midnight, January 1st 2010 and prior to now - 2 hours. Please make sure that you understand the concept of time zones, UTC, and convert date and time to UTC before you submit it to DataSift. You can use an online converter.
Example values: 1325548800
UTC timestamp at which to end the report. The end must be greater than or equal to start, and prior to now - 1 hour. If not specified, defaults to the earliest out of start + 24 hours or now - 1 hour. This will be rounded to the next hour. You can only analyze a maximum of 24 hours' worth of past data in one Historics Preview job.
Example values: 1325549800
The hash of the filter to preview.
Example values: 2459b03a13577579bca76471778a5c3d
Comma-separated list of data sources to include. In the future, you will be able to choose any source listed as a valid value that you would use in the interaction.type target. Currently, you can use any of the sources shown here.
Example values: twitter, facebook, bitly, tumblr
A list of at least one but no more than 20 Historics Preview parameters each formatted as a comma-separated string:
Historic Preview parameters are separated with semicolons (;), for example
Each parameter defines the target and the statistical analysis to be performed on that target along with an optional argument that customizes its results. You have a choice of four types of statistical analyses you can perform on a selected target:
freqDist - target frequency distribution. This analysis takes a threshold argument that controls the number of values returned in the output (max 100). For example, if you want to know the frequency distribution of the top 10 languages used in the matching interactions, you would specify:
numStats - results of a numeric statistical analysis of the given target. The values of the given target will be analyzed in hourly intervals, and for each interval you will receive minimum, maximum, count, and sum values.
targetVol - returns how many times the specified target appears in the results, in hourly intervals.
wordCount - returns a list of up to 100 most often used words found in the specified target inside the 1 percent stream that the new Historics Preview will be based on. For example, if you are doing an analysis of conversations happening on Twitter and you want top ten words found in the matching Tweets, set this parameter to:
Example values: interaction.author.link,targetVol,hour;interaction.type,freqDist,10
1. Here is an example of a call to /v1/preview/create:
Successful calls to /v1/preview/create return HTTP Code: 202 Accepted.
Status: Running (HTTP Code: 202 Accepted)
A success response will contain the GUID (hash) of the new preview. The initial status of each new Historics Preview job is set to queued. If you want to monitor the progress of your query, you need to call /preview/get.
When things go wrong the Historics Preview API responds with the following errors:
No stream found for the given hash (HTTP Code: 404 Not Found)
Returned when you supply a non-existent stream hash id. If you forget the id of the stream you want to use for the Historics Preview, call /usage.
Start must be at least two hours ago (HTTP Code: 400 Bad Request)
The timestamp given as the value of the start parameter was set to a value smaller than current UTC - 7200 seconds. Adjust the value of the start timestamp and try again.
End must be at least one hour ago (HTTP Code: 400 Bad Request)
The timestamp given as the value of the end parameter was set to a value smaller than current UTC - 3600 seconds. Adjust the value of the end timestamp and try again.
Target target.name invalid (HTTP Code: 400 Bad Request)
You made a typo in the target name. Correct it and try again
analysisName is an invalid analysis for target.name (HTTP Code: 400 Bad Request)
You are trying to perform a statistical analysis that does made sense for the chosen target, for example, interaction.author.link cannot be analyzed using targetVol. Please refer to our target-analysis matrix for help, then correct your call to /preview/create and try again.
All calls to the API must be properly authenticated with a DataSift username and API key.
- All calls to the API must be versioned. The current version is v1.