3.5 Network Service API Operations

Table of Contents




AerFrame Network Service API is a set of API to access core network features like Clear Registration and Get Local Dialable Number.


3.5.1 AerFrame Network Service API


Table 22.    API Operations

MethodURIDescription
DELETE /networkservices/v2/{accountId}/devices/{deviceIdType}/{deviceId}/registration

Clear Registration for a Device:

Clears registration of device from the serving VLR and SGSN. DeviceIdType could IMSI or MSISDN. DeviceId is corresponding IMSI or MSISDN.

The Cancel Location is sent on a "best effort" basis. If the device's location is not known then a cancel location cannot be sent and the request is silently ignored. There is no result for a cancel location request.

GET/networkservices/v2/{accountId}/devices/{deviceIdType}/{deviceId}/localDialableNumber

Get Local Dialable Number:

Obtain a temporary local dialable number for the device. DeviceIdType could IMSI or MSISDN. DeviceId is the corresponding IMSI or MSISDN.

GET

/networkservices/v2/{accountId}/devices/{deviceIdType}/{deviceId}/networkLocation?apiKey=<apiKey>

Get Network Location of the Device

This API call fetches the network-based location of a GSM, Fusion North America, or Fusion Global device. This API fetches information about the base station or the cell tower ID to determine the device location location where the device is recently connected or registered.

This API accepts the IMSI or MSISDN as DeviceIdType to identify the device. DeviceId is the corresponding IMSI or MSISDN.

This API also accepts the unique API key that is assigned to the customer account for authentication and authorization of the API call. This API key can be retrieved from the AerPort Portal.

This API returns the real-time information about the device network location.

  • If the network is able to page the device successfully (device is on and registered in the network), then you will receive the location response with current location information.
  • If the network is unable to page the device (device is off), then you might get a location response with the last recorded location values from the network if the location was recorded within the last approximately 36 hours. Otherwise, the API returns the information with all core elements of the location response with zeros or with an error "Location not found."

NOTE: 

  • We recommend that you not exceed 1 request every 30 minutes per device.
  • Making more frequent location requests per device could result in timeouts.


Table 23.    LocalDialableNumberResponse

NamePresenceDescription
dialableNumberMandatoryLocal dialable number that can be used to make MT Voice call
numberNOAMandatoryNature of address of the returned dialable number
numberNPMandatoryNumbering plan of the returned dialable number
requestCompletedTimestampMandatoryTimestamp in millis when the request was completed by the network
validForSecondsMandatoryApprox time in seconds the dialable number is valid for
requestIdMandatoryReference to the request Id. Used internally by AerFrame. Clients can use it as reference in support tickets

Cell Tower Locations

Cell tower locations are composed of these elements:

  • mcc: mobile country code
  • mnc: mobile network code
  • lac: location area code
  • cellId: the unique identifier of the Base Transceiver Station (BTS) or sector of a BTS within a LAC

Running Get Network Location provides you with values for these elements. You can use these four values to look up the latitude and longitude coordinates of the tower using a tool such as Google Gelocation API or Mozilla Location Service data file. This information tells you the current geographic location of the device.

In the table below, note that mcc, mnc, lac, and cellId return integer values. In some cases, the returned value of mnc or cellId might be a one- or two-digit value like 6 or 10 that is missing one or two leading zeros. For example, the location returned could be mcc=310 and mnc=3. In this case, please add leading zeros to the mnc to end up with 3 digits (310 003) when looking up the latitude and longitude coordinates.

NOTE: there is one ambiguous case where adding a leading zero might not be correct. 334 050 is not the same as 334 50. If the device is in this region of Mexico, please be aware that this scenario is possible.

Table 24.    LocationResponse

NamePresenceDescription
responseTypeMandatoryCurrently always returns as 'Cell ID' because this API is intended to retrieve the cell ID only.
mccMandatoryDefines the Mobile Country Code (MCC) to identify country of the device location. For example, 404 and 405 represent India, 310, 311, 312, 313, 314 and 316 represent USA and so on.
mncMandatory

Defines the Mobile Network Code (MNC) to identify the mobile operator in the MCC.

See the MNC list here https://en.wikipedia.org/wiki/Mobile_country_code for quick reference.

lacMandatoryDefines the Location Area Code (LAC) which is the unique identifier of the current location area. This LAC is a group of base stations that are used together to optimize signalling.
cellIdMandatory

Defines the unique identifier of the Base transceiver station (BTS) or sector of a BTS within LAC.

The Cell ID can be zero because it does not depend on the data returned from the last known switch. If the device is registered with switch A and then turned off and moved to another location or country and has not yet registered, then switch A is still the last known switch but the API returns no location because the device is no longer registered at that switch.

To keep getting updated Cell ID, it is recommend that you execute the API on regular intervals to have updated information of the Cell Id.

If the Cell ID is zero for any reason, use the value of mcc, mnc, and lac fields to estimate the location (country and state) of the device.

locationTimestampOptionalIf not NULL or non-zero, then this is the timestamp when the location was received.This is non-NULL and non-zero if there is a location for this device. 
ageOfLocationOptional

Defines the age of location information in Minutes that how long back the location information was retrieved from the network. Returns NULL or Zero if no location information is available.

stateOptional

Returns the CS state, which can be one of the following:

  • 0 = assumedIdle
  • 1 = camelBusy
  • 2 = netDetNotReachable
  • 3 = notProvidedFromVLR
requestIdMandatoryReference to the request Id. Used internally by AerFrame. Clients can use it as reference in support tickets.
destinationTypeMandatoryReturns the switch type CS (Circuit Switch) or PS (Packet Switch) to represent the location result. Since, this API works only on CS (Circuit Switch), this field always return CS as its value.
destinationTypeCodeMandatoryReturns 7 always to represent the destination type value, where 7 represents VLR (circuit switched PSI).


Back to Top


3.5.2 Example Requests and Responses

Clear Registration for a Device

    URL    DELETE https://api.aerframe.aeris.com/networkservices/v2/{accountId}/devices/imsi/204111211111259/registration?apiKey={{accountApiKey OR appApiKey}}


Get Local Dialable Number

    URL    GET https://api.aerframe.aeris.com/networkservices/v2/{accountId}/devices/imsi/204043396000768/localDialableNumber?apiKey={{accountApiKey OR appApiKey}}

Response
{
  "numberNoa": 16
  "numberNp": 1
  "reqCompletedTimestamp": 1394239535000
  "validForSeconds": 30
  "requestId": "00009c71-30b8-954d-00b3-ff39179e8d5a"
  "dialableNumber": "19254350381"
}



Get Network Location of the Device

URL    GET https://api.aerframe.aeris.com/networkservices/v2/{accountId}/devices/imsi/204043396622367/networkLocation?apiKey={{accountApiKey OR appApiKey}}

Response
{
    "responseType": "Cell ID",
    "mcc": 404,
    "mnc": 11,
    "lac": 1013,
    "cellId": 0,
	"locationTimestamp": 1533581751.01775,
    "ageOfLocation": 0,
    "state": 0,
    "requestId": "000ba911-dabf-b375-0a43-e1c55e5e4da7",
    "destinationType": "CS",
    "destinationTypeCode": 7
}



Back to Top