NAV Navbar
shell python javascript
  • Introduction
  • Quick Start
  • Authentication
  • Graph Data
  • Advanced Configuration
  • Releases
  • Frequently Asked Questions (FAQ)
  • Errors
  • Introduction

    Welcome to the KIProtect Analytics API! Our Analytics API allows you to access all of the graph data endpoints configured in our hosted stream anonymization dashboard, so you can build your own visualizations and business analysis -- all with anonymized event data!

    We have language bindings in Shell, Python and Javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Quick Start

    Want to dive in? Follow these steps!

    Or, keep browsing the documentation!

    Authentication

    To send a request to the API with your token, send it as a header argument using Authorization: Bearer YOUR_TOKEN_HERE.

    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" https://analytics.kiprotect.com/api/events/default
    
    import requests
    
    data = requests.get('https://analytics.kiprotect.com/api/events/default',
                        headers={
                            'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    const https = require('https');
    
    var options = {
        host: 'analytics.kiprotect.com',
        port: 443,
        path: '/api/events/default'
        method: 'GET',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    Make sure to replace YOUR_TOKEN_HERE with your API access token.

    To sign up for a developer token, please visit your access token page. Your token should be kept private and only shared with trusted individuals (i.e. one token for team use). The token will be utilized on all requests to the APIs and will be used to track your usage with regard to request limits and data usage per day.

    To find out more about available API plans, please see our our Usage Plans.

    Graph Data

    Most likely you are reading this documentation because you have already setup your analytics and would like to use the data to make some custom graphs or visualizations. This is fairly easy to do once you have generated an Analytics Dashboard access token. You can access your graph data using the access token via a simple signed GET request.

    The following examples will load data from the default stream. If you want to load a different stream, you will need to replace "default" in the URL with the stream ID. All streams that are set up (i.e. one for each dashboard) are available to you by sending a signed GET request to https://analytics.kiprotect.com/api/events/.

    import requests
    
    data = requests.get('https://analytics.kiprotect.com/api/events/default/graphs/data', 
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://analytics.kiprotect.com/api/events/default/graphs/data
    
    const https = require('https');
    
    var options = {
        host: 'analytics.kiprotect.com',
        port: 443,
        path: '/api/events/default/graphs/data'
        method: 'GET',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    If you would prefer to look at data for a particular graph, this is available by modifying the URL endpoint. The logic is as follows:

    https://analytics.kiprotect.com/api/events//graphs//data

    To see all graphs for a stream, send a signed GET request to https://analytics.kiprotect.com/api/events//graphs.

    The data is organized as follows:

    Key Description
    data This contains the 10 most recent anonymized datapoints for each matching group or data points. For each group, there will then be lists x and y, correlating to the X and Y axis of the chart and some group information as well as label information. Note: some aggregations do not have groups, and so groups can be empty.
    params These are extra parameters for the graph such as the minimum and maxiumum of the X values, which represent the time window information.
    title A generated title which gives you the display name and some extra grouping information about that aggregation.

    If you need to request previous time windows, or you would like to change the number of items returned, you may append query parameters to your graph data request.

    Query Parameter Example Description
    page page=2 Paginate over the results. Default page is 1.
    page_size page_size=20 Change page size. Default page is 10.
    window_from window_from='2017-10-01T00:00Z' Adjust time windows of returned data. From is the start of the time windows. We support RFC-3339 and Unix time formats.
    window_to window_to='1543590963' Adjust time windows of returned data. To is the end of the time windows. We support RFC-3339 and Unix time formats

    Advanced Configuration

    If you'd like to configure new graphs, update graphs or setup a new dashboard via the API, you're in the right place. These are considered advanced functionality in the API and may change in future releases.

    Initial Setup

    To setup the application, you will need to send the initial configuration of the dashboard to the setup URL. Here is an example of the configuration details you will need.

    \* example setup.json *\
    {
        "display_name": "My Dashboard",
        "display_logo": "https://mysite.com/logo.png",
        "organization_name": "my_org",
        "organization_id": "KIPROTECT_ORG_ID",
        "kiprotect_api_key": "KIPROTECT_API_KEY"
    }
    

    You will need to get the organization_id and KIProtect API key from your KIProtect application dashboard. You can then POST this data to the setup API endpoint using a signed request: https://analytics.kiprotect.com/api/setup

    Configuring Event Streams

    Streams are configured via several endpoints using the stream configuration information. The possible fields are as follows:

    Field Name Example Description Required
    display_name "My Event Stream" Stream Display Name t
    backend "file_upload" Input Type. One of 'firebase', 'bigquery', 'file_upload', 'kafka'. t
    agg_column "visit_time" Column to use for aggregations that require data (i.e. mean) only for 'mean'
    agg_functions ["count", "uniques"] List of functions to use for aggregation. One of 'count', 'mean', 'uniques' t
    order_by "timestamp" Column to order by for querying new data. f
    order 0 return order of the graph (0-indexed) f
    time_format "rfc3339" Time Format. Currently, only "unix" and "rfc3339" are supported. t
    time_column "timestamp" Name of the time column. t
    id_column "app_id" Name of the unique ID column. If none set, uniques cannot be used or must be set on a per-graph basis. f
    input_params {"url": "https://firebase.io/my-project"} Extra JSON required for input parameters. for all non-file-upload backends

    For the non-required columns, such as agg_column, this is where you can set defaults to be used for your analytics (i.e. for future graphs which you'd like to use the stream default).

    Example Event Stream Data

    Here is a short example of a Event Stream JSON object. Please refer to the KIProtect API documentation section covering the appropriate input parameters for your chosen input.

    \* example event.json *\
    {
        "display_name": "GA BigQuery Events",
        "backend":      "bigquery",
        "order_by": "timestamp",
        "time_column": "timestamp",
        "time_format": "unix",
        "id_column": "app_id",
        "order": 0,
        "input_params": {
            "project": "my_project"
            "dataset": "my_dataset",
            "table": "my_table",
            "credentials": CREDENTIALS,
        }
    }
    

    Please note that the order should be unique per analytics account; if it is not included, an order will be assigned at creation.

    Adding a new event stream

    To add a new event stream, you need to post the example data to the stream creation endpoint.

    import requests
    import json
    
    data = requests.post('https://analytics.kiprotect.com/api/events', 
                json=json.load('event.json'),
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
        -d @event.json
        https://analytics.kiprotect.com/api/events
    
    const https = require('https');
    
    var options = {
        host: 'analytics.kiprotect.com',
        port: 443,
        path: '/api/events'
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
        body: /* here you would specify your event.json structure */
    
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    Editing an event stream

    To edit an event stream, use the stream specific URL, and send a post request using the same information as when adding a stream: https://analytics.kiprotect.com/api/events/<STREAM_ID>

    Removing an event stream

    Currently, there is not API access for removing an event stream. Please contact us for help removing or pausing streams.

    Configuring Graphs

    Graphs are configured via several endpoints using the graph configuration information. The possible fields are as follows:

    Field Name Example Description Required
    display_name "Unique Visitors" Graph Display Name t
    graph_type "bar" Graph Type. One of 'timeseries', 'line', 'bar', 'map', 'table', 'number'. t
    agg_column "visit_time" Column to use for aggregations that require data (i.e. mean) only for 'mean'
    agg_functions ["count", "uniques"] List of functions to use for aggregation. One of 'count', 'mean', 'uniques' t
    group_by ["country", "event_type"] List of groupings to aggregate your events. These must be fields included in each data point which you would like to track and group by. f
    time_windows ["day", "day-by-hour" List of windows to track. Choices are 'hour', 'day', 'day-by-hour' (last 24 hours rolling), 'week', 'week-by-day' (last 7 days rolling), 'month', 'month-by-day' (last 30 days rolling), 'year'. t
    time_format "rfc3339" Time Format. Currently, only "unix" and "rfc3339" are supported. If none set, the default for the stream is used. f
    time_column "timestamp" Name of the time column. If none set, the default for the stream is used. f
    id_column "app_id" Name of the unique ID column. If none set, the default for the stream is used. f
    query_params {"most_recent": true} Extra JSON to save query parameters. f
    order 0 return order of the graph (0-indexed) f

    Example JSON object

    Here is an example graph configuration JSON:

    \* example graph data.json *\
    { 
        "display_name": "Active Users",
        "graph_type": "timeseries",
        "agg_functions": ["uniques"],
        "time_windows": ["day", "week-by-day", "month-by-day"],
        "id_column": "app_id"
    }
    

    Adding a new graph

    To add a new graph, send an authenticated POST request with the above structure and required fields to the creation endpoint: https://analytics.kiprotect.com/api/events/<STREAM_ID>/graphs/

    These examples assume you have the graph data (as shown above) in a JSON file data.json.

    import requests
    import json
    
    data = requests.post('https://analytics.kiprotect.com/api/events/<STREAM_ID>/graphs/', 
                json=json.load('data.json'),
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
        -d @data.json
        https://analytics.kiprotect.com/api/events/<STREAM_ID>/graphs/
    
    const https = require('https');
    
    var options = {
        host: 'analytics.kiprotect.com',
        port: 443,
        path: '/api/events/default/graphs/data'
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
        body: /* here you would specify your data.json structure */
    
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    Editing a graph

    To edit a graph, use the graph specific URL, and send a post request using the same information as when adding a graph: https://analytics.kiprotect.com/api/events/<STREAM_ID>/graphs/<GRAPH_NAME>

    Removing a graph

    To remove a graph, simply send an authenticated DELETE request to the graph API endpoint: https://analytics.kiprotect.com/api/events/<STREAM_ID>/graphs/<GRAPH_NAME>

    Releases

    1 December 2018: This is the v0.1.0 release of the KIProtect Analytics API. Our release schedule is not explicitly set, but we encourage feedback and feature requests which we will integrate in future releases.

    For more information of our plans, please refer to our release schedule and product roadmap.

    Planned Future Releases

    Product Roadmap

    Our current product roadmap will cover the following new functionality and data types:

    Do you have an anonymization, visualization or data input need we don't support or have in our roadmap? We'd love to hear about it! Please let us know.

    Frequently Asked Questions (FAQ)

    Support

    Feature Request

    Your request might already be covered in our future releases which we might be able to offer ahead of schedule as a beta API. Interested to learn more? Feel free to reach out.

    Need a feature or integration that is not currently supported? We'd love to hear more (and we might already be working on it!). Reach out so we can hear more and let you know about availability of new features.

    Bug Reporting

    Found a bug? Let us know!

    Please include a way we can reach you via email as well as a short and long description. Do not include your API tokens or key information, but feel free to pass along any other information you can to help us reproduce the error. Thank you again for taking the time to report the issue.

    Please fill out the form below. An email address is required.

    Contact Email:

    Title (short summary):

    Full Description:

    Errors

    Errors encountered in the processing of the API request will be sent directly back to the user. The format will be sent in JSON with a message detailing the error encountered when processing.

    To note, we are actively working on a feature to better surface errors of individual fields while still allowing the non-affected transformations to be properly returned. If this is a requirement for your use of our API, please let us know.