Usage API Reference

The Usage REST APIs allow system administrators to retrieve usage data for each of their Applications and Applications they manage. An API key is required to authenticate with this API. If you have not received an API key, please email your request to support@senraco.com or call the technical support phone number shown on support@senraco.com.

Response types vary from method to method.

Note

The keys required for Usage API access and Onboarding API access are different, i.e. An Onboarding API key will not grant access to the Usage APIs and vice versa.


Summary API

Returns a summary of all usage data for a given Application, month, and year.

Resource URL

https://api.senraco.io/rest/integration/usage/summary

HTTP Method

GET

Parameters

Parameter Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the LoRa Application. Yes Hexadecimal String
month The month to retrieve usage data for. Yes 1-12
year The year to retrieve usage data for. Yes 1 1-XXXX

Response

Content-Type: JSON

Field Description
numberOfDevices The total number of Devices on the Application
numberOfActiveDevices The total number of active Devices on the Application
numberOfReportingDevices The total number of devices that are active and have sent uplinks on the Application
numberOfDevicesEvaluated The total number of devices processed for usage data
totalRegistrations The total number of registrations on that Application
totalActivations The total number of activations on that Application
totalDeactivations The total number of deactivations on that Application
totalUpPackets The total number of up packets heard on that Application during the given month
totalDownPackets The total number of down packets heard on that Application during the given month
totalSecuritySession The total number of security sessions that occurred on that Application during the given month
totalLocalUpMsg The total number of up messages heard on Base Stations owned by the Application operator during the given month
totalForeignUpMsg The total number of up messages heard on Base Stations not owned by the Application operator during the given month
totalLocalDownMsg The total number of down messages heard on Base Stations owned by the Application operator during the given month
totalForeignDownMsg The total number of down messages heard on Base Stations not owned by the Application operator during the given month
billableFeatures An array of billable features enabled for the Application
contracts An array of statistics for each Contract on the Application

Billable Features

Field Description
duplicateUplinks Whether or not duplicate uplinks are sent northbound
includeRfData Whether or not the RF data is sent northbound
estLocation Whether or not the estimated location is sent northbound

Contracts

Field Description
contractId The unique id of the Contract
deviceCount The total number of devices sent northbound
Code Reason Description
200 Success Request was successfully processed
403 Authorization failure Access to this resource has been rejected due to an authorization issue
400 Bad Request Invalid request due to insufficient or malformed parameters
404 Application or File not found Indicates that either the given application cannot be found or there is no usage data for the given month/year

Curl Example

curl -X GET \
  'https://api.senraco.io/rest/integration/usage/summary?eui=<EUI>&year=<YEAR>&month=<MONTH>' -H 'Authorization: <API_KEY_TO_USE>'
{
    "billableFeatures": [
        {
            "simpleLocation": true
        },
        {
            "completeRfMetadata": true
        }
    ],
    "contracts": [
        {
            "contractId": -1,
            "deviceCount": 8
        },
        {
            "contractId": 0,
            "deviceCount": 1
        }
    ],
    "stats": {
        "numberOfDevices": 9,
        "numberOfActiveDevices": 0,
        "numberOfReportingDevices": 0,
        "numberOfDevicesEvaluated": 9,
        "totalUpPackets": 7152,
        "totalDownPackets": 0,
        "totalSecuritySession": 0,
        "totalLocalUpMsg": 0,
        "totalForeignUpMsg": 0,
        "totalLocalDownMsg": 0,
        "totalForeignDownMsg": 0,
        "totalRegistrations": 0,
        "totalActivations": 0,
        "totalDeactivations": 0
    }
}

Details API

Returns the details of all usage data for a given application, month, and year.

Resource URL

https://api.senraco.io/rest/integration/usage/details

HTTP Method

GET

Parameters

Parameter Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the LoRa Application. Yes Hexadecimal String
month The month to retrieve usage data for. Yes 1-12
year The year to retrieve usage data for. Yes 1 1-XXXX

Response

Content-Type: text/csv This web service returns a file containing all the devices on the application and their usage statistics.

See Application Details File for descriptions of the field data in the CSV file.

Code Reason Description
200 Success Request was successfully processed
403 Authorization failure Access to this resource has been rejected due to an authorization issue
400 Bad Request Invalid request due to insufficient or malformed parameters
404 Application or File not found Indicates that either the given application cannot be found or there is no usage data for the given month/year

Curl Example

curl -X GET \
  'https://api.senraco.io/rest/integration/usage/details?eui=<EUI>&year=<YEAR>&month=<MONTH>' -H 'Authorization: <API_KEY_TO_USE>'

Contracts API

Returns the per contract usage data for a given application, month, and year.

Resource URL

https://api.senraco.io/rest/integration/usage/contracts

HTTP Method

GET

Parameters

Parameter Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the LoRa Application. Yes Hexadecimal String
month The month to retrieve usage data for. Yes 1-12
year The year to retrieve usage data for. Yes 1 1-XXXX

Response

Content-Type: text/csv This WS returns a file containing all the contracts on the application and their usage statistics.

See Application Contracts File for descriptions of the field data in the CSV file.

Code Reason Description
200 Success Request was successfully processed
403 Authorization failure Access to this resource has been rejected due to an authorization issue
400 Bad Request Invalid request due to insufficient or malformed parameters
404 Application or File not found Indicates that either the given application cannot be found or there is no usage data for the given month/year

Curl Example

curl -X GET \
  'https://api.senraco.io/rest/integration/usage/contracts?eui=<EUI>&year=<YEAR>&month=<MONTH>' -H 'Authorization: <API_KEY_TO_USE>'