1. Aeris
  2. APIs
  3. Aeris APIs - Using Aeris Gateway

 

Connectivity Aware APIs

Avatar
Aeris Admin

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

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.

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.