Top Property Counts API

Overview

This endpoint is used to retrieve counts for the most and least frequently occurring properties for a particular event in a specified duration.

For example, let’s you have an ecommerce app and you are tracking purchase events and storing the product purchased as a property on the event. You can use this endpoint to find out what products are the most frequently purchased.

Base URL

https://location.api.clevertap.com/1/counts/top.json

📘

Note

Use the URL based on your location:

  • India - in1.api.clevertap.com
  • Singapore - sg1.api.clevertap.com
  • U.S - us1.api.clevertap.com

HTTP Method

POST

Headers

These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. Please see the authentication guide to see how to get their values.

Header

Description

Type

Example Value

X-CleverTap-Account-Id

Your CleverTap Account ID.

string

"X-CleverTap-Account-Id: ACCOUNT_ID"

X-CleverTap-Passcode

Your CleverTap Account Passcode.

string

"X-CleverTap-Passcode: PASSCODE"

Content-Type

Request content-type is always set to application/json.

string

"Content-Type: application/json"

Body Parameters

The body is uploaded as a JSON payload.

Parameter

Description

Required

Type

Example Value

event_name

The name of the event.

required

string

"choseNewFavoriteFood"

from

Start of date range within which users should have performed the event you specified in event_name. Input values have to be formatted as integers in format YYYYMMDD.

required

int

20150810

to

End of date range within which users should have performed the event you specified in event_name. Input values have to be formatted as integers in format YYYYMMDD.

required

int

20151025

groups

Object containing information about properties for which breakdown is required. The endpoint can be used to obtain analysis of multiple properties in one request. Each property object is referenced by a unique key within the groups object.

required

object

"groups": {
"foo": {
"property_type": "event_properties",
"name": "Amount"
},
"bar": {
"property_type": "profile_fields",
"name": "Customer Type",
"top_n": 2,
"order": "asc"
}
}

groups.property_type

Type of property for which top breakdown is required. Can be event_properties, session_properties, profile_fields, app_fields, demographics, technographics, reachability or geo_fields. Must be present inside each individual group.

required

string

"event_properties"

groups.name

Name of the property for which top breakdown is required. Must be present along with property_type.

required

string

“Amount”

top_n

Number of top values required for a given property. Can be specified along with property_type and name. Defaults to 10 if absent.

optional

int

2

order

Sort order. Either desc or asc. Defaults to desc if absent.

optional

string

"asc"

The property_type parameter enables you to specify the type of property you need metrics for. Here are the descriptions for the potential parameter values.

property_type

Description

event_properties

All event properties for the specified event_name.

profile_fields

All custom profile fields for the account.

session_properties

utm_source, utm_medium, utm_campaign, session_referrer, session_source, time_of_day (granularity up to hour of day).

app_fields

All the app fields.

demographics

All the demographics fields.

technographics

All the technographics fields.

reachability

All the reachability fields.

geo_fields

Country, region, city.

Below is an example payload.

{
    "event_name": "Charged",
    "from": 20161229,
    "to": 20170129,
    "groups": {
        "foo": {
            "property_type": "event_properties",
            "name": "Amount"
        },
        "bar": {
            "property_type": "profile_fields",
            "name": "Customer Type",
            "top_n": 2,
            "order": "asc"
        }
    }
}

Example Request

curl -X POST -d '{"event_name":"Charged","from":20161229,"to":20170129,"groups":{"foo":{"property_type":"event_properties","name":"Amount"},"bar":{"property_type":"profile_fields","name":"CustomerType","top_n":2,"order":"asc"}}}' "https://location.api.clevertap.com/1/counts/top.json" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json"
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://location.api.clevertap.com/1/counts/top.json")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
request.body = JSON.dump({
  "event_name" => "Charged",
  "from" => 20161229,
  "to" => 20170129,
  "groups" => {
    "foo" => {
      "property_type" => "event_properties",
      "name" => "Amount"
    },
    "bar" => {
      "property_type" => "profile_fields",
      "name" => "CustomerType",
      "top_n" => 2,
      "order" => "asc"
    }
  }
})

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json',
}

data = '{"event_name":"Charged","from":20161229,"to":20170129,"groups":{"foo":{"property_type":"event_properties","name":"Amount"},"bar":{"property_type":"profile_fields","name":"CustomerType","top_n":2,"order":"asc"}}}'

response = requests.post('https://location.api.clevertap.com/1/counts/top.json', headers=headers, data=data)
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
    'X-CleverTap-Account-Id' => 'ACCOUNT_ID',
    'X-CleverTap-Passcode' => 'PASSCODE',
    'Content-Type' => 'application/json'
);
$data = '{"event_name":"Charged","from":20161229,"to":20170129,"groups":{"foo":{"property_type":"event_properties","name":"Amount"},"bar":{"property_type":"profile_fields","name":"CustomerType","top_n":2,"order":"asc"}}}';
$response = Requests::post('https://location.api.clevertap.com/1/counts/top.json', $headers, $data);
var request = require('request');

var headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json'
};

var dataString = '{"event_name":"Charged","from":20161229,"to":20170129,"groups":{"foo":{"property_type":"event_properties","name":"Amount"},"bar":{"property_type":"profile_fields","name":"CustomerType","top_n":2,"order":"asc"}}}';

var options = {
    url: 'https://location.api.clevertap.com/1/counts/top.json',
    method: 'POST',
    headers: headers,
    body: dataString
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

Example Response

{
  "status": "success",
  "foo": {
    "NUMBER": {
      "0-100": 10,
      "100-200": 9,
      "200-300": 8,
      "300-400": 7,
      "400-500": 6,
      "500-600": 5,
      "600-700": 4,
      "700-800": 3,
      "800-900": 2,
      "900-1000": 1
    }
  },
  "bar": {
    "STR": {
      "Gold": 5,
      "Silver": 10
    }
  }
}

Each property breakdown is referenced by the unique key assigned to it while querying. Within each property breakdown, there are separate objects specifying the data type for the property’s values that have been provided.

Data types can be STR, NUMBER, ENUM, or DATE. NUMBER and DATE breakdowns are ‘-‘ separated ranges. DATE values are in UNIX epoch format. Counts are present within the data type object for each property breakdown.

Notes

The response is a JSON object containing the key status, which might be success, partial, or fail.

If the status is success, there will be a count key with an int value of the count for the specified query. If the status is fail, there will be an error key with a string value and a HTTP status code.

If the status is partial, the query has not finished processing in our system. In the response, you will receive a req_id key with a long int value that you will use to poll for the result. After the query is completed, you will either receive a success response with the count if the query was successful, or a fail response with an error string and a HTTP status code. Please wait 30 seconds between polling requests.

Here is an example response for a partial status.

{
  "req_id": 384649162721759,
  "status": "partial"
}

After getting the req_id, you will poll the endpoint below and provide the value of req_id as a query parameter.

GET https://location.api.clevertap.com/1/counts/top.json?req_id=<your_request_id_here>


Did this page help you?