Getting Started with Keen IO

Keen IO is an analytics API for modern developers. Track any event: signups, upgrades, impressions, purchases, powerups, errors, shares… Use Keen IO to embed analytics in your site or white label analytics for your customers. Keen IO is your new, lovingly crafted, massively scalable, event data backend in the cloud.

What are we doing in this guide?

We believe that 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!

There are three basic steps to using Keen IO, and this guide will walk you through steps 1 and 2 using cURL from your terminal.

  • Step 1: Send Your Data

  • Step 2: Analyze Your Data

  • Step 3: Visualize Your Data

If you want to start analyzing data from your app right away, as well as see some visualizations, start using our JavaScript SDK.

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.

1 - Send Your Data

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 and call it “purchases”, but 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 “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, EVENT_COLLECTION, and WRITE_KEY 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
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 of things going on here:

  • First, we send the request to a URL that includes both the Project ID and the name of the event collections. where we want to store this event. In this example, the name of your EVENT_COLLECTION would be “purchases”.
  • 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!

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

2 - Analyze Your Data

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 page, after you click “Show API Keys”. The second parameter is the name of the “event_collection” (e.g. purchases) that we want to analyze.

Replace the PROJECT_ID, READ_KEY, and EVENT_COLLECTION 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&timeframe=this_14_days"

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 are three more simple examples just to show off:

Average Request

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

curl "https://api.keen.io/3.0/projects/PROJECT_ID/queries/average?api_key=READ_KEY&event_collection=EVENT_COLLECTION&target_property=price&timeframe=this_14_days"

Response:

{
    "result": 4.5
}

The Timeframe Parameter

Use the timeframe parameter 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.

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
}

Request with Interval

You can also add an interval parameter in order to break the results into buckets. Here’s an example with an average of the previous_5_minutes and a “minutely” 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 Reference.

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 what you can build.

Now you can move onto the good stuff and build analytics into your own app! You’ll follow the same basic three steps to using Keen, but now you’ll select from our full range of SDK’s, analysis, and visualization tools.

1. Send Your Data

Start sending data from your own app now using one of our SDK’s

Collection Analysis Visualization

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

2. Analyze Your Data

  • Run counts, sums, averages, medians, build funnels, and more using our Analysis APIs!
  • Now that you’ve sent at least one sample event, you might want to try checking out our query builder, Data Explorer, 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. Check out filters, funnels, and more in our analysis API docs.

3. Visualize Your Data

  • Ready to see some charts and graphs of your data? Head over to the visualization documentation to learn how to embed charts into dashboards or web pages!

Questions? Reach out to us anytime at team@keen.io or chat with us on Keen Community Slack! If you’d like to learn more about how to get the most out of your data, reach out to Schedule a free data consultation with our data science team.