APIs Overview

This section describes the application programming interfaces (APIs) that are available for the CoolaData platform. The APIs enable customers to directly access the CoolaData platform (for example, using CoolaSQL (CQL) querying) directly or via 3rd party tools.
The REST-like API, which allows you to use and extend CoolaData’s Platform, provides access to CoolaData Discovery and Query capabilities. The CoolaData REST APIs are a set of URI resources, which grant access to data views.
CoolaData’s URI resources provide access for discovering metadata and executing queries.
The URI resources are now presented in the order of a typical API workflow:
  • Discovery API: This refers to the API that exposes information about the metadata.
  • Query API: The Query API enables you to query a data source using the CoolaData platform.
  • Delete API: Allows you to request to delete a specific user’s historical events and sessions from Cooladata.
  • User Update API: Enables updating user scope property values for specific users without having to send events.
  • User Identitities Matching API: Enables coupling between a registered user ID and an anonymous user ID without having to send events.

 Authorization

All of Cooladata’s API’s require Authorization Tokens.
Each Cooladata user has each own authorization token for carrying out API requests. Your Authorization Token can be found in the Cooladata App by clicking on the user icon in the top right hand side of the application:
Print Friendly, PDF & Email

Query API

CoolaData provides a query API that can be used  to query your project at any time. This enable you to create your own dashboards or easily integrate data from CoolaData with other tools.

Queries can be sent using GET or POST methods.

 

End Point

Replace the [project_id] placeholder with your actual Project ID.

 

Header

Replace the [User_API_Token] placeholder with your actual user API Token found in the user profile side-bar.

ContentType: application/x-www-form-urlencoded: Only relevant for method:post. This parameter can also be omitted if the content is already URL encoded. Other content types are not supported.

Optional Headers:

The default format for time-stamp properties returned in the query API is: yyyy-mm-dd hh:mm:ss. Add this header (without content) to the query to get time-stamp properties in the format in which they were sent. For example, event_time_ts will be returned in Epoch time in milliseconds.

Data/Payload

Replace the [query] placeholder with your actual query. The query should be written in CoolaSQL (CQL).

Optional Parameters:

Add to the query to force the system to ignore cache. All query results are cached for 30 minutes to provide fast response time. After 30 minutes it will be refreshed, regardless of how many queries were made during this time. Using noCache will only make a difference if the same query was first performed in the last 30 minutes, and data has been altered since. This isn’t mandatory in the API.

The default output of the query API is JSON. Add this to the query to get an output in the form of CSV instead.

 

Sample Invocations

The following queries includes both optional parameters for reference purpose – neither is mandatory.

Method: GET

The query should be URL encoded.

Method: POST

 

Response

The default output of the query API is JSON, in the following format:

Note: The query API result set is limited to 250k rows.

Sample Response:

Print Friendly, PDF & Email

Delete API

*Please note that this documentation is for a BETA feature. Please contact support@cooladata.com or your CSM for more information.

The Delete API will allow you to delete any user properties or historical events and sessions of a user.
Keep in mind that if you do not opt-out the user and send any events for that user in the future, the data will be stored. In addition, since Cooladata does not control your Aggregation Tables, external data sources or data uploaded through our integrations, it is your responsibility to delete that user from these external tables.

The delete API will be carried out using customer_user_id (the original user_id sent from the event JSON, not the internal user_id Cooladata allocates per user). Since Cooladata allows you to link between multiple identities of the same user, the Delete API will also delete all the alternative identities of a single user, and their records, and not just the ones received with the user id that asked for the erasure.

The Delete API will queue the user requested for deletion and the Delete Status API will  let you know the status of request for deletion (whether it’s in progress or done).

Also, since every query in Cooladata is calculated based on raw event-level data, once these tasks are completed, the data retrieved from queries on top of Cooladata will change and will not include these events and sessions, even when querying aggregated values.

Notice – This action cannot be reversed, please use it wisely!

Delete API

Method

POST

API End Point

Replace the [project_id] placeholder with your actual Project ID.

Header

Replace the [User_API_Token] placeholder with your actual user API Token found when clicking on your user in the application. The request will be permitted only for ADMIN user permissions.

Data/Payload

Response

The expected response is 200 OK (no body). If there was an error the body will include the reason for failure.

Sample Request:

[POST]:https://app.cooladata.com/api/v2/projects/113231/users/delete
headers:
Content-Type: application/json
Authorization: 07J2FBteX4dfgdfg431yWbO9jghkdfjg45YgfjlkoH3dCPmj
body:
{ “reason”:”testing delete api”, “userIds”:[“0e00e01b-2691-489c-93ac-74567d9e”,”4ad45365-7351-4c64-8605-25413dc216c7″,”b24f0b61-d6ce-427f-56g0-c41144504456″]}

response you should get if all is ok is 200 OK

 

Delete Status API

You can check the status of the delete request with the delete status API:

Method

POST

API End Point

Replace the [project_id] placeholder with your actual Project ID.

Header

Replace the [User_API_Token] placeholder with your actual user API Token found when clicking on your user in the application. The request will be permitted only for ADMIN user permissions. 

 

Data/Payload

Response

 

Print Friendly, PDF & Email

Sending Data

Is there any size limit for each event I send?

Event size should not exceed 100KB.

I’ve noticed events on ‘Live Events’ view but cannot see them when I query.

There are two reasons that this is likely to happen:

  1. The events haven’t been loaded to the data warehouse yet (Google BigQuery), and thus cannot be queried. In this case, wait for about an hour until the data loading is completed
  2. Some of the events’ properties were not sent in the correct format (either wrong type, missing etc.) and were consequently sent as invalids. You can query all invalids up to the previous 7 days, using the following query:

Why am I getting the following error, when I am sure this property exists in my project: “Field ‘session_duration’ not found in project, Coolalog no:5522517”?

This error occurs when trying to pull data from two different partitioned tables: events table, and session table. To solve it, join both tables using mutual property appears in both, e.g. user_id.
For instance, the following query will produce this error as event_name is a user scope property (saved in events tables), whilst session_duration is a session property (saved in sessions tables):

Does Cooladata support multiple customer identities?

A user can start as anonymous user (hash key generated automatically), and then become a registered user. We support one old identity per user.
Once the user is sending both identities within the same event, we know how to convert it to the new identity.

Is session_id mandatory?

No

Which columns are automatically generated?

based on session_ip we are generating ip_country, ip_region, ip_city, ip_longtitue, ip_latitude.
based on DUA (device user agent) we are generating brand and model.
based on timestamp, we are generating multiple columns (hour, day, month, year, week…)

Is the API Token the same as the App Key for using SDK implementation?

The AppKey is used to send events. It is the same regardless of how you send the events (REST, JavaScript etc.). However, the Query API is your user token and is used for querying the system. This can be retrieved by logging into Cooladata and clicking on the avatar in the top right-hand side of the screen.

How can I differentiate test data and organic data sent from my users?

There are several ways of differentiating between test data and real data:
A different project
A property
Both above methods require code intervention (in your app) to distinguish between real and test data.
In addition, if you have a distinct (and not too large) set of either devices or users that are generating test data, you can build segments that reflect those “test users”/”test devices” and filter them out in the dashboard slicers.

Handling Personally Identifiable Information (PII)

Cooladata takes the utmost precautions to ensure the security of your data in the cloud and continually upgrades with the latest security options.

Cooladata accepts any event properties that you send without filtering them. However, even so, we advise you not to send sensitive personal information (such as credit card numbers) that may help a malicious entity identify someone.

Here are a few tips for protecting personal information:

  • Conceal personally identifiable information. For example, by scrambling, cloaking, encrypting, faking or hashing it.
  • Send a person’s location, instead of their IP address.
  • Send only partial information, such as a person’s country instead of their IP address.
  • Do not send combinations of information that may help someone piece together who the person is, such as session IP, address, gender and age.
Print Friendly, PDF & Email

Common reasons for data discrepancies

Companies often use several tools to understand their user’s behaviour. Alongside Cooladata, most companies also use Google Analytics or their own DB for comparison. 

We suggest investigating discrepancies if there is more than a 5% difference between Cooladata and other tools. Any less is likely not material enough to warrant a full tracking audit, since often analytics are used to identify trends (e.g. how fast are we growing?), rather than exact numbers. If the difference is greater than 5% across all events, or specific events don’t match between systems, then further investigation is called for.

Check this guide to identify common reasons for data discrepancies between various systems:

Timezone

Cooladata’s default timezone is UTC. When comparing data between Cooladata and other system such as Google Analytics, consider the time zone differences.

Double-check your query

When weird numbers appear in a report, it’s not always a data issue. Sometimes the report is just not querying what we intend it to query. Make sure you are querying the correct date range, and no filters are applied, filtering out relevant data.

Invalids

Cooladata automatically validates the data sent to Cooladata in order to prevent Garbage In – Garbage Out situations. Events marked as invalid are not stored with the rest of the valid events, but in a separate, designated table for invalid events, which you can query to check what went wrong. See Handling Invalid Events to learn more.

Data Sampling

Google Analytics sometimes use sampled data in reports, causing discrepancies in the numbers from Cooladata. Google Analytics sampling occurs automatically when more than 500K sessions are collected for a report. Google Analytics state that a report is based on sampling in text above the report. When comparing Cooladata to a sampled Google Analytics report, discrepancies are expectable.

Session Definition

A session in Cooladata starts when someone visits your site or app, sending an event, and ends after thirty minutes of inactivity. The session duration is calculated as the difference between the first and last event in that session. This thirty minutes timeframe is a configurable parameter. If you are the project’s admin, you can see this parameter under ‘Session timeout“ in your project settings page. Most analytics tools, such as Google Analytics use this thirty minute definition, which might cause discrepancies when comparing session duration or number of sessions if you set this parameter to be different than thirty minutes in Cooladata. Also, consider that Google Analytics will count additional sessions for clicks on AdWords campaigns, and will hard stop all sessions at midnight, whereas in Cooladata sessions occurring across midnight (starting before midnight and ending afterwards) would be stored as one session. Other mobile analytics tools platforms also end sessions if the user moved the app to the background for more than a minute.

Events are sent differently

A common cause for discrepancy is the way the events are sent to Cooladata and other tools. For instance, if one tool is receiving events from the server-side and the other from the client side, differences in numbers will most likely occur.

Even if both tools are sent from the client side, the code needs to be checked. Sometimes, there is a logical condition for sending an event to one tool which is not the same as the code sending the event to the other tool. When using JS SDK, the location of the trackEvent code is important. If the call sending the event to one tool is at the top of the code and the call sending the event to another tool is at the bottom of the code, there might be some discrepancies, due to an error in the code or if the user manually closed the window before the trackEvent function was called.

Bots and Test Users

Some tools automatically filter out events created by bots, Cooladata does not. Cooladata does have several solutions available if you wish to slice out bad IP’s or bots. To find the best solution for you, contact your Customer Support Manager.   

If your operational DB automatically cleans test user’s activity, make sure you filter out test users in Cooladata as well.

Funnel and Conversion Definitions

Funnels in Cooladata count distinct (unique) users who completed the funnel in the date range in question, in the time window set in the report. Conversions are sometimes defined differently in other tools. For instance, Google Analytics count the number of sessions in which the funnel’s steps were completed.  

Notice that if you choose to set the funnel in Cooladata to show users who completed the funnel by X days, the funnel will only include users who did the first event X days before the end of the report date range when looking at the last week or month. This is done in order to give users who came in at the beginning of the date range, the same “chance” to complete the funnel as users who came in at the end of the date range.

Redirects and Self Referrals

When looking at Cooladata’s “referring_url” and “reffering_domain” you should see the url and domain the user was referred from. Sometimes, you see url’s and domain’s that you do not expect, such as your own url. This happens when your site uses redirecting rules, usually set up by your site admin.

Cooladata Sessions Table

Cooladata stores your data in two separate tables: one is your event table, in which every row is an event, and the other is your sessions table, in which every row is a session. The event table holds all the event-level data and event-scope properties, as well as user and session scope properties. The sessions table holds session-specific properties (such as session duration and the session path) as well as session and user scope properties. In order to optimize performance, Cooladata automatically shifts your queries to run on top of the sessions table if all the data you are searching for is there. For instance, Daily Active Users (DAU), counting number of unique users per day will run over the sessions table, but if you want to count Daily Active Payers (pDAU), you will have to run over the events table in order to add a filter for the payment event. Shifting between the sessions and events table might cause for slight differences due to the fact that when running over the sessions table, the date range is filtered according to the session start time (session_start_time_ts) whereas when running over the events table the date range is filtered according to the event (event_time_ts)  timestamp.

Print Friendly, PDF & Email