Server API Reference

Last modified: December 15, 2023 09:52

This document describes the API functionality provided with the Countly Server. Both read (/o) and write (/i) requests are available through the Countly Server API.

Full API List

For a complete API list, review the Countly API documentation page.

Write API

The first API call when a user opens your application:

http://your_domain/i?
    app_key=AAA &
    device_id=BBB &
    sdk_version=CCC &
    begin_session=1 &
    metrics= {
        "_os": "DDD",
        "_os_version": "EEE",
        "_device": "FFF",
        "_resolution": "GGG",
        "_carrier": "HHH",
        "_app_version": "III"
    }

The second API call and rest that ensue are the same as below. The same call is repeated every 60 seconds, extending a user's current session duration:

http://your_domain/i?
    app_key=AAA &
    device_id=BBB &
    session_duration=30

The final API call, ending that user's session:

http://your_domain/i?
    app_key=AAA &
    device_id=BBB &
    end_session=1

Of course, each request is URL-encoded and does not have any of the spaces or new lines shown in the examples above:

http://your_domain/i?app_key=AAA&device_id=BBB&sdk_version=CCC&begin_session=1&metrics=%7B%22_os%22%3A%22DDD%22%2C%22_os_version%22%3A%22EEE%22%2C%22_device%22%3A%22FFF%22%2C%22_resolution%22%3A%22GGG%22%2C%22_carrier%22%3A%22HHH%22%7D

Parameters

Mandatory Parameters

The parameters listed below are mandatory for every write API request.

app_key: Application key for the current application. May be obtained from your dashboard after creating your application.
device_id: Unique ID for the user device.

Optional Parameters

begin_session: Indicates the start of the user session. begin_session should be used with the API call you make at the beginning of a user's session. begin_session should be given the value of 1. The sdk_version parameter needs to be present in the request if begin_session is used.
end_session: Indicates the end of the user session. end_session should be used with the API call you make at the end of a user's session. end_session should be given the value of 1.
metrics: JSON object containing the key, value pairs, and metrics can only be sent together with the begin_session. Currently, the predefined metrics below are valid:
```
metrics={
    "_os": "DDD",
    "_os_version": "EEE",
    "_device": "FFF",
    "_resolution": "GGG",
    "_carrier": "HHH",
    "_app_version": "III"
}
```
session_duration: Heartbeat-like parameter that extends a user’s session duration for the session_duration of seconds.
timestamp: 10-digit UTC timestamp for recording past data.
ip_address: IP address of the user. A user’s IP address is detected from the connection by default. However, you may send it manually using this parameter. The ip_address parameter may only be used with the begin_session request.

events: JSON array containing event objects. Each event object may contain the properties listed below:

- key (Mandatory, String)
- count (Mandatory, Integer)
- sum (Optional, Double)
- segmentation (Optional, Dictionary Object)

A sample API call to the server will appear as follows:

http://your_domain/i?
    app_key=AAA &
    device_id=BBB &
    events= [
        {
            "key": "level_success",
            "count": 4
        },
        {
            "key": "level_fail",
            "count": 2
        },
        {
            "key": "in_app_purchase",
            "count": 3,
            "sum": 2.97,
            "segmentation": {
                "app_version": "1.0",
                "country": "Germany"
            }
        }
    ]

After this request, we will be able to perform the following:

See how many times a user successfully completed or failed a level.
See how many times in-app purchases were made and the total amount of these IAPs.
Segment IAP data into two levels, one being the app_version and the other being the country. We will be able to identify which application version performed best in terms of IAP and which countries tend to make more IAPs.

Read API

There are two API versions for read requests:

v1

The Countly Dashboard uses v1 API in order to fetch data for your dashboard. This version of the read API returns data in an almost raw format that needs to be processed in order to be meaningful. The Countly JavaScript libraries may be used for this purpose.

http://your_domain/o?
    api_key=AAA &
    app_id=BBB &
    method=CCC &

Parameters

Mandatory Parameters

The parameters listed below are mandatory for every read API request.

api_key: Your account’s API Key, which may be obtained from your account Management menu.
app_id: Your application’s Application ID, which may be obtained from your Countly dashboard, once your application has been created.
method: Defines which data should be fetched. This may take one of the sessions, users, locations, carriers, devices, device_details, app_versions, events, get_events, live, live_graph, or retention values.

For example, the read request fetches all location-related data for the application below:
```
http://your_domain/o?
    api_key=AAA &
    app_id=BBB &
    method=locations &Preview
```
Note: live, live_graph and retention methods are only available with Countly Enterprise Edition.

Optional Parameters

callback: Callback function name. When specified, the results will be sent as a parameter to this function (JSONP).
event: This parameter is used only if method=events is available inside the request. Such as:
```
http://your_domain/o?
    api_key=AAA &
    app_id=BBB &
    method=events &
    event=in_app_purchase
```
Used in order to specify which event data will be fetched and returned. Use the following if this parameter is missing from the request:
```
http://your_domain/o?
    api_key=AAA &
    app_id=BBB &
    method=events
```
The first event from the event list will automatically be selected by the API and the data for that event will be returned.
action: Can only take refresh value for now. If the read request contains an action=refresh parameter, only the data for the current day will be returned.
```
http://your_domain/o?
    api_key=AAA &
    app_id=BBB &
    method=locations &
    action=refresh
```

v2

The v2 version of the API is designed to return ready-to-use metrics for today, the last 7 days, and the last 30 days. There are two available paths:

/o/analytics/dashboard

    http://your_domain/o/analytics/dashboard?
        api_key=AAA &
        app_id=BBB

Output:

{
    "30days": { // --> X object
        "dashboard": {
            "total_sessions": { // --> Y object
                "total": 304947,
                "change": "-24.6%", // percent change
                "trend": "d" // trend, can be up (u) or down (d)
            },
            "total_users": { // Same data as Y object },
            "new_users": { // Same data as Y object },
            "total_time": { // Same data as Y object },
            "avg_time": { // Same data as Y object },
            "avg_requests": { // Same data as Y object }
        },
        "top": {
            "platforms": [ // --> Z array
                {
                  "name": "iOS",
                  "percent": 60
                },
                {
                  "name": "Android",
                  "percent": 30
                },
                {
                  "name": "BlackBerry",
                  "percent": 10
                },
            ],
            "resolutions": [ // Same data as Z array ],
            "carriers": [ // Same data as Z array ],
            "users": [ // Same data as Z array ]
        },
        "period": "19 Jan - 17 Feb"
    },
    "7days": { // Same data as X object },
    "today": { // Same data as X object },
}

/o/analytics/countries

    http://your_domain/o/analytics/countries?
        api_key=AAA &
        app_id=BBB

Output:

{
    "30days": [ // --> X array, contains at most 10 countries
        {
            "country": "Germany",
            "code": "de",
            "t": 72225,
            "u": 8781,
            "n": 1340
        }
    ]
    "7days": [ // Same data as X array ],
    "today": [ // Same data as X array ],
}

Looking for help?

Countly Enterprise Support

Create a ticket for any support request you might have as a Countly Enterprise Customer

Countly Community

Join us on Discord to engage in discussions, share your feature ideas, and learn from fellow Countly users