nRF Cloud location

The nRF Cloud location library enables applications to submit cellular network and/or nearby Wi-Fi network information to nRF Cloud over MQTT to obtain device location. This library is an enhancement to the nRF Cloud library.


To use the nRF Cloud location service, you need an nRF Cloud account, and the device needs to be associated with your account.


Configure the CONFIG_NRF_CLOUD_LOCATION Kconfig option to enable or disable the use of this library.

Request and process location data

The nrf_cloud_location_request() function is used to submit network information to the cloud. If specified in the request, nRF Cloud responds with the location data. If the application provided a callback with the request, the library sends the location data to the application’s callback. Otherwise, the library sends the location data to the application’s nRF Cloud event handler as an NRF_CLOUD_EVT_RX_DATA_LOCATION event.

The nrf_cloud_location_process() function processes the received location data. The function parses the data and returns the location if it is found.

API documentation

Header file: include/net/nrf_cloud_location.h, include/net/wifi_location_common.h
Source files: subsys/net/lib/nrf_cloud/src/
group nrf_cloud_location



Omit the RSSI value when submitting a location request


Omit the channel value when submitting a location request


Minimum number of access points required by nRF Cloud


Omit the timing advance value when submitting a location request


Omit the RSRQ value when submitting a location request


Omit the RSRP value when submitting a location request


Omit the EARFN value when submitting a location request


Maximum value for timing advance parameter


typedef void (*nrf_cloud_location_response_t)(const struct nrf_cloud_location_result *const pos)

Cloud location result handler function type.

Param pos:

Location result.


enum nrf_cloud_location_type

Location request type.




int nrf_cloud_location_request(const struct lte_lc_cells_info *const cells_inf, const struct wifi_scan_info *const wifi_inf, const struct nrf_cloud_location_config *const config, nrf_cloud_location_response_t cb)

Perform an nRF Cloud location request over MQTT.

  • cells_inf – Cell info. The required network parameters are cell identifier, mcc, mnc and tac. The required neighboring cell parameters are E-ARFCN and physical cell identity. The parameters for time diff and measurement time are not used. The remaining parameters are optional; including them may improve location accuracy. To omit a request parameter, use the appropriate NRF_CLOUD_LOCATION_CELL_OMIT_ define. Can be NULL if Wi-Fi info is provided.

  • wifi_inf – Wi-Fi info. The MAC address is the only required parameter for each item. To omit a request parameter, use the appropriate NRF_CLOUD_LOCATION_WIFI_OMIT_ define. Can be NULL if cell info is provided.

  • config – Optional configuration of request. If NULL, fall back to default which is do_reply = true, hi_conf = false, and fallback = true.

  • cb – Callback function to receive parsed location result. Only used when config->do_reply is true or config is NULL. If cb is NULL, JSON result will be sent to the cloud event handler as an NRF_CLOUD_EVT_RX_DATA_LOCATION event.

Return values:
  • 0 – Request sent successfully.

  • -EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

  • -EDOM – The number of access points in the Wi-Fi-only request was smaller than the minimum required value NRF_CLOUD_LOCATION_WIFI_AP_CNT_MIN.


A negative value indicates an error.

int nrf_cloud_location_process(const char *buf, struct nrf_cloud_location_result *result)

Process location data received from nRF Cloud over MQTT or REST.

  • buf – Data received from nRF Cloud.

  • result – Parsed results.

Return values:
  • 0 – If processed successfully and location found.

  • 1 – If processed successfully but no location data found. This indicates that the data is not a location response.

  • -EFAULT – An nRF Cloud error code was processed.


A negative value indicates an error.

int nrf_cloud_location_scell_data_get(struct lte_lc_cell *const cell_inf)

Get the cellular network information from the modem that is required for a single-cell location request.

  • cell_inf – Cellular information obtained from the modem.

Return values:

0 – If cellular information was obtained successfully.


A negative value indicates an error.

struct nrf_cloud_location_result
#include <nrf_cloud_location.h>

Location request result.

Public Members

enum nrf_cloud_location_type type

The service used to fulfill the location request

double lat


double lon


uint32_t unc

The radius of the uncertainty circle around the location in meters. Also known as Horizontal Positioning Error (HPE).

enum nrf_cloud_error err

Error value received from nRF Cloud. NRF_CLOUD_ERROR_NONE on success.

struct nrf_cloud_location_config
#include <nrf_cloud_location.h>

Location request config.

Public Members

bool do_reply

If true, nRF Cloud will send the location to the device.

bool hi_conf

If true, uncertainty of result will be 95%, otherwise 68%.

bool fallback

If true, and location cannot be found, result will fall back to rough estimate based on the cell tower tracking area code. If false, will return an error if the cloud cannot provide a higher accuracy response.

group wifi_location_common

Common components for Wi-Fi location.



Size of Wi-Fi MAC address string: 2 chars per byte, colon separated


Print template for creating a MAC address string from a byte array

struct wifi_scan_info
#include <wifi_location_common.h>

Access points found during a Wi-Fi scan.

Public Members

struct wifi_scan_result *ap_info

Array of access points found during scan.

uint16_t cnt

The number of access points found during scan.