Retrieving counters

Retrieving counters

To retrieve a counter, do the following:

cURL

Request syntax

curl -X GET https://<baas_host_name>/your-org/your-app/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://<baas_host_name>/my-org/my-app/counters?counter=button_clicks

Example response

{
  "action" : "get",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : {
    "counter" : [ "button_clicks" ]
  },
  "uri" : "https://<baas_host_name>/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
    } ]
  } ]
}
                

iOS

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://<baas_host_name>/your-org/your-app";
}
                

Android

Request syntax

void getCountersAsync(final ArrayList<string> 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());
ApigeeDataClient client = apigeeClient.getDataClient();

// specify the counter names to be retrieved in an ArrayList
ArrayList<string> counterArray = new ArrayList<string>();
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://<baas_host_name>/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
    } ]
  } ]
}
                

JavaScript (HTML5)

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://<baas_host_name>/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://<baas_host_name>/your-org/your-app"
                

Ruby

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://<baas_host_name>/'
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://<baas_host_name>/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
    } ]
  } ]
}
                

Node.js

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://<baas_host_name>/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://<baas_host_name>/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.

cURL

Request syntax

curl -X GET https://<baas_host_name>/your-org/your-app/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.