Get Device Usage by Zone

Description

For a specified device, returns usage information for a single billing cycle, broken down by rate plan and zone. You can filter the usage information by zone and/or rate plan, and specify a particular cycle start date. If no billing cycle is specified, the API returns usage for the current billing cycle by default. All usage is pre-invoiced and applies to wholesale rate plans. To retrieve retail rate plan usage, you must examine the corresponding wholesale rate plan usage.

Resource URL

GET rws/api/v{apiVersion}/devices/{iccid}/usageInZone

Request Parameters

Request Parameters and Descriptions
Parameter Description
apiVersion

The version number for this API. The current version for all functions is 1.

iccid The ICCID of the device you want information about.
cycleStartDate

(Optional) The first day of a billing cycle. This date must correspond to one of the last three billing cycles (the current billing cycle plus the two preceding cycles). If there is no date, the function returns usage information for the current billing cycle only.

The date format is yyyy-MM-ddZ. See Date Formats for details.

ratePlan

(Optional) The name of a rate plan. Use this parameter to retrieve usage information that's linked to a specific rate plan. If there's no rate plan listed, the function returns usage information for any rate plans used by the device during the specified time period. You can specify only one rate plan per function call.

zone

(Optional) The name of a billing zone. Use this parameter to track usage for a specific zone. To get usage information for all zones specified in the rate plans used by the device, omit this parameter. You can specify only one zone per function call.

Response Parameters

The function returns an array of usage records sorted by rate plan and zone.

Return Values and Descriptions
Return Value Description
iccid The ICCID of the device.
timestamp The point in time when the usage information was returned. The date format is yyyy-MM-ddTHH:mm:ss.SSSZ. See Date Formats for more details.
cycleStartDate The beginning of the billing cycle associated with the usage. The date format is yyyy-MM-ddTHH:mm:ss.SSSZ. See Date Formats for more details.
cycleEndDate The end of the billing cycle associated with the usage. The date format is yyyy-MM-ddTHH:mm:ss.SSSZ. See Date Formats for more details.
deviceCycleUsageInZones An object containing a list of rate plans used by the device during the billing cycle.
deviceCycleUsageInZones  
Rate Plan Name, Version Number Each rate plan contains an array of zones where usage occurred. If the device did not use service in a particular zone, that zone does not appear in the array. The function returns the rate plan version number, because in the case of prepaid rate plans it's possible for a device to use two versions of the same rate plan during the billing cycle.
ratePlan The name of the rate plan associated with the device usage.
ratePlanVersion The version number of the rate plan.
zone The name of the zone associated with the device usage.
dataUsage

The amount of data used during the specified time period.

dataUsageUnit The unit of measure for the data usage. Valid values include: bytes.
voiceMTUsage The number of mobile-terminated voice seconds used since the specified start date.
voiceMTUsageUnit The unit of measure for the voice MT usage. Valid values include: seconds.
voiceMOUsage

The number of mobile-originated voice seconds used since the specified start date.

voiceMOUsageUnit The unit of measure for the voice MO usage. Valid values include: seconds.
SMSmtusage

The number of mobile-terminated messages sent since the specified start date.

SMSmousage

The number of mobile-originated messages sent during the specified time period.

Request Example

Make sure to use your own user credentials. See Authentication for information about creating an authorization header.

The first example requests all usage records for a device during the current billing cycle. See the Response Example for the response.

json
Copycurl -X GET --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>" "https://rws-jpotest.jasper.com/rws/api/v1/devices/8988217755520000031/usageInZone"

To get usage for a specific cycle start date:

json
Copycurl -X GET --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>" "https://rws-jpotest.jasper.com/rws/api/v1/devices/8988217755520000031/usageInZone?cycleStartDate=2016-11-10Z"

To get usage for a specific cycle start date, rate plan, and zone:

json
Copycurl -X GET --header "Accept: application/json" --header "Authorization: Basic <YOUR-ENCRYPTED-CREDENTIALS>" "https://rws-jpotest.jasper.com/rws/api/v1/devices/8988217755520000031/usageInZone?cycleStartDate=2016-11-10Z&ratePlan=Rate%20Plan%20A&zone=Zone%20B"

Response Example

The response contains an array of rate plans. Each rate plan contains an array of usage records. This response matches the first request example.

json
Copy{   
  "iccid":"8988217755520000031",
  "timeStamp":"2016-11-10T05:31:17.557Z",
  "cycleStartDate":"2016-10-31T10:30:00.000Z",
  "cycleEndDate":"2016-11-30T10:29:59.000Z",
  "deviceCycleUsageInZones":{   
	"Rate Plan A, 1":[   
		{   
		"ratePlan":"Rate Plan A",
		"ratePlanVersion":"1",
		"zone":"default zone",
		"dataUsage":null,
		"dataUsageUnit":null,
		"voiceMTUsage":null,
		"voiceMTUsageUnit":null,
		"voiceMOUsage":600,
		"voiceMOUsageUnit":"seconds",
		"smsmtusage":null,
		"smsmousage":null
		}
	    ],
	"Rate Plan B, 2":[   
		{   
		"ratePlan":"Rate Plan B",
		"ratePlanVersion":"2",
		"zone":"default zone",
		"dataUsage":943718,
		"dataUsageUnit":"bytes",
		"voiceMTUsage":null,
		"voiceMTUsageUnit":null,
		"voiceMOUsage":943718,
		"voiceMOUsageUnit":"seconds",
		"smsmtusage":null,
		"smsmousage":null
		}
	    ]
	}
}

Code Samples

Make sure to use the Control Center sandbox URL and your own user credentials.

python
javascript
ruby
Copyimport requests 
import json 
import base64 
import pprint 

cobrandURL=input("Cobrand URL: ")						
url = 'https://'+cobrandURL+'/rws/api/v1/devices/'+input("iccid: ")+'/usageInZone' 
myResponse = requests.get(url,auth=(input("username: "),input("api_key: ")))
# For successful API call, response code will be 200 (OK)
if(myResponse.ok):
    # Loading the response data into a dict variable
    # json.loads takes in only binary or string variables so using content to fetch binary content
    # Loads (Load String) takes a Json file and converts into python data structure (dict or list, depending on JSON)
    jData = json.loads(myResponse.content)
    pp=pprint.PrettyPrinter(indent=4) 
    pp.pprint(jData) 
else:
    # If response code is not ok (200), print the resulting http error code with description
    print("Failure")
    myResponse.raise_for_status()
Copyvar request = require('request');
var body = [];
request.get('https://<your-base-URL>/rws/api/v1/devices/8988216716970004975/usageInZone').auth('username', 'password', false)
    .on('error', function(error){
        console.log('Error:', error);
    })
    .on('response', function(response) {
        console.log(response.statusCode); // return statusCode
        console.log(response.headers['content-type']); // return contentType
    })
    .on('data',function(chunk){
        body.push(chunk);
    })
    .on('end',function(){
        body = Buffer.concat(body).toString();
        console.log(body);
    });
Copy#!/usr/bin/ruby -w
require 'rest-client'
require 'json'
  
url = 'https://<your-base-URL>/rws/api/v1/devices/89011704252318147060/usageInZone'
response = RestClient::Request.execute(
 method: :get,
 url: url,
 user: 'username',
 password: 'password',
 :headers => {:accept => :json}
)
puts JSON.pretty_generate(JSON.parse(response))

Errors

Error Codes, HTTP Codes, and Descriptions
Error Code HTTP Code Error Message
10000001 401

Invalid credentials.

Description: Control Center uses this error message when the API credentials are invalid or when the IP address is not within the allowed range.

10000012 400 Invalid date format.
10000013 404

Invalid ratePlan.

10000024 400 Invalid apiVersion.
10000028 400

Invalid request.

Description: The request contained one or more unrecognized parameters.

10000031 400 Invalid Zone.
10000032 400

Cycle Start Date should be greater than or equal to 20xx-xx-xx.

Description: The cycleStartDate must specify one of the last three billing cycles (including the current cycle).

20000001 404 Resource not found - Invalid ICCID.
30000001 500 Unknown server error.