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. API keys are created and managed in the API Keys view.

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
completeRfMetadata	Whether or not duplicate uplinks and RF data is sent northbound
simpleLocation	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>'