Historics Preview API: Step-by-Step

Make sure you check out our introduction to this topic. It's called What is Historics Preview?

The preview endpoints of the DataSift API allow you to estimate the time and expense required to complete a Historics query before you commit your time and money. A Historics Preview must be based on the same stream as the Historics query. To learn how to create a stream using our API, read our introduction to the DataSift REST API. Once you have read it, do the following:

  1. Create a stream using /compile.
    Historics Preview takes a one-percent sample of the stream you want to use. Make sure that your stream does not use interaction.sample targets because they will have a cumulative effect, that is you could be sampling one percent of one percent when you use interaction.sample < 2 in your filter.

  2. Keep a note of the hash id returned by /compile.

  3. Call /preview/create to create a Historics Preview.

  4. Keep a note of the preview id returned by /preview/create.

  5. Call /preview/get and check the value of the progress key in the JSON output.

  6. Repeat step 5 until the value of the progress key is equal to 100 and the status key is set to completed.

The data key will hold the results of the preview. That value is a list of up to 20 items. These items are dictionaries whose keys are:

  • target (which target was analyzed)
  • analysis (what kind of analysis was performed)
  • output (the results of the analysis)

You can use output the for further analysis, graphing, decision making, and estimating the usefulness of the filter and the data set you wish to run a full Historics query on.

What next?

Learn about the types of preview you can generate.