This is the official Python Client for the Keen IO API. The Keen IO API lets developers build analytics features directly into their apps.

This is still under active development. Stay tuned for improvements!

Use pip to install!

pip install keen

This client is known to work on Python 2.6, 2.7, 3.2 and 3.3.

For versions of Python < 2.7.9, you’ll need to install pyasn1, ndg-httpsclient, pyOpenSSL.

To use this client with the Keen IO API, you have to configure your Keen IO Project ID and its access keys (if you need an account, sign up here - it's free).

Setting a write key is required for publishing events. Setting a read key is required for running queries. The recommended way to set this configuration information is via the environment. The keys you can set are KEEN_PROJECT_ID, KEEN_WRITE_KEY, KEEN_READ_KEY, and KEEN_MASTER_KEY.

If you don't want to use environment variables for some reason, you can directly set values as follows:

    keen.project_id = "xxxx"
    keen.write_key = "yyyy"
    keen.read_key = "zzzz"
    keen.master_key = "abcd"

You can also configure unique client instances as follows:

    from keen.client import KeenClient

    client = KeenClient(
        project_id="xxxx",
        write_key="yyyy",
        read_key="zzzz",
        master_key="abcd"
    )

Once you've set KEEN_PROJECT_ID and KEEN_WRITE_KEY, sending events is simple:

    keen.add_event("sign_ups", {
        "username": "lloyd",
        "referred_by": "harry"
    })

Or if using unique client instances:

    client.add_event(...)

You can upload Events in a batch, like so:

    # uploads 4 events total - 2 to the "sign_ups" collection and 2 to the "purchases" collection
    keen.add_events({
        "sign_ups": [
            { "username": "nameuser1" },
            { "username": "nameuser2" }
        ],
        "purchases": [
            { "price": 5 },
            { "price": 6 }
        ]
    })

That's it! After running your code, check your Keen IO Project to see the event/events has been added.

Here are some examples of querying. Let's assume you've added some events to the "purchases" collection.

    keen.count("purchases", timeframe="this_14_days") # => 100
    keen.sum("purchases", target_property="price", timeframe="this_14_days") # => 10000
    keen.minimum("purchases", target_property="price", timeframe="this_14_days") # => 20
    keen.maximum("purchases", target_property="price", timeframe="this_14_days") # => 100
    keen.average("purchases", target_property="price", timeframe="this_14_days") # => 49.2

    keen.sum("purchases", target_property="price", group_by="item.id", timeframe="this_14_days") # => [{ "item.id": 123, "result": 240 }, { ... }]

    keen.count_unique("purchases", target_property="user.id", timeframe="this_14_days") # => 3
    keen.select_unique("purchases", target_property="user.email", timeframe="this_14_days") # => ["bob@aol.com", "joe@yahoo.biz"]

    keen.extraction("purchases", timeframe="today") # => [{ "price" => 20, ... }, { ... }]

    keen.multi_analysis("purchases", analyses={
        "total":{
            "analysis_type": "sum",
            "target_property":"price",
            "timeframe": "this_14_days"
        },
        "average":{
            "analysis_type": "average",
            "target_property":"price",
            "timeframe": "this_14_days"
        }
    ) # => {"total":10329.03, "average":933.93}

    step1 = {
        "event_collection": "signup",
        "actor_property": "user.email"
    }
    step2 = {
        "event_collection": "purchase",
        "actor_property": "user.email"
    }
    keen.funnel([step1, step2], timeframe="today") # => [2039, 201]

To return the full API response (as opposed to the singular "result" key), set all_keys=True.

For example, keen.funnel([step1, step2], all_keys=True) would return "result", "actors" and "steps" keys.

The Keen IO API allows you to delete events from event collections, optionally supplying filters, timeframe or timezone to narrow the scope of what you would like to delete.

You'll need to set your master_key.

    keen.delete_events("event_collection", filters=[{"property_name": 'username', "operator": 'eq', "property_value": 'Bob'}])

See below for more options.

Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use ISO-8601 Format.

Keen stores all date and time information in UTC!

    keen.add_event("sign_ups", {
        "keen": {
            "timestamp": "2012-07-06T02:09:10.141Z"
        },
        "username": "lloyd",
        "referred_by": "harry"
    })

By default, GET requests will timeout after 305 seconds. If you want to manually override this, you can create a KeenClient with the "get_timeout" parameter. This client will fail GETs if no bytes have been returned by the server in the specified time. For example:

    from keen.client import KeenClient

    client = KeenClient(
        project_id="xxxx",
        write_key="yyyy",
        read_key="zzzz",
        get_timeout=100

    )

This will cause queries such as count(), sum(), and average() to timeout after 100 seconds. If this timeout limit is hit, a requests.Timeout will be raised. Due to a bug in the requests library, you might also see an SSLError (https://github.com/kennethreitz/requests/issues/1294)

By default, POST requests will timeout after 305 seconds. If you want to manually override this, you can create a KeenClient with the "post_timeout" parameter. This client will fail POSTs if no bytes have been returned by the server in the specified time. For example:

    from keen.client import KeenClient

    client = KeenClient(
        project_id="xxxx",
        write_key="yyyy",
        read_key="zzzz",
        master_key="abcd",
        post_timeout=100

    )

This will cause both add_event() and add_events() to timeout after 100 seconds. If this timeout limit is hit, a requests.Timeout will be raised. Due to a bug in the requests library, you might also see an SSLError (https://github.com/kennethreitz/requests/issues/1294)

The Python client enables you to create Scoped Keys easily. For example:

    from keen.client import KeenClient
    from keen import scoped_keys

    api_key = KEEN_MASTER_KEY

    write_key = scoped_keys.encrypt(api_key, {"allowed_operations": ["write"]})
    read_key = scoped_keys.encrypt(api_key, {"allowed_operations": ["read"]})

write_key and read_key now contain scoped keys based on your master API key.

• fixed timestamp overriding keen addons
• add get_collection and get_all_collections methods

• Added all_keys parameter which allows users to expose all keys in query response.
• Added delete_events method.

• Added better error handling to surface all errors from HTTP API calls.

• Added compatibility for pip 1.0

• Added compatibility for pip < 1.5.6

• Made requirements more flexible.

• Added requirements.txt to pypi package.

• Fixed requirements in setup.py
• Updated test inputs and documentation.

• Added master_key parameter.

• Mocked tests.
• Added median query method.
• Added support for $python setup.py test.

• Upgraded to requests==2.5.1

• Added max_age parameter for caching.

• Added client configurable timeout to gets.

• Added percentile query method.

• Support interval parameter for multi analyses on the keen module.

• Reuse internal requests' session inside an instance of KeenApi.

• Support property_names parameter for extractions.

• Added client configurable timeout to posts.
• Upgraded to requests==2.2.1.

• Fixed sys.version_info issue with Python 2.6.

• Added interval to multi_analysis.

• Added stacktrace_id and unique_id to Keen API errors.

• Added add_events method to keen/init.py so it can be used at a module level.
• Added method to generate image beacon URLs.

• Added support for publishing events in batches
• Added support for configuring client automatically from environment
• Added methods on keen module directly

• Added querying support

• Bugfix to use write key when sending events - do not use 0.1.6!

• Changed project token -> project ID.
• Added support for read and write scoped keys.
• Added support for generating scoped keys yourself.
• Added support for python 2.6, 3.2, and 3.3

• Added documentation.

• Asynchronous insert
• Scoped keys

If you have any questions, bugs, or suggestions, please report them via Github Issues. We'd love to hear your feedback and ideas!

This is an open source project and we love involvement from the community! Hit us up with pull requests and issues.