Getting Started Guide

This guide will walk you through getting started with Keen IO using cURL from your terminal. If you want to start analyzing data as well as see some visualizations try Getting Started With Javascript

What Are We Doing?

This we believe: Getting started with Keen IO APIs should be easy. For the technical wizards among you, this guide will take you 8 minutes. For the sorcerer’s apprentices, this shouldn’t take much more than 20 minutes. If it does, we’ve failed. Let us know via email or come chat with us at users.keen.io.

Project Setup

If you haven’t done so already, login to Keen IO and create a new project. Since we’re just practicing, you might want to give it a name like “Sandbox” or “Rainbow Garden”. Projects provide a way to securely store your data and keep it separated from other data. Each project has a unique access key.

Once you’ve created your project, look for the Project ID and click the “Show API Keys” button to find the Write Key. You’ll need those soon.

Send an Event

Let’s get to the heart of it - sending events. Events are the actions that are happening that you want to track. Events of a similar type are stored in Event Collections. Collections are created on-the-fly when you send your first event. In this example we’ll create a new Event Collection “purchases” (you can pick any name you want!).

Let’s insert a new “purchase” event into the “purchases” event collection. The event should be in JSON format and look like this example.

STEP 1: Copy this example, paste it into a text editor, and save it as a “purchase1.json”.

{
  "category": "magical animals",
  "animal_type": "pegasus",
  "username": "perseus",
  "payment_type": "head of medusa",
  "price": 4.50
}

Next you’ll send this event to Keen using a command line interface like Mac’s Terminal. cURL is a simple data transfer program built into most operating systems. We’ll use cURL to do an HTTP POST to the Keen API.

STEP 2: Copy, modify, then paste the following cURL command into your terminal. Replace <PROJECT_ID>, <WRITE_KEY>, and <EVENT_COLLECTION> (e.g. purchases) with your specific values.

curl https://api.keen.io/3.0/projects/<PROJECT_ID>/events/<EVENT_COLLECTION>?api_key=<WRITE_KEY> -H "Content-Type: application/json" -d @purchase1.json

Note: Make sure to navigate your Terminal prompt to the place where you saved your event, or add a file path to your file name.

There are a couple things going on here.

  • First, we send the request to a URL that includes both the Project ID and the name of the Event Collection (e.g. purchases) where we want to store this event.
  • Since the event collection “purchases” doesn’t exist yet, Keen IO automatically creates a new event collection for you called “purchases” and stores your event there. Now you have a place to send all your purchase events in the future.
  • Second, we set a header for content-type (so the API knows it’s getting a JSON request).
  • Third, we set the body of the HTTP request to the contents of the file that we saved.

The response should look like:

{
    "created": true
}

Ta-da!

Note

Once the API acknowledges that your event has been stored, it may take up to 10 seconds before it will appear in query results.

Analyze Events

Through our data analysis API, you’ll have access to a number of different tools. But, for the moment, let’s just worry about one - counts. It does exactly what it sounds like it does; it counts the number of times an event has occurred.

We’ll try a very simple version of a count here. The first query string parameter is the “api_key”. Instead of the Write Key, this time we want to use the Read Key since we’re querying (or “reading”) the data. You can find this key right next to the Write Key on the Project Settings page. The second parameter is the “event_collection” (e.g. purchases) that we want to analyze.

Replace the <PROJECT_ID>, <READ_KEY>, and <EVENT_COLLECTION_NAME> with your own, then enter this cURL request into your terminal.

Simple Count Request

curl https://api.keen.io/3.0/projects/<PROJECT_ID>/queries/count?api_key=<READ_KEY>\&event_collection=<EVENT_COLLECTION>

Response

{
    "result": 1
}

Yup. 1. We only inserted one event, so that’s all we can count. This is just a getting started guide. Here a couple more simple examples just to show off:

Now change Count to Average and add a target_property query string parameter to let the API know which numeric property you want average. Here’s how you can run an average on the “price” property.

Average Request

curl https://api.keen.io/3.0/projects/<PROJECT_ID>/queries/average?api_key=<READ_KEY>\&event_collection=<EVENT_COLLECTION>\&target_property=price

Response

{
    "result": 4.5
}

Add a Timeframe parameter to any request to limit the results to events that happened in a particular timeframe. For example, we can set timeframe=today to count the events created today.

Request with timeframe

curl https://api.keen.io/3.0/projects/<PROJECT_ID>/queries/count?api_key=<READ_KEY>\&event_collection=<EVENT_COLLECTION>\&timeframe=today

Response

{
    "result": 1
}

You can also add an Interval parameter in order to break the results into buckets. Here’s an example with a Timeframe of the previous_5_minutes and a minutely Interval.

Request with interval

curl https://api.keen.io/3.0/projects/<PROJECT_ID>/queries/count?api_key=<READ_KEY>\&event_collection=<EVENT_COLLECTION>\&timeframe=previous_5_minutes\&interval=minutely

Response

{
  "result": [
    {
      "value": 0,
      "timeframe": {
        "start": "2014-03-29T22:44:00.000Z",
        "end": "2014-03-29T22:45:00.000Z"
      }
    },
    {
      "value": 1,
      "timeframe": {
        "start": "2014-03-29T22:45:00.000Z",
        "end": "2014-03-29T22:46:00.000Z"
      }
    },
    {
      "value": 0,
      "timeframe": {
        "start": "2014-03-29T22:46:00.000Z",
        "end": "2014-03-29T22:47:00.000Z"
      }
    },
    {
      "value": 0,
      "timeframe": {
        "start": "2014-03-29T22:47:00.000Z",
        "end": "2014-03-29T22:48:00.000Z"
      }
    },
    {
      "value": 0,
      "timeframe": {
        "start": "2014-03-29T22:48:00.000Z",
        "end": "2014-03-29T22:49:00.000Z"
      }
    }
  ]
}

That’s just the beginning. You’ll find a lot more analysis tools on our website and our API docs.

Next Steps

Congratulations! You’ve graduated from the Keen Getting Started guide. Admittedly, we’ve just scratched the surface, but hopefully you’ve got some context on which you can build.

On to the good stuff...

Data Collection

Start sending data from your app now:

Take a look at Bulk Loading if you’ve got a MixPanel account or some other historical data on-hand.

Data Analysis APIs

Now that you’ve sent at least one sample event, you might want to try checking out our query building workbench in Keen IO. Notice that all of the custom properties you send are immediately available for analysis, and you can do a lot more than counts! The workbench has some query types, but there are even more available by API. Checkout filters, funnels, and more in our analysis API docs.

Visualize Your Data

Ready to see some charts and graphs of your data? Head over to the JavaScript SDK Usage Guide to learn how to embed charts in into dashboards or web pages!

So, what are you waiting for? It only takes a few minutes and a few lines of code to start collecting the events that really matter to you.

Sign Up Free