Connectivity Aware APIs – Aeris

Aeris always has a commitment to improving our customer experience with its evolving technology and set of new features.

The connectivity aware APIs is such an effort that enables you to gain access to the information for a set of IoT devices. These APIs are useful by providing relevant information about device manufacturers before conducting OTA provisioning campaigns for IoT devices or other similar activities. These APIs provides a straightforward method to interrogate Connectivity about a device's status (for example, is registered or in a data session) and a mechanism to detect if the device(s) are residing on an MNO's cell ID which may be congested (for example, how many devices are on a cell ID, relative to a device which Aeris is cognizant of).

Note:

These New APIs are developed and offered as 'beta' capabilities.
You can use the hostname as connectivity.aerisapis.com

Device Query – Cell Utilization API
Device Information API
Resource Limitation API
Ping API

Device Query – Cell Utilization API

Use this API to get registration information about devices and if these devices are having an active data session. If yes, then this API also returns the cellid of the device to whom it is connected.

URI

https://{hostname}/devicesQuery/{accountId}/devices/cellUtilization

Variable Path Parameters

The preceding URI has the following variable path parameters:

Name	Type	Description
accountId	String	Defines the account Id to which the device is provisioned. You can log in to the AerPort portal to get this Id.

Query Parameters

The preceding URI has the following query parameters:

Name	Type	Description
NA	NA	NA

HTTP Headers

The following standard and custom HTTP headers are supported.

Authorization Headers

Type	Value	Constraint	Description
Bearer Token	String	Mandatory	Use the Get Authentication Token API to retrieve this token. You can specify the same as key value pair.

Request Headers

HTTP headers available for the request are as follows:

Field Name	Value	Constraint
Accept	application/json	Optional
Content-Type	application/json	Mandatory
Accept-Charset	utf-8	Optional

Response Headers

HTTP headers available for the response are as follows:

Field Name	Value	Description
Content-Type	application/json; charset=utf-8	Defines the response format.
Content-Length	<n>	The content length value varies for each response.
Date	<Date Time Stamp>	Date time stamp of receiving the response.

Method Type

Method Type

POST

Request Payload Description

The request payload is provided as a JSON object with the following attributes:

Attribute Name

Data Type

Constraint

Description

idType

String

Mandatory

Defines the device indentifier name. Currently, imsi is the only supported value.

devices

String Array

Mandatory

Defines the array of imsi for all those devices that you need to interrogate.

For example, [“imsi1xxx“, “imsi2xxxx“]

Response Payload Description

The response payload is provided as a JSON object with the following attributes:

Attribute Name			Type	Description
resultCode			String	Defines the HTTP response code, as the API execution result.
devices			Data Array	Defines the array of device details for each device as provided in the request payload.
	idType		String	Currently, only imsi is supported value.
	id		String	Defines the imsi of device.
	status		String	Defines if the API is able to fetch the device details as SUCCESS or FAIL.
	resultCode		Integer	Defines the HTTP response code, if the API is able to fetch the device details.
	result		Data Array	Defines an array of device detail.
		resultcode	Integer	Same as resultCode field in devices array.
		cellId	String	Retuns the cell id of the tower to which the device connected.
		lastSessionTime	String	Retuns the last session start time in GMT 00:00 , in the following format: 2020-03-26 13:58:55+0000
		devicesNearbyCount	String	Returns the numbers of devices that are currently connected to the same cell tower.
		duration	String	Returns the duration of data session time in hours.

Sample Request

POST /devicesQuery/21561/devices/cellUtilization HTTP/1.1
Host: i-h-n-beta-devq-us-00-pre-ap.aeriscloud.com
Authorization: Bearer <Your Authorization Token>
Content-Type: application/json

{
  "idType": "imsi",
  "devices": [
    "310170817577775"
  ]
}

Sample Response

{
    "resultCode": "200",
    "devices": [
        {
            "idType": "imsi",
            "id": "310170817577775",
            "status": "SUCCESS",
            "resultCode": 200,
            "result": {
                "resultCode": 200,
                "cellId": "130014411C130014034E4523",
                "lastSessionTime": "2020-03-26 13:58:55+0000",
                "devicesNearbyCount": "2",
                "duration": "1"
            }
        }
    ]
}

Device Information API

Use this API to fetch information about technology, provisioning status, registration status, data session details, and the network location for the list of devices

URI

https://{hostname}/devicesQuery/{accountId}/devices/info

Variable Path Parameters

The preceding URI has the following variable path parameters:

Name	Type	Description
accountId	String	Defines the account Id to which the device is provisioned. You can log in to the AerPort portal to get this Id.

Query Parameters

The preceding URI has the following query parameters:

Name	Type	Description
NA	NA	NA

HTTP Headers

The following standard and custom HTTP headers are supported.

Authorization Headers

Type	Value	Constraint	Description
Bearer Token	String	Mandatory	Use the Get Authentication Token API to retrieve this token. You can specify the same as key value pair.

Request Headers

HTTP headers available for the request are as follows:

Field Name	Value	Constraint
Accept	application/json	Optional
Content-Type	application/json	Mandatory
Accept-Charset	utf-8	Optional

Response Headers

HTTP headers available for the response are as follows:

Field Name	Value	Description
Content-Type	application/json; charset=utf-8	Defines the response format.
Content-Length	<n>	The content length value varies for each response.
Date	<Date Time Stamp>	Date time stamp of receiving the response.

Method Type

Method Type

POST

Request Payload Description

The request payload is provided as a JSON object with the following attributes:

Attribute Name

Data Type

Constraint

Description

idType

String

Mandatory

Defines the device indentifier name. Currently, imsi is the only supported value.

devices

String Array

Mandatory

Defines the array of imsi for all those devices that you need to interrogate.

For example, [“imsi1xxx“, “imsi2xxxx“]

Response Payload Description

The response payload is provided as a JSON object with the following attributes:

Attribute Name		Type	Description
resultCode		String	Defines the HTTP response code, as the API execution result.
devices		Data Array	Defines the array of device details for each device as provided in the request payload.
	idType	String	Currently, only imsi is supported value.
	id	String	Defines the imsi of device.
	technology	Data Array	Defines the data array with the HTTP result code and the technology type (like GSM, LTE). `"technology": { "resultCode": 200, "technologyType": "LTE" },`
	provisioning	Data Array	Defines the data array with the HTTP result code and the provisioning status of the device (like BILL, PROV, CANCEL). `"provisioning": { "resultCode": 200, "provisioningStatus": "BILL" },`
	registration	Data Array	Defines the data array with the HTTP result code and the registration status of the device (like true, false). If true, it also returns the date-time of the registration. `"registration": { "resultCode": 200, "isRegistered": true, "lastRegistrationTime": "2020-03-26T11:40:30.000Z" },`
	dataSession	Data Array	Defines the data array with the HTTP result code and the data session status of the device (like true, false). `"dataSession": { "resultCode": 200, "dataSessionStatus": false },`
	networkLocation	Data Array	Defines the data array with the HTTP result code and the network location details if available. Like mcc, mnc, lac and so on. `"networkLocation": { "resultCode": 200, "mcc": 234, "mnc": 15, "lac": 310, "cellId": 47168, "locationTimestamp": 1584044985.42048, "ageOfLocation": 76, "state": 0, "destinationType": "CS", "destinationTypeCode": 7 }`

Sample Request

POST /devicesQuery/21561/devices/info HTTP/1.1
Host: i-h-n-beta-devq-us-00-pre-ap.aeriscloud.com
Authorization: Bearer <Your Authorization Token>
Content-Type: application/json

{
  "idType": "imsi",
  "devices": [
    "310170817577775"
  ]
}

Sample Response

{
    "resultCode": "200",
    "devices": [
        {
            "idType": "imsi",
            "id": "310170817577775",
            "technology": {
                "resultCode": 200,
                "technologyType": "LTE"
            },
            "provisioning": {
                "resultCode": 200,
                "provisioningStatus": "BILL"
            },
            "registration": {
                "resultCode": 200,
                "isRegistered": true,
                "lastRegistrationTime": "2020-03-26T11:40:30.000Z"
            },
            "dataSession": {
                "resultCode": 200,
                "dataSessionStatus": false
            },
            "networkLocation": {
                "resultCode": 404
            }
        }
    ]
}

Resource Limitation API

Use this API to obtain the resource limitations as provided by Aeris for the list of devices.

URI

https://{hostname}/devicesQuery/{accountId}/devices/resources

Variable Path Parameters

The preceding URI has the following variable path parameters:

Name	Type	Description
accountId	String	Defines the account Id to which the device is provisioned. You can log in to the AerPort portal to get this Id.

Query Parameters

The preceding URI has the following query parameters:

Name	Type	Description
NA	NA	NA

HTTP Headers

The following standard and custom HTTP headers are supported.

Authorization Headers

Type	Value	Constraint	Description
Bearer Token	String	Mandatory	Use the Get Authentication Token API to retrieve this token. You can specify the same as key value pair.

Request Headers

HTTP headers available for the request are as follows:

Field Name	Value	Constraint
Accept	application/json	Optional
Content-Type	application/json	Mandatory
Accept-Charset	utf-8	Optional

Response Headers

HTTP headers available for the response are as follows:

Field Name	Value	Description
Content-Type	application/json; charset=utf-8	Defines the response format.
Content-Length	<n>	The content length value varies for each response.
Date	<Date Time Stamp>	Date time stamp of receiving the response.

Method Type

Method Type

GET

Request Payload Description

The request payload is provided as a JSON object with the following attributes:

Attribute Name	Data Type	Constraint	Description
NA	NA	NA	NA

Response Payload Description

The response payload is provided as a JSON object with the following attributes:

Attribute Name	Type	Description
requestLimit	Integer	Defines the number of concurrent request that you can initiate. If you are having a multi-thread application that you need to ensure that only one request is initiated at a time.
concurrency	Integer	For Aeris internal use only.
delayPerDevice	Integer	For Aeris internal use only.
devicesLimit	Integer	Defines the number of devices that can be connected to the tower. For example, if the deviceLimit is 20 and you have 1000 devices at the same location then you need to create a loop of 20 devices 50 times.

Sample Request

GET /devicesQuery/21561/devices/resources HTTP/1.1
Host: i-h-n-beta-devq-us-00-pre-ap.aeriscloud.com
Authorization: Bearer <your generated token>
Content-Type: application/json

Sample Response

{
    "requestLimit": 1,
    "concurrency": 5,
    "delayPerDevice": 20,
    "devicesLimit": 20
}

Ping API

https://{hostname}/beta/service/devicesQuery/ping

API to ping device query service.