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

https://app.cooladata.com/api/v2/projects/[project_id]/cql

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

 

Header

Authorization:Token [User_API_Token]
ContentType:application/x-www-form-urlencoded //optional

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:

TIMESTAMP

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

tq=[query]
&noCache=true //optional
&tqx=out:csv //optional

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

Optional Parameters:

noCache=true

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.

tqx=out:csv

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.

curl -H "Authorization:Token n8rwaqp6zj62yya3yj3pvysy7h9gvzn8" https://app.cooladata.com/api/v2/projects/123456/cql/?tq=select%20event_name,%20event_time_ts%20from%20cooladata%20where%20date_range(last%207%20days)%20limit%2010&noCache=true&tqx=out:csv

Method: POST

curl 
  -X POST
  -H "Authorization:Token n8rwaqp6zj62yya3yj3pvysy7h9gvzn8"
  -H "ContentType: application/urlencode"
  -H "TIMESTAMP"
  -d "noCache=true" \\optional
  -d "tqx=out:csv" \\optional
  -d "TQ=select event_name, event_time_ts from cooladata where date_range(last 7 days) limit 10"
  https://app.cooladata.com/api/v2/projects/123456/cql/

 

Response

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

{version,status,Number of rows,Processed bytes,Total query time,sig,table{cols,rows}}

Note: The query API result set is limited to 5M rows.

Sample Response:

{
	"version": "0.6",
	"status": "ok",
	"Number of rows": "15",
	"Processed bytes": "2952",
	"Total query time": "2129",
	"sig": "1880384400",
	"table": {
		"cols": [
			{
				"id": "0",
				"label": "date",
				"type": "string",
				"pattern": ""
			}
		],
		"rows": [
			{
				"c": [{"v": "2013-05-01"}]
			}
			,...
		]
	}
}
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

https://app.cooladata.com/api/v2/projects/{projectId}/users/delete

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

Header

ContentType:application/json
Authorization:Token [User_API_Token]

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

{ "reason":"<reason for deletion>",
 "userIds":
[<an array of comma separated customer user ids for deletion>]
 }
 

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

https://app.cooladata.com/api/v2/projects/{projectId}/users/delete/status

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

Header

ContentType:application/json
Authorization:Token [User_API_Token]

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

[an array of comma separated customer user_ids ] 

Response

{
 "<user_id1>": [
 {
 "status": "<status of request>",
 "deletedEvents": <number of deleted events>,
 "deletedSessions": <number of deleted sessions>,
 "statusUpdateDate": <timestamp of last update in msec>
 }
 ],
"<user id2>": [
{
"status": "<status of request>",
"deletedEvents": <number of deleted events>,
"deletedSessions": <number of deleted sessions>,
"statusUpdateDate": <timestamp of last update in msec>
}
]
}
 

 

Print Friendly, PDF & Email

User Identities Matching API

CoolaData provides an API that can be used  to match between 2 identities of the same user without having to send an event. The API matches between a user_id and that user’s user_alternative_id.

Once an event is sent with a user_id and user_alternative_id together or and API request for matching is sent, Cooladata will associate all events from this registered user, based on user_alternative_id, to the pre-registered user, based on user_id. Read more about handling multiple user identities here.

The API is called using customer_user_id (the actual user id sent in events, not the internal_user_id Cooladata allocated per user). The API will work only for existing users that sent events in the past. Notice that since Cooladata deletes users after a period of inactivity, the user updated might not exist in Cooladata records if the period has past. For more information about the period Cooladata keeps users for please contact support@cooladata.com or contact your CSM directly.

API End Point

https://app.cooladata.com/api/v2/projects/{projectId}/users/identities

Replace the [project_id] placeholder with your actual Project ID found in the project settings.

 

Method

POST

Header

ContentType:application/json
Authorization:Token [User_API_Token]

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.

Payload

Sample Payload

 

Response

  • Success: 200 ok + number of users updated
  • Failure: 400 bad request
    •  No customer user id <id> for project <project id> – this means the user_id you requested to update does not exist (never sent events) or was deleted since the period of user inactivity defined in your project has past.
    • Operation requires admin permissions on project <project id> – this means you are using a non-admin authorization token.
Print Friendly, PDF & Email

Discovery API

The discovery API offers a RESTful API for discovering CoolaData’s metadata. Developers can use this API to check which of the platform’s resources are available and get details about those resources (JSON):

Setup for all APIs

Endpoint
All APIs use the same URI:

https://app.cooladata.com/api/v3

Header
All APIs require the following authentication to be included in the request header. Replace [User_API_Token] with the user API token found in the user profile side-bar:

Authorization: Token {User_API_Token}

Method: GET
All the APIs use the method GET.

 

Projects

Returns a list of all the projects the user has permissions for.
Full URI:

https://app.cooladata.com/api/v3/projects

Response:

[
  {
    "id": [project_id],
    "name": [project_name],
    "token": [project_token]
  },
  ...
]

 

Example

Query:

https://app.cooladata.com/api/v3/projects
Authorization: Token IrdY70oSJL3pbsidnQyJTRaclLmg75DGVFIUfpFL

Response:

[
  {
    "id": 123456,
    "name": "My First Project",
    "token": "qh9d70mh9aa4xol6ondekeff4dhq2w0u"
  }
]

 

Events

Returns a list of all the events in the project and their corresponding category. See the overview section for more information on events and properties.

Full URI:

https://app.cooladata.com/api/v3/projects/{project_id}/events

Replace {project_id} with the ID of the specific project.

Response:

[{
   "name": "event_name",
   "category": "event_category"
},
...
]

 

Example

Query:

https://app.cooladata.com/api/v3/projects/123456/events
Authorization: Token IrdY70oSJL3pbsidnQyJTRaclLmg75DGVFIUfpFL

Response:

[{
    "name": "signup",
    "category": "onboarding"
},
...
]

 

Properties (Data Columns)

Returns a list of all the properties in the project and their corresponding details. See the overview section for more information on events and properties.

Full URI:

https://app.cooladata.com/api/v3/projects/{project_id}/cql/columns

Replace {project_id} with the ID of the specific project.

Response:

The following fields are returned in the response:

[{
    "created": [epoch timestamp in miliseconds],
    "modified": [epoch timestamp in miliseconds],
    "id": 123456,
    "source": "[string]",
    "name": "[string]",
    "scope": "[string]",
    "configJson": "{}",
    "candidate": [boolean],
    "lookupsCupSize": [integer],
    "data_type": "[string]",
    "virtual": [boolean],
    "classifications": ["string",...],
    "refreshing": [boolean]
},
...
]

 

Example

Query:

https://app.cooladata.com/api/v3/projects/123456/cql/columns
Authorization: Token IrdY70oSJL3pbsidnQyJTRaclLmg75DGVFIUfpFL

Response:

[{
    "created": 1425385386000,
    "modified": 1425385386000,
    "id": 124018,
    "source": "session_os",
    "name": "device_os",
    "scope": "SESSION",
    "configJson": "{}",
    "candidate": false,
    "lookupsCupSize": 300,
    "data_type": "STRING",
    "virtual": false,
    "classifications": ["DIMENSION"],
    "refreshing": false
},
...
]

 

Lookup

Returns a list of all the values in the property’s (column’s) auto-complete list.
Full URI:

https://app.cooladata.com/api/v3/projects/{project_id}/{column_id}/lookup

Replace {project_id} with the ID of the specific project and [column_id] with the ID of the specific property (column) from the property discovery API.
Response:

{
  "lookupsValuesAlphabetical": [
    "[string]",
    ...
  ]
}

 

Example

Query:

https://app.cooladata.com/api/v3/projects/123456/654321/lookup
Authorization: Token IrdY70oSJL3pbsidnQyJTRaclLmg75DGVFIUfpFL

Response:

{
  "lookupsValuesAlphabetical": [
    "Antalya",
    "Barcelona",
    "Dubai",
    "Guangzhou",
    "Kuala Lumpur",
    "London"
    "Miami",
    "New York",
    "Taipei"
  ]
}

 

Views

Returns a list of all the tables the user can query in the project.
Full URI:

https://app.cooladata.com/api/v3/projects/{project_id}/views

Replace {project_id} with the ID of the specific project.
Response:

Currently the response only includes CoolaData’s default database (does not include Aggregation Tables and external data sources).

[
  {
    "name": "[project_name]"
  },
  ...
]

 

Example

Query:

https://app.cooladata.com/api/v3/projects/123456/views
Authorization: Token IrdY70oSJL3pbsidnQyJTRaclLmg75DGVFIUfpFL

Response:

[{
    "name": "CoolaData"
   }
]

 

Linked Data Sources

Returns a list of all the external data sources linked to the project.
Full URI:

https://app.cooladata.com/api/v3/projects/{project_id}/linked_data_sources

Replace {project_id} with the ID of the specific project.
Response:

[{
    "id": ,
    "name": "",
    "type": "",
    "connection": ,
    "description": "",
    "properties": ,
    "googleBucket": "",
    "googleProjectName": "",
    "googleDataSet": ""
}, ...
]

Example

Query:

https://app.cooladata.com/api/v3/projects/123456/linked_data_sources
Authorization: Token IrdY70oSJL3pbsidnQyJTRaclLmg75DGVFIUfpFL

Response:

The following example response includes an example of each type of data sources currently available. The actual response will only include the data sources set up in the project.

[{
    "id": 1,
    "name": "MySQL",
    "type": "MYSQL",
    "connection": null,
    "description": "example external MySQL",
    "properties": null,
    "googleBucket": "",
    "googleProjectName": "",
    "googleDataSet": ""
}, {
    "id": 2,
    "name": "MsSQL",
    "type": "SQL_SERVER",
    "connection": "jdbc:sqlserver://URL;DatabaseName=DATABASE_NAME;user=USER_NAME;password=PASSWORD",
    "description": "null",
    "properties": null,
    "googleBucket": "",
    "googleProjectName": "",
    "googleDataSet": ""
}, {
    "id": 3,
    "name": "RedShift",
    "type": "REDSHIFT",
    "connection": "username:password@host:port/database",
    "description": "null",
    "properties": null,
    "googleBucket": "",
    "googleProjectName": "",
    "googleDataSet": ""
}, {
    "id": 4,
    "name": "BigQuery",
    "type": "EXTERNAL_BIG_QUERY",
    "connection": "",
    "description": "",
    "properties": null,
    "googleBucket": null,
    "googleProjectName": "example_project",
    "googleDataSet": "example_dataset"
}, {
    "id": 5,
    "name": "GoogleBucket",
    "type": "GOOGLE_BUCKET",
    "connection": "",
    "description": "",
    "properties": null,
    "googleBucket": "project-bucketId",
    "googleProjectName": "",
    "googleDataSet": ""
}]

Tables

Returns a list of all data tables per specific external data source:

https://app.cooladata.com/api/v3/projects/{project_id}/{dataSourceId}/sys_tables

Data Columns

Returns a list of all data columns per specific external data source table:

https://app.cooladata.com/api/v3/projects/{project_id}/{dataSourceId}/{tableName}/sys_columns
Print Friendly, PDF & Email