Get Location Service Usage
Get location services usage information
POST /usage
Returns the number of device location requests used by an account during a specified time period. Primary accounts can also see usage totals for their managed accounts.
To see only the usage by the primary account, use the primary accountName and set "usageForAllAccounts": false.
To see only the usage by a managed account, use the managed accountName. The usageForAllAccounts setting does not matter.
To see usage by all accounts, including the total number of transactions, use the primary accountName and set "usageForAllAccounts": true.
Header Parameters
The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization (required) | string | HTTP Authorization bearer token: Authorization: Bearer {token} |
| VZ-M2M-Token (required) | string | A valid session token: VZ-M2M-Token: {M2Mtoken} |
| Content-Type (required) | string | Must be application/json Content-Type: application/json |
HTTP Request
POST https://thingspace.verizon.com/api/loc/v1/usage
Request Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName (required) | string | The numeric name of the account. Must include any leading zeros. |
| startDate (required) | string ($date) | The first date to be included in the report as mm-dd-yyyy. |
| endDate (required) | string ($date) | The last date to be included in the report as mm-dd-yyyy. |
| usageForAllAccounts (optional) | boolean | Set to false to only see usage information for the specified account. If the accountName is a primary account, set this to true to see usage for all managed accounts. |
Request Body
Example Request Body
{
"accountName": "0000123456-00001",
"startDate": "07-01-2024",
"endDate": "07-31-2024",
"usageForAllAccounts": true
}Success Responses
Status 200
A success response for a single account shows the susbscription type, the number of transactions allowed in a billing cycle and the number of transactions used between the requested dates. The response for a primary account with "usageForAllAccounts": true also includes the number of transactions for each managed account.
Example Success Response for a Primary Account with "usageForAllAccounts": false:
{
"accountName": "0000123456-00001",
"usageForAllAcounts": false,
"skuName": "TS-LOC-COARSE-CellID-Aggr",
"transactionsAllowed": "5000",
"totalTransactionCount": "350",
"PrimaryAccount": {
"accountName": "0000123456-00001",
"transactionsCount": "125"
},
"ManagedAccounts": []
}Example Success Response for a Primary Account with "usageForAllAccounts": true:
{
"accountName": "000012345-00001",
"usageForAllAcounts": true,
"skuName": "TS-LOC-COARSE-CellID-Aggr",
"transactionsAllowed": "5000",
"totalTransactionCount": "350",
"PrimaryAccount": {
"accountName": "0000123456-00001",
"transactionsCount": "125"
},
"ManagedAccounts": [
{
"accountName": "0000123456-00002",
"transactionsCount": "100"
},
{
"accountName": "0000123456-00003",
"transactionsCount": "200"
},
{
"accountName": "0000123456-00004",
"transactionsCount": "300"
}
]
}Example Success Response for a Managed Account:
{
"accountName": "0000123456-00004",
"usageForAllAcounts": false,
"skuName": "TS-LOC-COARSE-CellID-Aggr",
"transactionsAllowed": "5000",
"totalTransactionCount": "200",
"PrimaryAccount": {},
"ManagedAccounts": [
{
"accountName": "0000123456-00004",
"transactionsCount": "200"
}
]
}Success Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName | string | The billing account for which usage information was requested. |
| usageForAllAccounts | boolean | Indicates whether the request was for an aggregated usage report (true) or non-aggregated (false). |
| skuName | string | The Device Location subscription type, which will be one of these values: TS-LOC-COARSE-CellID-5K - Monthly recurring subscription for 5,000 non-GPS device locate requests, TS-LOC-COARSE-CellID-10K - Monthly recurring subscription for 10,000 non-GPS device locate requests, TS-LOC-COARSE-CellID-100K - Monthly recurring subscription for 100,000 non-GPS device locate requests, TS-LOC-COARSE-CellID-1M - Monthly recurring subscription for 1,000,000 non-GPS device locate requests, TS-LOC-COARSE-CellID-Aggr or TS-LOC-COARSE-CellID-Aggr-ECPD - Aggregated billing account subscription. |
| transactionsAllowed | string | The number of location requests included with the subscription type. |
| totalTransactionCount | string | The total number of billable device location requests during the reporting period from all included accounts. |
| primaryAccount | object | The accountName and number of billable device location requests (transactionsCount) made by the primary account. |
| transactionsCount | string | The number of billable device location requests made. |
| ManagedAccounts | array | Usage for managed accounts. Each object in the array will have its own accountName and transactionsCount. |
Failure Responses
All error messages are returned in this format:
{
"errorCode": "The 3-digit HTML error code",
"errorMessage": "string"
}Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.