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
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 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.
To get usage for a specific cycle start date:
To get usage for a specific cycle start date, rate plan, and zone:
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.
Code Samples
Make sure to use the Control Center sandbox URL and your own user credentials.
Errors
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. |