HTTP API

The Calq API server can be called directly over HTTP(s) if required. However, we would normally recommend using one our existing API clients where most of the heavy lifting has been done for you. We are also able to offer better support if you are using one of our client libraries.

If you are using a platform that is not on our list then you can still send data to Calq using HTTP(s).

We are always looking to support more platforms. Are you planning on writing a client library for a popular platform we don't yet support? You could earn up to $1,000 in credit if you share it with us! Contact us to check if your platform is eligible.

HTTP endpoints

Calq supports both HTTP and HTTPS. All calls should be made to the API servers at http://api.calq.io/. The URL specifies the API endpoint you are calling. For example, to call the track endpoint you would make a request to http://api.calq.io/track.

All our API calls take a JSON payload containing the data required for the call (action data, profile data etc). You can pass this data to us in 3 ways.

HTTP POST with JSON body

To send a JSON payload directly use POST and specify a content type of application/json.

POST /track HTTP/1.1
Host: api.calq.io
Content-Type: application/json; charset=utf-8
Content-Length: 58

{"action_name":"Login","actor":"1","write_key":"test1234"}
HTTP POST form encoded

The JSON payload can be passed as the data parameter using URL form encoding.

POST /track HTTP/1.1
Host: api.calq.io
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 104

data=%7B%22action_name%22%3A%22Login%22%2C%22actor%22%3A%221%22%2C%20%22write_key%22%3A%22test1234%22%7D
HTTP GET URL & Base64 encoded

The JSON payload can be passed as the data GET parameter (query string). The JSON data must be Base64 encoded before being passed.

GET /track?data=eyJhY3Rpb25fbmFtZSI6IkxvZ2luIiwiYWN0b3IiOiIxIiwgIndyaXRlX2tleSI6InRlc3QxMjM0In0= HTTP/1.1
Host: api.calq.io

All methods support Base64 encoding the JSON payload, although it is only required for HTTP GET.

If your request is successful the API server will return a HTTP status code of 200 and a JSON response of {"status":"accepted"}.

If an error occurs the API server will return a HTTP error status (such as 400, 404, 500 depending on the error) and a JSON response providing more information. For example, an invalid write key would give a status code of 400, and a JSON response similar to {"status":"rejected","error":"The write_key \"test1234\" did not match any known keys."}.

Tracking actions

Calq performs analytics based on actions that user's take. You can track an action using the track endpoint (http://api.calq.io/track). Specify the action and any associated data you wish to record in your JSON payload.

{
    "actor": "1495",
    "action_name": "Product Review",
    "properties": {
        "Rating": 9.0
    },
    "write_key": "test1234"
}

JSON payload properties

actor string Required

The unique Id of the actor (user) performing this action. Normally this is a user Id generated by your application.

action_name string Required

The name of the action being tracked. This will be shown in the reporting interface.

properties object Required

A JSON object describing any additional custom data you want to send with this action. This is the data that you will analyze within Calq. This property is required but can be empty { }.

write_key string Required

The write key for the project to save data for. This is found within the Calq reporting interface.

ip_address string Optional

The IP address of the actor performing this action. This is useful if a server is making a request on behalf of a client. By default the IP address of the calling client will be used unless this is specified. To specify an unknown address use the string literal "none". The IP address is used to automatically populate geographical information for the calling client (though these properties can be specified manually in the properties node instead).

timestamp string Optional

UTC date & time that this action occurred. Dates can be up to 2 days in the past. This is useful for handling offline clients & connection errors, and for queuing events into batches. If no timestamp is specified then the time is taken from the request. Most sane time formats will be accepted, but if you want something explicit then use yyyy-MM-dd HH:mm:ss.SSSZ.

utc_now string Optional

UTC date & time that represents "now" on the client. This can optionally be used if also sending the timestamp property on a device which might not have an accurate clock (quite common on mobile devices). Calq will look at the difference between the submitted time and Calq's synchronised time and adjust the inbound timestamp property accordingly.

Action properties

When specifying custom data under the properties node there are some special properties that you can use. These properties allow you to use additional functionality in Calq reports.

$sale_value The amount of any sale. Marks this action as containing revenue. Must be specified if $sale_currency is also present.
$sale_currency The 3 letter currency code for any sale. Must be specified if $sale_value is also present.
$device_agent The user agent of the browser being used, or information on the device being used.
$device_os The operating system running on the device (Windows, OSX, iOS, Android etc).
$device_resolution The screen size of the device being used.
$device_mobile Whether the device is a mobile device such as a phone or tablet.
$country The user's current country (Taken from IP address if not specified manually).
$region The user's region within their country (Taken from IP address if not specified manually).
$city The user's city (Taken from IP address if not specified manually, though accuracy at city level is varied).
$gender The gender of the user (as either the string "male" or "female").
$age The age of the user. Must be an integer.
$utm_campaign The campaign name that was used to aquire this user (utm_campaign).
$utm_source The source that was used to aquire this user (utm_source).
$utm_medium The type of marketting medium that was used to aquire this user (utm_medium).
$utm_content The content source that was used to aquire this user (utm_content).
$utm_term The keywords used to aquire this user (utm_term).
$is_view Flags that this is a view (a page, or screen that contians other actions).
$is_within_view Flag whether this action occured within a view (the last set view).
$view_url The URL of this view if it's a page.
$view_name The name of this view (e.g. page title, or app screen name).

Your own properties should not start with a $. Unknown special properties will be rejected with an API error.

A JSON payload to describe a sale using the $sale_value and $sale_currency properties might look like:

{
    "actor": "1495",
    "action_name": "Product Purchase",
    "properties": {
        "Product Id": 1203
        "$sale_value": 49.99
        "$sale_currency": "USD",
    },
    "write_key": "test1234"
}

Batching actions

The track endpoint is unique amog Calq API calls in that it allows batching. Up to 100 actions can be sent in a single API call. This allows server side applications to make a reduced number of outgoing HTTP requests if desried. Batched actions should only send data using HTTP POST.

To batch actions together the actions are simply passed as an array in the format [ {action1}, {action2}, ..., {actionN} ]

.

If one action in a batch fails due to a syntax or other error then the entire batch will be rejected.

[
    {
        "actor": "1495",
        "action_name": "Product Review",
        "properties": {
            "Rating": 9.0
        },
        "write_key": "test1234"
    },
    {
        "actor": "1895",
        "action_name": "Product Review",
        "properties": {
            "Rating": 4.0
        },
        "write_key": "test1234"
    },
]

The write_key property should be specified for individual each action (even if the keys are the same). This allows servers to batch data for different Calq projects into the same API call if required.

User information

In addition to sending data about actions, you can also send properties about users themselves. This allows you to analyze your audience based on who they are, rather than what they did. You can set user properties using the profile endpoint (http://api.calq.io/profile).

{
    "actor": "1495",
    "properties": {
        "$email": "super_customer1@notarealemail.com"
    },
    "write_key": "test1234"
}

JSON payload properties

actor string Required

The unique Id of the actor (user) you wish to save profile data for. Normally this is a user Id generated by your application.

properties object Required

A JSON object describing the data you want to associate with this user. This project can not be empty.

write_key string Required

The write key for the project to save data for. This is found within the Calq reporting interface.

User properties

There are special properties for user profiles that start with a $ symbol. These enable additional functionality within Calq.

$full_name The full name of this user.
$image_url URL to an image to display in Calq's UI when examining this user. Use a square image for best results.
$country The user's current country.
$region The user's region within their country.
$city The user's city.
$gender The gender of the user (as either the string "male" or "female").
$age The age of the user. Must be an integer.
$email The email address used to contact this user
$phone A phone number contact this user
$sms A mobile number that can be used to deliver SMS messages to this user.
$utm_campaign The campaign name that was used to aquire this user (utm_campaign).
$utm_source The source that was used to aquire this user (utm_source).
$utm_medium The type of marketting medium that was used to aquire this user (utm_medium).
$utm_content The content source that was used to aquire this user (utm_content).
$utm_term The keywords used to aquire this user (utm_term).

Your own properties should not start with a $. Unknown special properties will be rejected with an API error.

User identity

Under some circumstances you may wish to associate user actions with a new Id. This typically happens when a user registers with your site and they were previously using an anonymous Id. Often you will want to use a known Id from your database or other source for future actions.

If a user has performed some actions and you then swap to sending a different Id, then the previous actions are not correctly associated. This would result in some reports being inaccurate (Funnels, LTV etc). By way of example: User "anon1" does actions A, and B, then registers and is given a new Id from your database of "7". The user then performs action C. Calq will see one user has performed action A and B, and a different user has performed action C.

To combat this scenario Calq has an API endpoint called transfer (http://api.calq.io/transfer). You can use this API call to associate the former actions with the new Id. Calling transfer will look back at up to 14 days of actions and link those actions to the new Id.

Once you have called transfer on a user you must not call it again for the same Id.

Calling transfer only attributes previous actions. It does not associate profile data (and nor should it - you should always call the profile endpoint with your known Id).

{
    "old_actor": "1495",
    "new_actor": "mydb_12324",
    "write_key": "test1234"
}
old_actor string Required

The old unique Id of the actor (user).

new_actor string Required

The new unique Id to associate actions with. All further actions you send Calq should use this Id instead of the former.

write_key string Required

The write key for the project to save data for. This is found within the Calq reporting interface.

Platform limits

Calq has certain limits which you should factor in when modelling your actions. These limits can not be increased.

Action names
  • Maximum of 112 characters. Will be truncated if this is exceeded.
  • Names should not start with a $ symbol.
Action properties
  • Maximum of 50 registered properties per action type.
  • Maximum property name of 224 characters. Calq will reject actions with an error if this is exceeded.
  • Maximum property length of 256 bytes (factor in UTF8 size). Will be truncated if this is exceeded.
  • Property name must not start with a $ unless it's a special reserved property.
General properties
  • Maximum actor name of 128 bytes (factor in UTF8 size). Will be truncated if this is exceeded.
  • Maximum $device_agent of 1024 bytes. Will be truncated if this is exceeded.
  • All $utm_ paramters have a max size of 128 bytes, except for $utm_content which has 256. Will be truncated if this is exceeded.