Streams

What is an event? An event is a record of something important happening in the life of your app or service: like a click, a purchase, or a device activation.

We make it easier than ever to collect large volumes of these events over time. Events are recorded as individual JSON objects, each containing a timestamp and customizable properties that describe the state of the world when they occurred. These events can be sent individually or in bundles, accumulating within collections for later analysis.

Here are a few tips to get started:

Record a single event
Record multiple events

API URL

Each request body is a single JSON object.
Basic variable types are supported, and even required to ensure full analysis potential. Important: Arrays of objects are inaccessible to analysis and filtering capabilities. Learn more in our Data Modeling Guide.
Nesting objects is OK. In fact, it makes life easier! Nesting common objects consistently will make your data easier to reason about later (Especially if you're on a team!)
keen.timestamp can be manually overwritten. This keen object is created automatically, but you can provide your own timestamp value for localized or historical event data.

Learn more in our Data Modeling Guide

{
  "item": "Fancy turtleneck with deer on it",
  "price": 469.50,
  "on_sale": true,
  "payment_method": "Bank Simple VISA",
  "customer": {
    "name": "Francis Woodbury",
    "age": 28,
    "address": {
      "city": "San Francisco",
      "country": "USA"
    }
  },
  "keen": {
    "timestamp": "2015-05-27T22:44:50.722Z"
  }
}

API URL

Each request body is a single JSON object.
Top-level keys are named for each event collection, and correspond to a list of events to be recorded. This is one of the few cases where arrays are ok :)
All of the same rules apply for individual events!

Learn more in our Data Modeling Guide

{
  "purchases": [
    {
      "item": "Golden gadget",
      "price": 25.50,
      "transaction_id": "f029342"
    },
    {
      "item": "Different gadget",
      "price": 17.75,
      "transaction_id": "f029342"
    }
  ],
  "transactions": [
    {
      "id": "f029342",
      "items": 2,
      "total": 43.25
    }
  ]
}

Find an SDK to get up and running fast!!

Bulk Uploads
Upload a CSV file with the Keen CLI

Tracking Pixels
Record events when an image is loaded

URL Redirects
Record events when a URL is requested

Data Enrichment

Powerful add-ons enrich the data you're already collecting

Configure with an IP address:

{
  "ip_address" : "${keen.ip}",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:ip_to_geo",
        "input" : {
          "ip" : "ip_address"
        },
        "output" : "ip_geo_info"
      }
    ]
  }
}

This example uses the ${keen.ip} placeholder, but standard IP addresses work too. Learn more about dynamic placeholders in the API reference.

We’ll fill in geographic information:

{
  "ip_address" : "192.168.0.1",
  "ip_geo_info" : {
    "city" : "San Francisco",
    "province" : "California",
    "country" : "United States",
    "continent" : "North America",
    "postal_code" : "94122",
    "coordinates" : [-122.42005, 37.77479]
  }
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with a user agent string:

{
  "user_agent" : "${keen.user_agent}",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:ua_parser",
        "input" : {
          "ua_string" : "user_agent"
        },
        "output" : "parsed_user_agent"
      }
    ]
  }
}

This example uses the ${keen.user_agent} placeholder, but standard user agent strings work too. Learn more about dynamic placeholders in the API reference.

We’ll fill in available information:

{
  "user_agent": "Mozilla/5.0 (iPhone; U; CPU iPhone OS 5_1_1 like Mac OS X; en AppleWebKit/534.46.0 (KHTML, like Gecko) CriOS/19.0.1084.60 Mobile/9B206 Safari/7534.48.3",
  "parsed_user_agent" : {
    "device" : {
      "family" : "iPhone",
      "type": "mobile phone"
    },
    "browser" : {
      "family" : "Chrome Mobile iOS",
      "major" : 19,
      "minor" : 0,
      "patch" : 1084
    },
    "os" : {
      "family" : "iOS",
      "major" : 5 ,
      "minor" : 1,
      "patch" : 1,
      "patch_minor" : null
    }
  }
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with a URL:

{
  "page_url" : "http://my-website.com/cool/link?source=twitter&foo=bar/#title",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:url_parser",
        "input" : {
          "url" : "page_url"
        },
        "output" : "parsed_page_url"
      }
    ]
  }
}

Missing URL elements, such as a query string or anchor, will be omitted from the recorded output object.

We’ll parse the URL into queryable pieces:

{
  "page_url" : "http://my-website.com/cool/link?source=twitter&foo=bar/#title",
  "parsed_page_url": {
    "protocol" : "http",
    "domain" : "my-website.com",
    "path" : "/cool/link",
    "anchor" : "title",
    "query_string" : {
      "source" : "twitter",
      "foo" : "bar"
    }
  }
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with page and referrer URLs:

{
  "referrer" : {
    "url": "https://search.com?search=analytics"
  },
  "page_url": "http://mysite.com/landing-page",
  "keen" : {
    "addons" : [
      {
        "name" : "keen:referrer_parser",
        "input" : {
          "referrer_url" : "referrer.url",
          "page_url" : "page_url"
        },
        "output" : "referrer.info"
      }
    ]
  }
}

Mal-formed page_url or referrer_url input parameters will result in blank output values.

We’ll parse the referrer into its source:

{
  "referrer": {
    "url": "https://search.com?search=analytics",
    "info": {
      "medium" : "SEARCH",
      "source" : "search.com",
      "term" : "analytics"
    }
  },
  "page_url": "http://mysite.com/landing-page"
}

The keen.addons configuration will be omitted from the recorded event. Learn more about the keen object in the API reference.

Configure with a datetime property:

{
  "keen" : {
    "timestamp": "2016-05-21T16:36:40.092Z"
    "addons": [
      {
        "name": "keen:date_time_parser",
        "input": {
          "date_time": "keen.timestamp",                                
        },
        "output": "timestamp_info"
      }
    ]
  }
}

This example uses the keen.timestamp property, but this will work with any property that looks like a datetime.

We’ll fill in datetime information:

{
  "keen": {
    "timestamp": "2016-05-21T16:36:40.092Z"
  },
  "timestamp_info": {
    "millisecond": 92,
    "day_of_week_string": "Saturday",
    "hour": 16,
    "timezone_offset": 0,
    "day_of_month": 21,
    "day_of_week": 6,
    "month": 5,
    "second": 40,
    "week": 20,
    "year": 2016,
    "minute": 36
  }
}