The Ranlytics Kallo API provides a mechanism for accessing data collected by Kallo devices for custom integrations, workflows and data export. The GraphQL API provides read-only access to processed metrics, events and raw data from Kallo devices.
Please note that the below metrics are a subset of those available to be parsed from the on-device modem. Therefore, additional metrics can be made available on request, as per discussion with Ranlytics representatives.
Authentication
To communicate with the GraphQL API, you'll need an API Key from Key Management in the Network Health Monitoring Workbench. We recommend you generate seperate API Keys for different applications.
Your API Key authenticates your GraphQL queries and restricts your access to view only your organisation's Kallo data. It should be included in all queries in the api-key header. The API will produce an error for any unauthenticated queries.
Consult your GraphQL's client documentation for information on how to add the api-key header to your queries.
For assistance with Grafana, see: Setting up Grafana | Help Centre.
Query Examples
Here we've collated a variety of example GraphQL queries which may be used to inform query creation and customisation.
Latest Metrics
This query provides the most recent power and noise measurements sample data, as well as the signal boolean and the sample time.
This type of query can be useful in cases where an application wishes to check for the quality of a signal for a given carrier and band on a known Kallo device.
The query uses a named GraphQL query that accepts four arguments to denote the carrier PLMN, technology, band and Kallo device to retrieve these results from. These are then used as part of the where filter. We'll explain some of these components underneath.
query LatestMetrics($plmn: String, $tech: String, $band: smallint, $device: String) {
cell_rf_metrics(
limit: 1
order_by: {time: desc_nulls_last}
where: {plmn: {_eq: $plmn}, technology: {_eq: $tech}, band: {_eq: $band}, serial_number: {_eq: $device}}
) {
rsrp,
rsrq,
signal,
time
}
}
Query Components
PLMN
The plmn field denotes the globally unique public land mobile network (PLMN) code of the carrier a set of metrics have been collected from. A PLMN code can be a 5 or 6 digit sequence unique to a carrier.
A single carrier may have multiple PLMNs so check those locally applicable. The PLMNs the Kallo units sample can be configured in the Kallo configurations.
Technology
The technology field refers to the radio access technology a sample was captured on.
The technologies the Kallo units sample can be configured in the Kallo configurations.
There are several possible values for this:
umts - Universal Mobile Telecommunications Service (the most common 3G technology)
lte - Long Term Evolution (4G)
nr - New Radio (5G)
Band
The band field refers to the 3GPP operating band number a sample was captured on. This band number corresponds the radio frequency ranges used by cellular devices set out by the 3GPP standards.
A carrier may offer multiple bands on the same technology in a location. Lookup tables can help you convert a band number to its corresponding frequency range or common name. Conversion tables are readily available for UMTS, LTE and NR band numbers.
The bands the Kallo units sample can be configured in the Network Health Monitoring configurations.
Serial Number
The serial_number field is an identifier used for programatically identifying a Kallo unit. You can access any Kallo owned by your organisation using its unique device serial number.
The serial_number for a Kallo can be found on the label attached to the Kallo unit itself, or in the Network Health Monitoring Workbench when viewing the chart. This value identifies the Kallo itself, not particular location or site; therefore, if a Kallo is replaced in the workbench, a different Kallo may be assigned to the same location.
Time
The time field indicates the time a device began sampling, with the provided metrics (eg. power, noise) collected at this time. This field is produced as a string RFC3339 representation of a date and time.
In this query we are using order_by to sort time descending to ensure we select only the latest Kallo sample for the given criteria.
Expected Output
{
"data": {
"cell_rf_metrics": [
{
"rsrp": -95.0625,
"rsrq": 25.299999237060547,
"signal": true,
"time": "2022-06-30T18:00:41+00:00"
}
]
}
}
Output Components
Power
The RSRP (Reference Signal Received Power) value for NR (5G) and LTE (4G) samples indicates the power level measured in decibel-milliwatts (dBm).
The RSCP (Received Signal Code Power) value for UMTS (3G) samples indicates the power level measured in decibel-milliwatts (dBm).
A null value indicates this metric could not be collected, but only indicates a network connection failure if the signal field is also false.
Noise
The RSRQ (Reference Signal Received Quality) and SINR (Signal to Interference plus Noise Ratio) values for NR (5G) and LTE (4G) samples indicates the noise level measured in decibels (dB).
The ECNO (Energy per Chip over Noise) value for UMTS (3G) samples indicates the noise level measured in decibels (dB).
A null value indicates this metric could not be collected, but only indicates a network connection failure if the signal field is also false.
Signal
The signal Boolean value on each Kallo sample indicates if the device was successfully able to connect to the network during the sample period.
When signal is false the cell measurement fields will always be null. When signal is true the Kallo has successfully connected to the carrier on the given band and cell measurements values may be given.
When the signal is true this indicates the Kallo has been able to connect to the network. However, this may include low power, or high noise conditions. It does not, alone, indicate the signal is sufficiently strong to hold a call or a data session.
Site Signal Check
This query provides a set of results allowing you to check signal on each carrier, technology and band combination sampled by any Kallo at a given subsite.
This type of query may be useful for simply validating a minimum availability of networks across a given site and subsite with multiple Kallos. It could be used to ensure an operation-critical carrier is always available, or that there is at least one network and band available at all times for SOS calling.
The query uses a named GraphQL query that accepts two arguments to identify the site to query results for. These are then used as part of the where filter. We'll explain some of these components underneath.
query SiteSignalCheck($site: Int, $subsite: Int) {
cell_rf_metrics(
order_by: [{plmn: asc}, {technology: asc}, {band: asc}, {time: desc_nulls_last}]
distinct_on: [plmn, technology, band]
where: {site_id: {_eq: $site}, sub_site_id: {_eq: $subsite}}
) {
plmn
technology
band
signal
time
}
}
Query Components
Site ID and Subsite ID
The site_id and subsite_id fields indicate the site and level/zone, respectively, of a set of Kallo locations in your organisation.
Each site can have many subsites, and a subsite can only belong to one site. Kallos are attached to a site and subsite in the workbench when they are installed to a location. Querying by site_id allows you to query all samples collected by Kallos deployed on the site and all subsites.
You can find the site_id and a subsite_id of a particular Kallo by navigating to the level/zone page in the Network Health Monitoring Workbench and examining the URL of the page.
You can alternatively use site_name and subsite_name to query a site by the user-entered name given to a site and subsite, respectively, in the workbench.
Example: Kallos listed on the Network Health Monitoring Workbench page with URL https://app.ranlytics.com/kallo/site/57/subsite/67 will have a site_id of 57 and a subsite_id of 67.
Throughput Metrics
This query provides a set of results allowing you to check maximum data throughput for a carrier sampled by a given Kallo device.
This type of query may be useful for asserting the maximum throughput available on a given carrier. This can be used to ensure a minimum level of service is available for a given carrier.
query ThroughputMetrics($plmn: String, $device: String) {
cell_throughput_metrics(
order_by: {time: desc_nulls_last}
where: {plmn: {_eq: $plmn}, serial_number: {_eq: $device}}
) {
max_download
max_upload
time
}
}
Output Components
Max Download and Max Upload
The max_download and max_upload fields indicate the maximum download and upload speeds, respectively, measured in bits per second (bps).
A null value indicates this metric could not be collected, but only indicates a network connection failure if the signal field is also false.
Cellular RF Metrics
GraphQL Type: cell_rf_metrics
RF Metrics are collected multiple times per hour and provide a snapshot of the RF environment at the time of sampling.
A single cell_rf_metrics record is created for every cell captured by the Kallo. This means a test for a single configuration may generate multiple cell_rf_metrics for any serving and neighbour cells advertising the configured PLMN, technology and band. You can use the serving_cell field to query only serving cells, and the dominant_cell field to query only the serving cell with the strongest signal.
Field | Type | Guaranteed | Description |
band | smallint | True | 3GPP Band Number |
channel | integer | True | 3GPP Channel Number |
config_id | integer | True | Identifier of the configuration used to collect the data |
cqi | integer | False | Channel Quality Indicator |
dominant_cell | boolean | True | Indicates if the cell has the strongest signal out of all available serving and neighbour cells |
ecno | float | False | Ratio between the received energy from the pilot signal CPICH per chip (Ec) to the noise density (No) (dB) |
install_location | locations | True | A locations entry |
install_location_id | integer | True | Identifier of the installation location where the data was collected |
mcs | integer | False | Modulation and Coding Scheme
NR: Coming soon |
pci | integer | False | Physical Cell Identifier
NR: Available LTE: Available UMTS: Not available |
plmn | string | True | Public Land Mobile Network Identifier (MCC-MNC) |
psc | integer | False | Primary Scrambling Code |
pucch_txp | float | False | Physical Uplink Control Channel Transmit Power (dBm)
NR: Coming soon LTE: Available UMTS: Not available |
pusch_txp | float | False | Physical Uplink Shared Channel Transmit Power (dBm) |
RSCP | float | False | Received Signal Code Power (dBm) |
RSRP | float | False | Reference Signal Received Power (dBm)
NR: Available LTE: Available UMTS: Not available |
RSRQ | float | False | Reference Signal Received Quality (dB)
NR: Available LTE: Available UMTS: Not available |
serial_number | string | True | Serial number of the device that collected the data |
serving_cell | boolean | True | Indicates if this cell was the serving cell during this RF test |
signal | boolean | True | Indicates if the device was successfully able to connect to the carrier network on the given band. If false, the metrics will be null |
sinr | float | False | Signal to Interference plus Noise Ratio (dB) |
site |
| True | A sites entry |
site_id | integer | True | Identifier of the site where the data was collected |
sub_site |
| True | A sub_sites entry |
sub_site_id | integer | True | Identifier of the sub-site where the data was collected |
ta | integer | False | Timing Advance
NR: Coming soon LTE: Coming soon UMTS: Not available |
task_index | smallint | True | Index of the configuration task that collected the data |
technology | string | True | 3GPP Technology
NR: New Radio (5G) |
time | timestamp | True | RFC3339 timestamp of the data collection time - NOTE: expressed in UTC |
txp | float | False | Transmitted Power (dBm)
NR: See PUSCH/PUCCH TxP LTE: See PUSCH/PUCCH TxP UMTS: Available |
Cellular Throughput Metrics
GraphQL Type: cell_throughput_metrics
Cellular throughput metrics provide the results of a data connection and throughput test to the server as configured. These tests are collected by default once every four hours for customers with this option.
A singular cell_throughput_metrics record is created for every test run on a Kallo. However, a subset of metrics recorded on each serving cell during the test is recorded in the cells field, or the associated cell_throughput_cells type.
Field | Type | Guaranteed | Description |
band | smallint | True | Configured 3GPP Band Number ("All Bands" configuration returned as 0) |
bytes_download | bigint | False | Total number of bytes downloaded during this throughput test |
bytes_upload | float | False | Total number of bytes uploaded during this throughput test |
cells |
| True | An array relationship |
config_id | integer | True | Identifier of the configuration used to collect the data |
install_location |
| True | A |
install_location_id | integer | True | Identifier of the installation location where the data was collected |
jitter_download | float | False | Download jitter in milliseconds |
jitter_upload | float | False | Upload jitter in milliseconds |
latency | float | False | Latency in milliseconds |
max_download | float | False | Maximum download speed in bits per second |
max_upload | float | False | Maximum upload speed in bits per second |
plmn | string | True | Public Land Mobile Network Identifier (MCC-MNC) |
rrc_messages | JSONB array | False | Ordered array of Radio Resource Control (RRC) messages collected during the test. |
serial_number | string | True | Serial number of the device that collected the data |
signal | boolean | True | Indicates if the device was successfully able to connect to the carrier network. If false, the metrics will be null |
site |
| True | A |
site_id | integer | True | Identifier of the site where the data was collected |
sub_site |
| True | A |
sub_site_id | integer | True | Identifier of the sub-site where the data was collected |
task_index | smallint | True | Index of the configuration task that collected the data |
technology | string! | True | Configured 3GPP Technology ("All Technology" configuration returned as "ALL") |
time | timestamp | True | RFC3339 timestamp of the data collection time - NOTE: expressed in UTC |
Cellular Voice Call Metrics
GraphQL Type: cell_voice_metrics
Cellular voice call metrics provide the results of a data connection and voice call test to the server as configured. These tests are collected by default once every four hours, with advanced scheduling available on the configuration panel.
A singular cell_voice_metrics record is created for every test run on a Kallo. However, a subset of metrics recorded on each serving cell during the test is recorded in the cells field, or the associated cell_voice_cells type.
Field | Type | Guaranteed | Description |
band | smallint | True | Configured 3GPP Band Number ("All Bands" configuration returned as 0) |
call_answered_time | bigint | False | Time the voice call was answered (null if unanswered). Formatted as Unix Epoch (milliseconds) |
call_dropped | boolean | True | Indicates if a voice call was dropped. Mutually exclusive with call_failed and call_success |
call_dropped_reason | int | False | [Not currently implemented] |
call_end_time | bigint | True | Time the voice call was terminated, either by the KALLO or the target number |
call_failed | boolean | True | Indicates if a voice call was failed. Mutually exclusive with call_dropped and call_success |
call_failed_reason | int | False | [Not currently implemented] |
call_start_time | bigint! | True | Time the voice call was started by the KALLO |
call_success | boolean | True | Indicates if a voice call was successful. Mutually exclusive with call_dropped and call_failed |
cells |
| True | A cells entry |
install_location |
| True | A locations entry |
install_location_id | int | True | Identifier of the installation location where the data was collected |
plmn | string! | True | Public Land Mobile Network Identifier (MCC-MNC) |
rrc_messages | JSONB array | False | Ordered array of Radio Resource Control (RRC) messages collected during the test. |
serial_number | string! | True | Serial number of the device that collected the data |
signal | boolean | True | Indicates if the device was successfully able to connect to the carrier network on the given band. If false, the metrics will be null |
sip_messages | JSONB array | True | An array of all SIP messages captured by the device during a voice call |
site |
| True | A sites entry |
site_id | int | True | Identifier of the site where the data was collected |
sub_site |
| True | A sub_sites entry |
sub_site_id | int | True | Identifier of the sub-site where the data was collected |
target_number | string! | True | Phone number targetted by the voice call, formatted including the country code without the plus sign |
task_index | smallint! | True | Index of the configuration task that collected the data |
technology | string! | True | Configured 3GPP Technology ("All Technology" configuration returned as "ALL") |
time | timestamptz! | True | RFC3339 timestamp of the data collection time - NOTE: expressed in UTC |
SIP Messages
SIP messages are recorded per voice call in the cell_voice_metrics GraphQL type. Each sip_messages payload is a JSONB array that follows the below structure.
Field | Type | Guaranteed | Description |
time | smallint | True | Time the SIP message was recorded. Formatted as Unix Epoch (milliseconds) |
msgId | smallint | True | SIP message identifier |
rspCode | smallint | True | SIP message response code |
cmCallId | smallint | True | Identifier of the voice call that the SIP message refers to |
direction | string! | True | Direction of the SIP message (Network to UE or UE to Network) |
RRC Message Types
RRC messages are recorded per voice call, throughput, and ping test in the cell_voice_metrics and cell_throughput_metrics GraphQL type. Each rrc_messages payload is a JSONB array that may contain the following message types.
RRC Message | Description |
System Information Block 1 | Broadcast by the base station to provide cell identity, PLMN info, and scheduling details for other SIBs. |
System Information Block 2 | Broadcast by the base station to provide common and shared channel configuration information needed for UE access. |
RRC Connection Request | Sent by the UE to the base station to initiate an RRC connection, including the reason for the request. |
RRC Connection Setup | Sent by the base station to the UE, providing the radio resource configuration needed to establish the RRC connection. |
RRC Connection Setup Complete | Sent by the UE to confirm successful RRC connection establishment and to carry the initial NAS message. |
RRC Connection Reject | Sent by the base station to deny the UE's connection request, optionally including a wait time before retry. |
RRC Connection Reconfiguration | Sent by the base station to modify an existing RRC connection, such as adding/removing bearers or handing over to another cell. |
RRC Connection Reconfiguration Complete | Sent by the UE to confirm that the reconfiguration has been successfully applied. |
RRC Connection Reestablishment Request | Sent by the UE to request re-establishment of an RRC connection after radio link failure or handover failure. |
RRC Connection Reestablishment | Sent by the base station to allow the UE to re-establish the RRC connection, providing the necessary configuration. |
RRC Connection Reestablishment Reject | Sent by the base station to deny the UE's re-establishment request, forcing the UE to return to idle mode. |
RRC Connection Reestablishment Complete | Sent by the UE to confirm successful re-establishment of the RRC connection. |
P25 Metrics
GraphQL Type: cell_p25_metrics
P25 metrics are collected continuously without configuration on all KALLO units equipped with a P25 module, though the rate of responses has been limited to once every 3 minutes.
Field | Type | Guaranteed | Description |
band | smallint! | True | Radio frequency band used for the transmission. |
ber | smallint! | False | Bit Error Rate (%) |
configured | boolean | True | Blind / Configured P25 scan indicator |
frequency | Int! | True | Exact RF frequency in Hz being monitored |
install_location | locations | True | A |
install_location_id | Int | True | Identifier of the installation location where the data was collected |
lra | Int! | False | Location Registration Area |
p25_site_id | Int! | False | Identifier for a specific P25 trunked site. |
rfss | Int! | False | RF Sub-System |
rssi | smallint! | False | Received Signal Strength Indicator (dBm) |
serial_number | String! | True | Serial number of the device that collected the data |
signal | Boolean! | True | Indicates if the device was successfully able to connect to the p25 network on the given frequency. If false, the metrics will be null |
site | sites | True | A |
site_id | Int | True | Identifier of the site where the data was collected |
sub_site | sub_sites | True | A |
sub_site_id | Int | True | Identifier of the subsite where the data was collected |
system_id | Int! | False | P25 trunking system identifier |
time | timestamptz! | True | RFC3339 timestamp of the data collection time - NOTE: expressed in UTC |
wacn | Int! | False | Wide Area Communications Network ID for the P25 system. |
Events
GraphQL Type: events
An event is an occurrence of a significant event on a Kallo device. Events are generated by the Kallo device and may be delayed by a lack of connectivity. Events are generated for a variety of reasons, including power loss, hardware failure, and firmware update. A full list of represented events is available below.
Field | Type | Guaranteed | Description |
event | event | True | The details of this event. The details available will differ on the value of the event_type field. Possible combinations are documented in the Event Types section below. |
event_type | string | True | A string token denoting the type of this event. One of 'device_startup', or 'device_restart'. The details available will differ on the value of the `event_type` field. Possible combinations are documented in the Event Types section below. |
install_location_id | integer | True | Identifier of the installation location where the event was triggered. |
serial_number | string | True | Serial number of the device on which this event was triggered. |
site_id | integer | True | Identifier of the site where the event was triggered. A site can contain multiple sub-sites and installation locations |
sub_site_id | integer | True | Identifier of the sub-site where the event was triggered. A sub-site can contain multiple installation locations. |
time | timestamp | True | RFC3339 timestamp of the time the event was triggered on the device - NOTE: expressed in UTC |
Event Types
Event Type | Event Field | Field Type | Description |
Device_startup | sims |
| An array of sim objects describing the subscriber identity module cards inserted into this device. The SIMs are ordered as notated on the KALLO board. |
Device_restart | restartReason | string | The reason the device is restarting. |
Device_external_power_on | - | - | Event type returned whenever device detects external power through PoE input. |
Device_external_power_off | - | - | Event type returned whenever device stops detecting external power through PoE input. |
Device_cell_scan | nrCells |
| An array of all nearby NR cells ordered by time seen. Contains PCI (int), SCS (int), Band (int), PLMN (string), RSRP (int), RSRQ (int), and Channel (int). |
Device_cell_scan | lteCells |
| An array of all nearby LTE cells ordered by time seen. Contains PCI (int), Band (int), PLMN (string), RSRP (int), RSRQ (int), and Channel (int). |
SIMs Array Values
Each object describes either an embedded (MMF2) or micro (FF4) Subscriber Identity Module (SIM) in the Kallo device. If the SIM is an Embedded Universal Integrated Circuit Card (eUICC) SIM, the spn, imsi, hplmn and iccid fields will represent those properties of the active SIM profile at startup.
Field | Type | Description |
spn | string | Service Provider Name - The name of the carrier provided by the SIM card. |
imsi | string | International Mobile Subscriber Identity (IMSI) number of the SIM card. |
hplmn | string | Home Public Land Mobile Network (HPLMN) identifier of the SIM card. |
iccid | string | The Integrated Circuit Card Identification (ICCID) number of the SIM card. |
eid | string | Embedded Universal Integrated Circuit Card (eUICC) Identifier - The identifier of the eUICC itself. Only filled for some eUICC SIMs. |
dspn | string | Derived issuer Service Provider Name - The name of the issuer of the eUICC. Only filled for some eUICC issuers. |
Restart Reason Values
Value | Description |
| This device was restarted for an unknown reason. |
| This device was restarted following periodic device maintenance. |
| This device was restarted to undertake a firmware upgrade. |
| This device was restarted as the modem encountered an unrecoverable error and needed to be restarted. |
| This device was restarted as the device was unexpectedly unable to publish data for an extended period. |
LTE / NR Cells Array Values
Field | Type | Description |
pci | integer | Physical Cell Identifier |
scs | float | NR Only - Sub-Carrier Spacing (kHz). |
band | smallint | 3GPP Band Number |
plmn | string | Public Land Mobile Network Identifier (MCC-MNC) |
rsrp | float | Reference Signal Received Power (dBm) |
rsrq | float | Reference Signal Received Quality (dB) |
channel | integer | 3GPP Channel Number |
Sites
GraphQL Type: sites
A site is a physical location where Kallo units are installed like a building or complex of buildings. Sites can have multiple sub_sites.
Field | Type | Guaranteed | Description |
address_line1 | string | False | Address line 1 of the site |
address_line2 | string | False | Address line 2 of the site |
country | string | False | Country of the site |
id | bigint | True | Unique identifier for the site |
name | string | False | Site Name |
postal_code | string | False | Postal code of the site |
site_type | string | True | Type of site. One of 'building', 'stadium', 'compound', 'outdoor_location', or 'other' |
sub_sites |
| True | An array relationship |
suburb_city | string | False | Suburb or city of the site |
zone | string | False | State, province, zone or region of the site |
Sub-Sites
GraphQL Type: sub_sites
A sub-site is a physical location which forms part of a site where Kallo units are installed. Sub-sites can be floors, rooms, or even small buildings within a larger site. Each sub_sites record is associated with a parent site and can have multiple locations within it.
Field | Type | Guaranteed | Description |
id | bigint | True | Unique identifier for the sub-site |
locations |
| True | An array relationship |
name | string | True | Sub-site Name |
site | sites | True | A |
site_id | integer | True | Unique identifier for the site this sub-site is inside |
Locations
GraphQL Type: locations
A location is a physical installation point for a Kallo unit. Each locations record is associated with a parent site and sub_site.
Field | Type | Guaranteed | Description |
cell_rf_metrics |
| True |
|
cell_throughput_metrics |
| True |
|
device_serial_number | string | True | Serial number of the device installed at the location |
id | bigint | True | Unique identifier for the location |
installed_at | timestamp | True | Date and time the device was installed at the location |
name | string | True | Location Name |
pixel_x | integer | True | X coordinate of the location on the sub-site floorplan |
pixel_y | integer | True | Y coordinate of the location on the sub-site floorplan |
site |
| True | A |
site_id | bigint | True | Unique identifier for the site this location is inside |
sub_site |
| True | A |
sub_site_id | bigint | True | Unique identifier for the sub-site this location is inside |
Further Reading
We recommend consulting the following resources for additional information on our API technologies.