Was this helpful?

Retrieving counters

To retrieve a counter, do the following:

Request syntax

curl -X GET https://api.usergrid.com/counters?counter=<counter_name>

Parameters

Parameter Description
counter_name The name of the counter to be retrieved. More than one counter can be retrieved with a single request by appending additional counter parameters to the request URI.

Example request

curl -X GET https://api.usergrid.com/my-org/my-app/counters?counter=button_clicks

Example response

{
  "action" : "get",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "counter" : [ "button_clicks" ]
  },
  "uri" : "https://api.usergrid.com/your-org/your-app",
  "entities" : [ ],
  "timestamp" : 1401310084096,
  "duration" : 21,
  "organization" : "your-org",
  "applicationName" : "your-app",
  "count" : 0,
  "counters" : [ {
    "name" : "button_clicks",
    "values" : [ {
      "timestamp" : 1,
      "value" : 9
    } ]
  } ]
}
		

SDK Method

- (ApigeeClientResponse*)getCounters:(NSArray*)counterArray

Parameters

Parameter Description
counterArray An NSArray of the names of the counters to be retrieved.

Example request

//we recommend you call ApigeeClient from your AppDelegate.
//for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
//create an instance of AppDelegate
AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate];

//create an array of the counters you want to retrieve
NSArray *counters = @[@"button_clicks"]; //multiple counters are allowed

//call getCounters to initiate the API GET request to retrieve our counters
ApigeeClientResponse *response = [appDelegate.dataClient getCounters:counters];

@try {
    //success
}
@catch (NSException * e) {
    //fail
}
		

Example response

{
    action = get;
    application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
    applicationName = your-app;
    count = 0;
    counters =     (
                {
            name = "button_clicks";
            values =             (
                                {
                    timestamp = 1;
                    value = 9;
                }
            );
        }
    );
    duration = 18;
    entities =     (
    );
    organization = your-org;
    params =     {
        counter =         (
            "button_clicks"
        );
    };
    timestamp = 1401313099150;
    uri = "https://api.usergrid.com/your-org/your-app";
}
		

Request syntax

void getCountersAsync(final ArrayList counterArray,
            final ApiResponseCallback callback) {
		

Parameters

Parameter Description
counterArray An ArrayList of the names of the counters to be retrieved.
callback An ApiResponseCallback instance to handle the async response.

Example request

// get an instance of the ApigeeClient class
ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
DataClient client = apigeeClient.getDataClient();

// specify the counter names to be retrieved in an ArrayList
ArrayList counterArray = new ArrayList();
counterArray.add("button_clicks");

// call getCountersAsync to initiate the async GET request
client.getCountersAsync(counterArray, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error		
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	            // Success	        	
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    }
	}
		

Example response

{
  "action" : "get",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "counter" : [ "button_clicks" ]
  },
  "uri" : "https://api.usergrid.com/your-org/your-app",
  "entities" : [ ],
  "timestamp" : 1401310084096,
  "duration" : 21,
  "organization" : "your-org",
  "applicationName" : "your-app",
  "count" : 0,
  "counters" : [ {
    "name" : "button_clicks",
    "values" : [ {
      "timestamp" : 1,
      "value" : 9
    } ]
  } ]
}
		

Request syntax

Counter.fetch(callback)

Parameters

Parameter Description
callback A callback function to handle the async API response.

Example request

// create an instance of Apigee.Client to call API methods			
var dataClient = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app',
});

// create a Counter object to represent the counter to be retrieved    
var event_options = {
    client: dataClient,
    timestamp: 0,
    counters: {
        'button_clicks':null // value is null since we are retrieving, not incrementing
    }
};

var counter = new Apigee.Counter(event_options, function (error, result) {

    if (error) { 
        // Error creating Counter object
    } else { 
        // Counter object created
    }

});

// call fetch() to retrieve the counter
counter.fetch (function (error, result) {

    if (error) { 
        // Error retrieving counter        
    } else { 
        // Success retrieving counter                
    }

});
		

Example response

Usergrid.Response {action: "get", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, uri: "https://api.usergrid.com/your-org/your-app", entities: Array[0]…}
action: "get"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
count: 0
counters: Array[1]
	0: Object
		name: "button_clicks"
		values: Array[1]
		0: Object
			timestamp: 1
			value: 9
			__proto__: Object
			length: 1
	__proto__: Array[0]
__proto__: Object
length: 1
__proto__: Array[0]
duration: 14
entities: Array[0]
err: null
logger: Logger
organization: "your-org"
params: Object
status: 200
statusGroup: 200
success: true
timestamp: 1401404328610
uri: "https://api.usergrid.com/your-org/your-app"
		

SDK method

counter(counter_name)

Parameters

Parameter Description
counter_name The name of the counter to be retrieved.

Example request

#Create a client object
usergrid_api = 'https://api.usergrid.com/'
organization = 'your-org'
application = 'your-app'

client = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"

begin
	#Call counter() to initiate the API GET request
	response = client.counter 'button_clicks'	
rescue
	#fail
end
		

Example response

{
  "action" : "get",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "counter" : [ "button_clicks" ]
  },
  "uri" : "https://api.usergrid.com/your-org/your-app",
  "entities" : [ ],
  "timestamp" : 1401475666535,
  "duration" : 14,
  "organization" : "your-org",
  "applicationName" : "your-app",
  "count" : 0,
  "counters" : [ {
    "name" : "button_clicks",
    "values" : [ {
      "timestamp" : 1,
      "value" : 9
    } ]
  } ]
}
		

SDK method

// create an instance of Usergrid.client to call API methods			
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app',
});

// create a Counter object to represent the counter to be retrieved    
var event_options = {
    client: dataClient,
    timestamp: 0,
    counters: {
        'button_clicks':null // value is null since we are retrieving, not incrementing
    }
};

var counter = new Usergrid.counter(event_options, function (error, result) {

    if (error) { 
        // Error creating Counter object
    } else { 
        // Counter object created
    }

});

// call fetch() to retrieve the counter
counter.fetch (function (error, result) {

    if (error) { 
        // Error retrieving counter        
    } else { 
        // Success retrieving counter                
    }

});
		

Parameters

Parameter Description
callback A callback function to handle the async API response.

Example request

curl -X GET https://api.usergrid.com/my-org/my-app/counters?counter=button_clicks

Example response

{ action: 'get',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: 
   { end_time: [ '1401474371670' ],
     counter: [ 'button_clicks' ],
     start_time: [ 'undefined' ],
     resolution: [ 'all' ] },
  uri: 'https://api.usergrid.com/your-org/your-app',
  entities: [],
  timestamp: 1401474368377,
  duration: 16,
  organization: 'your-org',
  applicationName: 'your-app',
  count: 0,
  counters: [ { name: 'button_clicks', values: [Object] } ] }
		

Retrieving counters by time interval

Knowing the value of a counter is useful; however, you often need to know how the value varies over time. Fortunately, the API provides a method for you to view this data over any time interval or level of granularity.

For example, let’s say you’re incrementing a counter every time someone launches your application. You might be interested in which days of the week the application sees the most usage. Using the API, you can examine the counter over a set of weeks, with the data split into daily intervals. Using this information, you can see which are your peak days of usage. You can also view usage across a single day, so you can see if your application is used more in the mornings or the evenings.

Request syntax

curl -X GET https://api.usergrid.com/counters?start_time=<timestamp>&end_time=<timestamp>&resolution=<resolution>&counter=<counter_name>

Parameters

Parameter Description
start_time The beginning of the time period to search
end_time The end of the time period to search
resolution

The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days.

The following resolutions are supported:

  • all
  • minute
  • five_minutes
  • half_hour
  • hour
  • six_day
  • day
  • week
  • month
counter_name The name of the counter to be retrieved.

Example request

For example, to retrieve a time range of values, with a granularity of "day", for a counter called "button_clicks", the GET request would look like this:

curl -X GET https://api.usergrid.com/my-org/my-app/counters?start_time=1315119600000&end_time=1315724400000&resolution=day&counter=button_clicks

Example response

		{
		 action: "get",
		    uri: "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/counters",
		    timestamp: 1315354369272,
		    duration: 28,
		    counters: [
		        {
		            name: "button_clicks",
		            values: [
		                {
		                    value: 2
		                    timestamp: 1315180800000
		                },
		                {
		                    value: 1
		                    timestamp: 1315267200000
		                },
		                {
		                    value: 1
		                    timestamp: 1315353600000
		                }
		            ]
		        }
		    ]
		}
		

SDK Method

- (ApigeeClientResponse*)getCountersByInterval:(NSArray*)counterArray
                                      startTime:(NSDate*)start_time
                                        endtime:(NSDate*)end_time
                                     resolution:(NSString*)interval
		

Parameters

Parameter Description
counterArray An NSArray of the names of the counters to be retrieved.
start_time The beginning of the time period to search
end_time The end of the time period to search
interval

The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days.

The following resolutions are supported:

  • all
  • minute
  • five_minutes
  • half_hour
  • hour
  • six_day
  • day
  • week
  • month

Example request

//create an array of the counters you want to retrieve
NSArray *counters = @[@"button_clicks"]; //multiple counters are allowed

//get results by hour for the last day
NSDate *start = [NSDate dateWithTimeIntervalSinceNow:-86400];
NSDate *end = [NSDate date];
NSString *res = @"hour";

//call getCountersByTimeInterval to initiate the API GET request to retrieve our counters
ApigeeClientResponse *response = [appDelegate.dataClient getCountersByInterval:counters startTime:start endTime:end resolution:res];

@try {
    //success
}
@catch (NSException * e) {
    //fail
}
		

Example response

{
    action = get;
    application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
    applicationName = your-app;
    count = 0;
    counters =     (
                {
            name = "button_clicks";
            values =             (
                                {
                    timestamp = 1401228000000;
                    value = 1;
                },
                                {
                    timestamp = 1401231600000;
                    value = 3;
                },
                                {
                    timestamp = 1401292800000;
                    value = 1;
                }
            );
        }
    );
    duration = 18;
    entities =     (
    );
    organization = your-org;
    params =     {
        counter =         (
            "button_clicks"
        );
        "end_time" =         (
            1401316586677
        );
        resolution =         (
            hour
        );
        "start_time" =         (
            1401230186677
        );
    };
    timestamp = 1401316588796;
    uri = "https://api.usergrid.com/your-org/your-app";
}
		

SDK method

void getCountersForIntervalAsync(final ArrayList counterArray, final Date startTime, 
            final Date endTime, final String resolution, final ApiResponseCallback callback)
		

Parameters

Parameter Description
counterArray An NSArray of the names of the counters to be retrieved.
start_time The beginning of the time period to search
end_time The end of the time period to search
resolution

The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days.

The following resolutions are supported:

  • all
  • minute
  • five_minutes
  • half_hour
  • hour
  • six_day
  • day
  • week
  • month
callback An ApiResponseCalback instance to handle the async response.

Example request

// get an instance of the DataClient class
ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
DataClient client = apigeeClient.getDataClient();

// create an array of the counter names to be retrieved
ArrayList counterArray = new ArrayList();
counterArray.add("button_clicks");

// specify the interval criteria
Date end = new Date(); //end time
Date start = new Date(end.getTime() - 172800000); // start time
String res = "hour"; // resolution

// call getCountersForIntervalAsync to initiate the GET request
client.getCountersForIntervalAsync(counterArray, start, end, res, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error		
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	            // Success
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    }
	}
		

Example response

{
  "action" : "get",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "end_time" : [ "1401393403800" ],
    "counter" : [ "button_clicks" ],
    "start_time" : [ "1401220603800" ],
    "resolution" : [ "hour" ]
  },
  "uri" : "https://api.usergrid.com/your-org/your-app",
  "entities" : [ ],
  "timestamp" : 1401395202252,
  "duration" : 16,
  "organization" : "your-org",
  "applicationName" : "your-app",
  "count" : 0,
  "counters" : [ {
    "name" : "button_clicks",
    "values" : [ {
      "timestamp" : 1401224400000,
      "value" : 4
    }, {
      "timestamp" : 1401228000000,
      "value" : 1
    }, {
      "timestamp" : 1401231600000,
      "value" : 3
    }, {
      "timestamp" : 1401292800000,
      "value" : 1
    } ]
  } ]
}
		

SDK method

Counter.getData(options, callback)

Parameters

Parameter Description
options

A JSON object that specifies the following request options:

  • start: A UNIX timestamp in milliseconds of the beginning of the time period to search
  • end: A UNIX timestamp in milliseconds of the end of the time period to search
  • resolution: The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days.

    The following resolutions are supported:

    • all
    • minute
    • five_minutes
    • half_hour
    • hour
    • six_day
    • day
    • week
    • month
callback A callback function to handle the async API response.

Example request

curl -X GET https://api.usergrid.com/my-org/my-app/counters?counter=button_clicks

Example response

Usergrid.Response {action: "get", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, uri: "https://api.usergrid.com/your-org/your-app", entities: Array[0]…}
action: "get"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
count: 0
counters: Array[1]
	0: Object
		name: "button_clicks"
		values: Array[2]
		0: Object
			timestamp: 1401231600000
			value: 3
			__proto__: Object
		1: Object
			timestamp: 1401292800000
			value: 1
			__proto__: Object
		length: 2
		__proto__: Array[0]
	__proto__: Object
	length: 1
	__proto__: Array[0]
duration: 15
entities: Array[0]
err: null
logger: Logger
organization: "your-org"
params: Object
status: 200
statusGroup: 200
success: true
timestamp: 1401407234135
uri: "https://api.usergrid.com/your-org/your-app"
__proto__: Object
		

SDK method

counter(counter_name, start_time, end_time, resolution)

Parameters

Parameter Description
counter_name The name of the counter to be retrieved.
start_time The beginning of the time period to search
end_time The end of the time period to search
resolution

The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days.

The following resolutions are supported:

  • all
  • minute
  • five_minutes
  • half_hour
  • hour
  • six_day
  • day
  • week
  • month

Example request

#Create a client object
usergrid_api = 'https://api.usergrid.com/'
organization = 'your-org'
application = 'your-app'

client = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"

begin
	#Call counter() to initiate the API GET request
	response = client.counter 'button_clicks', start_time:1401232764000, end_time:1401405564000, resolution:'hour'
rescue
	#fail
end
		

Example response

{
  "action" : "get",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "end_time" : [ "1401405564000" ],
    "counter" : [ "button_clicks" ],
    "start_time" : [ "1401232764000" ],
    "resolution" : [ "hour" ]
  },
  "uri" : "https://api.usergrid.com/your-org/your-app",
  "entities" : [ ],
  "timestamp" : 1401475893680,
  "duration" : 12,
  "organization" : "your-org",
  "applicationName" : "your-app",
  "count" : 0,
  "counters" : [ {
    "name" : "button_clicks",
    "values" : [ {
      "timestamp" : 1401231600000,
      "value" : 3
    }, {
      "timestamp" : 1401292800000,
      "value" : 1
    } ]
  } ]
}
		

SDK method

Counter.getData(options, callback)

Parameters

Parameter Description
options

A JSON object that specifies the following request options:

  • start: A UNIX timestamp in milliseconds of the beginning of the time period to search
  • end: A UNIX timestamp in milliseconds of the end of the time period to search
  • resolution: The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days.

    The following resolutions are supported:

    • all
    • minute
    • five_minutes
    • half_hour
    • hour
    • six_day
    • day
    • week
    • month
callback A callback function to handle the async API response.

Example request

// create an instance of Usergrid.client to call our API methods			
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app',
});

// create a Counter object to represent the counter to be retrieved    
var event_options = {
    client: dataClient,
    timestamp: 0,
    counters: {
        'button_clicks':null
    }        
};

var counter = new Usergrid.counter(event_options, function (error, result) {

  if (error) { 
      // Error creating Counter object
  } else { 
      // Counter object created
  }

});

// specify the options for the interval we want to retieve
var interval_options = {
    start: 1401232764000,
    end: 1401405564000,
    resolution: 'hour'
}

// call getData() to retrieve the counter data for the interval
counter.getData (interval_options, function (error, result) {

    if (error) { 
        // Error retrieving counter        
    } else { 
        // Success retrieving counter                
    }

});
		

Example response

{ action: 'get',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: 
   { end_time: [ '1401405564000' ],
     counter: [ 'button_clicks' ],
     start_time: [ '1401232764000' ],
     resolution: [ 'hour' ] },
  uri: 'https://api.usergrid.com/your-org/your-app',
  entities: [],
  timestamp: 1401473985525,
  duration: 16,
  organization: 'your-org',
  applicationName: 'your-app',
  count: 0,
  counters: [ { name: 'button_clicks', values: [Object] } ] }
		

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)