Server API reference

Follow

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.

FOR A COMPLETE API LIST, SEE COUNTLY API DOCUMENTATION PAGE

1. 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/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

    Similar to parameter, Heartbeat 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_sessionrequest.

  • 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:

    1. See how many times a user successfully completed or failed a level.
    2. See how many times in-app purchases were made and the total amount of these IAPs.
    3. 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 do make more IAPs.

2. Read API

A. 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 settings popup.
  • app_id

    Your application’s Application ID, which may be obtained from your 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
    

B. 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 ],
}
Was this article helpful?
0 out of 0 found this helpful

Looking for help?