Getting Started - Java

This Quickstart Guide

What you'll learn: How to connect and stream live data from the DataSift platform to your machine.
Duration: 10 minutes

Table Of Contents

Before You Start

Before you get started make sure you've completed the Developer Quick Start guide. This will take you through:

  • Activating the Tumblr data source
  • Activating the Links augmentation

You'll need to have done these steps to continue.

Once complete, sign-in to DataSift and make a note of your username and API key on your dashboard. You'll need them in a minute.

Step 1: Install The Client Library

The Java library is available as a Maven package here.

Maven is a package manager tool and repository, and is supported by popular IDEs - you can read more here.

Create a new Java project in your favourite IDE, and add a pom.xml file.

Add a dependency to your pom.xml file:


Or of course you can choose to use the JAR file directly in your project. The latest JAR file can be downloaded from Maven too.

Step 2: Create A DataSift Client

With the package installed, now you can write a script to access the API. Firstly we need to create a client object that will access the API for us.

For this example we'll create a command line application. Create a new class in your Java project called

Firstly add the namespaces we'll need to import for the example:

import com.datasift.client.DataSiftClient;
import com.datasift.client.DataSiftConfig;
import com.datasift.client.core.Stream;

Next add a main method, and inside create a client object with your API credentials:

public static void main(String[] args) {
// TODO: Enter your username and API key
    DataSiftConfig config = new DataSiftConfig("YOUR_USERNAME", "YOUR_APIKEY");
DataSiftClient datasift = new DataSiftClient(config);


Step 3: Compile A Filter

In order to stream data from the platform, you need to create a filter in CSDL. You compile this filter using the API and receive a hash that represents the filter.

Add the following to your main method:

try {
// Compile filter looking for mentions of brands
String csdl = "interaction.content contains_any \"Calvin Klein, GQ, Adidas\"";
Stream stream = datasift.compile(csdl).sync();
catch(Exception ex)
// TODO: Your exception handling here

Here we're using the interaction.content property (or target) of the piece of content. This is the text of the Tumblr post in this case.

Step 4: Streaming Data

With your filter compiled you can now start streaming data. This sample code shows how to declare your event handlers and kick off the data stream.

Warning: When you are running a stream you are consuming your platform credit. Your free credit gives you plenty to play with, but always remember to stop your stream if you're not using to make the most of your credit.

Add the following to your main method, under where you compiled the stream, to set up handlers for the stream and start the subscription:

datasift.liveStream().onError(new ErrorHandler()); // handles stream errors
datasift.liveStream().onStreamEvent(new DeleteHandler()); // handles data deletes

// Subscribe to the stream
datasift.liveStream().subscribe(new Subscription(stream));

Now add handlers below the main method:

// Subscription handler
public static class Subscription extends StreamSubscription {
    public Subscription(Stream stream) {

    public void onDataSiftLogMessage(DataSiftMessage di) {
        System.out.println((di.isError() ? "Error" : di.isInfo() ? "Info" : "Warning") + ":\n" + di);

    public void onMessage(Interaction i) {
        System.out.println("INTERACTION:\n" + i);

// Delete handler
public static class DeleteHandler extends StreamEventListener {
    public void onDelete(DeletedInteraction di) {
        // You must delete the interaction to stay compliant
        System.out.println("DELETED:\n " + di);

// Error handler
public static class ErrorHandler extends ErrorListener {
    public void exceptionCaught(Throwable t) {
        // TODO: do something useful..!

Step 5: Give It A Whirl

With your script now complete, you can run the example and see data pouring into your console.

Run the application using your IDE (or compile and run it at the command line).

There's a complete version of the Java class here.

Step 6: Classifying Data

To help you understand, integrate and act upon the data, DataSift allows you to add custom metadata through tags and scores. Read more about DataSift VEDO to find out more.

As a quick example, you could use tags to identify where music is being shared from. Try replacing the csdl variable in your script with the following, and run the application again.

String csdl = "tag.brand \"Calvin Klein\" { interaction.content contains \"Calvin Klein\" } " +
"tag.brand \"GQ\" { interaction.content contains \"GQ\" } " +
"tag.brand \"Adidas\" { interaction.content contains \"Adidas\" } " +
"return { " +
"interaction.content contains_any \"Calvin Klein, GQ, Adidas\" " +

You can see the tags assigned to the data, under the interaction.tag_tree property of each item.

Learn More

That's the end of the quick start guide. To learn more about the platform please take a look at the following resources: