# nRF Cloud Location Services nRF Cloud Location Services give your devices fast, accurate, low-power location data. Without having to connect to multiple vendors and APIs, you can use our Location Services to improve accuracy of GNSS without relying on an unassisted GNSS receiver, get Single Cell or Multi Cell, Wi-Fi, or combine Wi-Fi and Cell into a Groundfix. You can now discover, configure, and start using Location Services directly from nRF Cloud, without leaving the platform to manage tokens or read separate docs. Sign Up [Create an nRF Cloud account](https://app.memfault.com/register?utm_source=docs-nordicsemi\&utm_medium=referral\&utm_campaign=LS-docs) to get started. ## What you get[​](#what-you-get "Direct link to What you get") nRF Cloud supports six service types: Assisted GNSS (A-GNSS) and Predictive GNSS (P-GNSS) for select Nordic Semiconductor cellular modems, single and multi-cell, Wi-Fi, and Groundfix which determines the most accurate fix between Wi-Fi and cell, all in one API. | Service | Typical accuracy | Power savings | GNSS required | Use when | | ----------------------- | ---------------- | ------------- | ------------- | --------------------------------------------------------------------------------- | | Assisted GNSS (A-GNSS) | Less than 10 m | Low | Yes | The device needs the most accurate fix and has a clear sky view. | | Predicted GNSS (P-GNSS) | Less than 10 m | Medium | Yes | The device has intermittent connectivity but still needs GNSS-grade accuracy. | | Single-cell (SCELL) | Less than 1000 m | High | No | The device is power-constrained or indoor, and coarse location is acceptable. | | Multicell (MCELL) | Less than 700 m | High | No | Several cells are usually in range and tighter cellular accuracy is needed. | | Wi-Fi | Less than 100 m | High | No | The device operates indoors with Wi-Fi access points in range. | | Groundfix | Less than 700 m | High | No | When you want the best fix determined from cell and Wi-Fi access points in range. | note Accuracy values are typical reference figures and not guaranteed. Reported `uncertainty` is the *horizontal positioning error* — the radius around the returned coordinates within which the device sits with roughly 68% probability. ![Location Services decision matrix](/assets/images/location-services-decision-matrix-c3cfa00ad6af8b86881cff15faa80b75.svg "Location Services decision matrix") ## Setting up Location Services [​](#setting-up-location-services-variantonly-variantmemfaultvia-apivariantonly "Direct link to setting-up-location-services-variantonly-variantmemfaultvia-apivariantonly") There are two ways to use Location Services. ### Send API requests from your own cloud (cloud-to-cloud)[​](#send-api-requests-from-your-own-cloud-cloud-to-cloud "Direct link to Send API requests from your own cloud (cloud-to-cloud)") Use this path when your backend talks to nRF Cloud on behalf of your fleet — for example, a proxy server that converts cell or Wi-Fi measurements into coordinates. * Authenticate with an [organization auth token (OAT)](/docs/platform/organization-auth-tokens.md) scoped to Location Services. * All requests go through the [REST API](https://api-docs.nrfcloud.com). ### Track devices in-platform (device-to-cloud)[​](#track-devices-in-platform-device-to-cloud "Direct link to Track devices in-platform (device-to-cloud)") Use this path when your devices talk directly to nRF Cloud — for example, an nRF91 Series device running the nRF Cloud multi-service sample. * Device authentication is handled by the nRF Connect SDK. Follow the [nRF Cloud](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/app_dev/device_guides/nrf91/nrf91_cloud_connecting.html) [ device setup guide](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/app_dev/device_guides/nrf91/nrf91_cloud_connecting.html) to onboard your device. * The device sends cell, Wi-Fi, or GNSS-assistance requests to nRF Cloud . ## Get started[​](#get-started "Direct link to Get started") ### Prerequisites[​](#prerequisites "Direct link to Prerequisites") * An nRF Cloud account. [Create one](https://app.memfault.com/register?utm_source=docs-nordicsemi\&utm_medium=referral\&utm_campaign=LS-docs) if you do not have one already. * Organization admin access in nRF Cloud . See [Access control: teams and roles](/docs/platform/access-control-teams-roles.md#organization-admin). ### Step 1: Sign in to nRF Cloud[​](#step-1-sign-in-to-nrf-cloud "Direct link to Step 1: Sign in to nRF Cloud") Go to [nrfcloud.nordicsemi.com](https://nrfcloud.nordicsemi.com) and sign in with your nRF Cloud credentials. ### Step 2: Find your organization and project slugs[​](#step-2-find-your-organization-and-project-slugs "Direct link to Step 2: Find your organization and project slugs") You need both slugs to construct Location Services API URLs. 1. In the left sidebar, click **Project Settings → General**. 2. Copy the **Organization Slug** and **Project Slug** values from the **Details** panel. ### Step 3: Run the Location Services setup guide[​](#step-3-run-the-location-services-setup-guide "Direct link to Step 3: Run the Location Services setup guide") nRF Cloud includes a guided wizard that explains your options and gets you to a working request in a few minutes. 1. Select **Location Services** from the project sidebar. 2. Step through the education and setup flow: 1. **Service Types.** Expand the SCELL, MCELL, Wi-Fi, and GNSS cards to compare accuracy, power, and prerequisites. 2. **Access Methods and OAT Setup.** Choose if you plan to send requests from your own cloud via API or connect devices in-platform. 3. **Plan and Pricing.** Review billing details and confirm the plan. 3. The app marks the wizard complete on the server, so it persists across browsers and reloads. Skipping the wizard Click **Skip for now** on any step to jump straight to the Location Services overview page. ### Step 4: Generate an organization auth token (cloud-to-cloud)[​](#step-4-generate-an-organization-auth-token-cloud-to-cloud "Direct link to Step 4: Generate an organization auth token (cloud-to-cloud)") You need to generate an Organization Auth Token (OAT). You do not need to leave the Location Services page to do this. 1. On the Location Services overview page, find the **Send API Requests** section. 2. Click **Generate token**. 3. Enter a description (for example, `Location Services`) and click **Create**. 4. Copy the token immediately and store it in a secrets manager. The token is shown only once. 5. (Optional) Click **Manage tokens** to view existing tokens or revoke one. warning Only organization admins can create OATs. If you are not an admin, the page shows a notice — ask your admin to complete this step. Tokens grant the same permissions as an organization admin via the API. Treat them like passwords: do not commit them to source control or share them in chat. Once the organization has at least one token, the **Generate token** button is hidden. Use **Manage tokens** to add more if you need to rotate. You can also create OATs directly from **Admin → Organization Auth Tokens → Create Token** if you prefer the settings route. ### Step 5: Make your first request[​](#step-5-make-your-first-request "Direct link to Step 5: Make your first request") The base URL for Location Services endpoints is: ``` https://api.nrfcloud.com/v1/organizations//projects//location ``` Replace `` with your **Organization Slug** and `` with your **Project Slug** from Step 2. The overview page shows a pre-filled sample cURL request using your actual slugs. You can copy it directly from there, or use the following Wi-Fi example: ``` curl -v -X POST \ https://api.nrfcloud.com/v1/organizations//projects//location/wifi \ -H "Authorization: Bearer $NRFCLOUD_OAT" \ -H "Content-Type: application/json" \ -d '{ "accessPoints": [ { "macAddress": "30:86:2d:c4:29:d0", "signalStrength": -45 }, { "macAddress": "3c:37:86:5d:75:d4", "signalStrength": -45 } ] }' ``` A `200 OK` response with a JSON body containing `lat` and `lon` confirms that your OAT and slugs are working. ## Service costs and plans[​](#service-costs-and-plans "Direct link to Service costs and plans") Location Services usage is metered per request type. See the [plan overview](https://nrfcloud.com/#/pricing) for current pricing. Cloud-to-cloud access requires a [Pro or Enterprise plan](https://nrfcloud.com/#/pricing). nRF Cloud stores location history for six months. ## Method details[​](#method-details "Direct link to Method details") The rest of this page covers each method in depth and shows how it works on the device. ### GNSS assistance (A-GNSS and P-GNSS)[​](#gnss-assistance-a-gnss-and-p-gnss "Direct link to GNSS assistance (A-GNSS and P-GNSS)") An unassisted GNSS receiver searches for satellites overhead, locks on, downloads navigation data at 50 bits per second, and computes a fix from the device's distance to each satellite. This is accurate but slow and power-hungry — cold-start time-to-first-fix can take minutes. [![Standard GNSS coordinate acquisition](/img/docs/nrfcloud/location-services-gnss-typical.svg)](/img/docs/nrfcloud/location-services-gnss-typical.svg) nRF Cloud sends the same assistance data over the LTE modem instead, which is orders of magnitude faster. [![How GNSS assistance works](/img/docs/nrfcloud/location-services-how-gnss-assistance-works.svg)](/img/docs/nrfcloud/location-services-how-gnss-assistance-works.svg) | Assistance type | Cloud access | Memory | Power | Time-to-first-fix | | --------------- | -------------------- | --------------------------- | ------------ | ------------------------------------------ | | Unassisted | Not required | None | Unrestricted | Unrestricted | | A-GNSS | Frequent (\~2 hours) | None | Restricted | Faster than unassisted and P-GNSS | | P-GNSS | Infrequent (days) | Stores predictions in flash | Restricted | Faster than unassisted, slower than A-GNSS | Choose **A-GNSS** when LTE is consistently available and you want the fastest fix. Choose **P-GNSS** when connectivity is sporadic — the device can still compute a fix offline using predicted ephemerides for several days into the future. A-GNSS includes an SCELL request as part of acquiring the fix. The SCELL data point shows up in the location history but is not billed. Time-to-first-fix terminology * **Cold start.** No prior knowledge of location, time, or navigation data. * **Warm start.** Approximate position, time, and almanac available — no current ephemeris. About 30 seconds. * **Hot start.** Recent fix in memory. Re-acquires the same satellites in seconds. A-GNSS and P-GNSS sit between hot and warm start. #### Use the Location sample[​](#use-the-location-sample "Direct link to Use the Location sample") The [Location sample](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/cellular/location/README.html) is the fastest way to demo core GNSS functionality. It uses REST. 1. In nRF Connect for VS Code, create the sample from the `nrf/samples/cellular/location` template. 2. Choose the `_ns` board option for the nRF9151 DK (`nrf9151dk/nrf9151/ns`). 3. Add the `pgps.conf` Kconfig fragment and `pgps.overlay` devicetree overlay if you want P-GNSS. A-GNSS is on by default. 4. (Optional) Add `CONFIG_MODEM_ANTENNA_GNSS_EXTERNAL=y` for an external GNSS antenna. 5. Build, flash, and open the device in nRF Terminal. The sample fetches assistance data and prints latitude, longitude, and accuracy. #### Use Modem Shell[​](#use-modem-shell "Direct link to Use Modem Shell") [Modem Shell](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/cellular/modem_shell/README.html) is a more configurable option for developers who need to customize the location flow. 1. Create the sample from the `nrf/samples/cellular/modem_shell` template. 2. Add `pgps.conf` and `pgps.overlay` for P-GNSS. 3. Uncomment `CONFIG_LTE_NETWORK_MODE_LTE_M_GPS=y` in `prj.conf` to enable the GNSS receiver. 4. Build and flash, connect to nRF Terminal, and run `location get --method gnss --gnss_cloud_nmea`. If you call the assistance endpoints directly instead of letting the SDK manage them, use [`GetAssistanceData`](https://api-docs.nrfcloud.com/#tag/GNSS/operation/GetAssistanceData) for A-GNSS and [`GetPredictedGpsAssistanceData`](https://api-docs.nrfcloud.com/#tag/Predicted-GPS/operation/GetPredictedGpsAssistanceData) for P-GNSS. ### Cellular location (SCELL and MCELL)[​](#cellular-location-scell-and-mcell "Direct link to Cellular location (SCELL and MCELL)") Cell-based location runs entirely in the cloud — the device sends information about the cells it can see, and nRF Cloud returns coordinates. [![How cell location works](/img/docs/nrfcloud/location-services-how-cell-works.svg)](/img/docs/nrfcloud/location-services-how-cell-works.svg) * **SCELL.** Uses only the serving cell. Lowest accuracy, lowest cost. Good for power-constrained or indoor devices. * **MCELL.** Uses the serving cell plus measured neighbor cells (`nmr`). More accurate, marginally more bandwidth. [![SCELL and MCELL](/img/docs/nrfcloud/location-services-scell-vs-mcell.png)](/img/docs/nrfcloud/location-services-scell-vs-mcell.png) #### Find cell parameters on the device[​](#find-cell-parameters-on-the-device "Direct link to Find cell parameters on the device") You need MCC, MNC, TAC, and ECI to construct a request. Get these with the Cellular Monitor app in nRF Connect for Desktop: 1. Open the Cellular Monitor app. 2. From the **Dashboard**, note the values: * `Mcc` and `Mnc` appear together as the PLMN ID. The first three digits are MCC; the last two or three are MNC. * `CellId` is the ECI. * `TAC` is a five-digit tracking area code. 3. For neighbor cells, open the debug log and search for `nmr`. Each entry has `earfcn` and `pci`. MCC/MNC validation Location Services validates MCC and MNC against the ITU-T E.212 ranges. Out-of-range values are rejected at the API. Pull the values straight from the modem rather than hand-coding them. #### Call the ground-fix endpoint[​](#call-the-ground-fix-endpoint "Direct link to Call the ground-fix endpoint") The [`GetGroundFix`](https://api-docs.nrfcloud.com/#tag/Ground-Fix/operation/GetGroundFix) endpoint combines cell and Wi-Fi positioning in one request. It tries Wi-Fi first, then falls back to cellular. ``` curl --location --request POST \ "https://api.nrfcloud.com/v1/organizations//projects//location/ground-fix" \ --header "Authorization: Bearer $NRFCLOUD_OAT" \ --header "Content-Type: application/json" \ --data-raw '{"lte":[{"mcc":'"$MCC"',"mnc":'"$MNC"',"tac":'"$TAC"',"eci":'"$ECI"'}]}' ``` Include an `nmr` array of neighbor cells to improve accuracy. The response includes `lat`, `lon`, `uncertainty`, and `fulfilledWith`. Results are written to the location history which you can access for up to six months through the [`GetLocationHistory`](https://api-docs.nrfcloud.com/#tag/Location-History/operation/GetLocationHistory). ### Wi-Fi location[​](#wi-fi-location "Direct link to Wi-Fi location") The device scans for nearby Wi-Fi access points, sends their MAC addresses to nRF Cloud, and receives coordinates derived from our dataset. Wi-Fi is often more accurate than cellular for indoor devices. There are two types of mac addresses: locally administered and globally administered (see [MAC address: Universal vs. local](https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local_\(U/L_bit\)) for more information). nRF Cloud accepts both types. tip Filter out mobile hotspots client side, these hotspots return unreliable positions because the access point itself moves. note At least two Wi-Fi access points are required for both the `/wifi` and `/ground-fix` endpoints for privacy reasons. A single access point combined with cell data is also accepted on `/ground-fix`. To locate a device from a single Wi-Fi access point, set `fallback=singleWifi` on a `/ground-fix` request. Single access point estimates are less accurate, so this setting must be requested explicitly. Use it if a coarse location is preferable to no location for your application. See the [Ground Fix best practices](/docs/best-practices/location-services-ground-fix.md#single-access-point-requests) and the [fallback query parameter](https://api-docs.nrfcloud.com/#tag/Ground-Fix/operation/GetGroundFix) for details. [![Wi-Fi location](/img/docs/nrfcloud/location-services-how-wifi-works.svg)](/img/docs/nrfcloud/location-services-how-wifi-works.svg) Supported hardware: * [nRF7002 DK](https://www.nordicsemi.com/Products/Development-hardware/nRF7002-DK), or * [nRF54L20 DK](https://www.nordicsemi.com/Products/Development-hardware/nRF54L20-DK) with [nRF7002 EB2](https://www.nordicsemi.com/Products/nRF7002) attached. Wi-Fi is used for both nRF Cloud connectivity and access-point scanning — no cellular link is required. #### Configure the Wi-Fi nRF Cloud sample[​](#configure-the-wifi-nrf-cloud-sample "Direct link to Configure the Wi-Fi nRF Cloud sample") 1. Open the [Wi-Fi nRF Cloud](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/wifi/nrf_cloud/README.html) sample from the `nrf/samples/wifi/nrf_cloud` template. Requires nRF Connect SDK v3.4.0 or later. 2. Create a build configuration for your target: * **nRF7002 DK:** select `nrf7002dk/nrf5340/cpuapp` as the board target. * **nRF54L20 DK + nRF7002 EB2:** select `nrf54l20dk/nrf54l20/cpuapp` as the board target and add `-DSHIELD=nrf7002eb2` under **CMake options**. 3. Build and flash. 4. Reset the device and watch it connect, scan, and request its location. ### Reverse geocoding[​](#reverse-geocoding "Direct link to Reverse geocoding") Convert coordinates into a human-readable address with [`GetGeocoding`](https://api-docs.nrfcloud.com/#tag/Geocoding/operation/GetGeocoding). The response includes at minimum the country and the state, province, or region. Higher-accuracy input coordinates (GNSS or Wi-Fi) produce higher-accuracy addresses than coarse cellular fixes. ### Location history[​](#location-history "Direct link to Location history") nRF Cloud stores every successful position request for six months. Pull the history with [`GetLocationHistory`](https://api-docs.nrfcloud.com/#tag/Location-History/operation/GetLocationHistory), or view it on the device page in nRF Cloud. ## API requirements[​](#api-requirements "Direct link to API requirements") All Location Services REST requests authenticate with an Organization Auth Token (OAT) passed as a Bearer token in the `Authorization` header. | Path | Authentication | Notes | | --------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cloud-to-cloud (REST) | OAT | Pro or Enterprise plan required. | | Device-to-cloud | Handled by nRF Connect SDK | Follow the [nRF Cloud device setup guide](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/app_dev/device_guides/nrf91/nrf91_cloud_connecting.html) to onboard your device. | For API requests, include your OAT as follows: ``` Authorization: Bearer $NRFCLOUD_OAT ``` For device-to-cloud integration, the [Location Service libraries in the nRF Connect SDK](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/networking/nrf_cloud.html#location_services) handle authentication automatically once the device is onboarded. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### The device cannot get a GNSS fix[​](#the-device-cannot-get-a-gnss-fix "Direct link to The device cannot get a GNSS fix") * Confirm the device meets the [GNSS prerequisites](#gnss-assistance-a-gnss-and-p-gnss). * Place the device near a window or outdoors. * Attach an external GNSS antenna if the device does not have an internal one. * Fall back to cellular while debugging. ### Cell location requests fail[​](#cell-location-requests-fail "Direct link to Cell location requests fail") * Open Cellular Monitor and confirm the device has a signal and the correct COM port is selected. * Wait two or three minutes after boot — connection setup is sometimes slow. * Verify network coverage with your carrier. * For iBasis SIMs, check the data balance under **Device Management > SIM Cards**. ### Coordinates do not match the actual device location[​](#coordinates-do-not-match-the-actual-device-location "Direct link to Coordinates do not match the actual device location") The returned coordinates are the center of an uncertainty circle. The device sits somewhere inside that circle with \~68% probability, not necessarily near the center. ### Uncertainty values are unusually large[​](#uncertainty-values-are-unusually-large "Direct link to Uncertainty values are unusually large") High uncertainty usually means one of: * Low cell density (rural). * The ECI is unknown and the service fell back to a tracking-area estimate. Tune behavior with the [fallback query parameter](https://api-docs.nrfcloud.com/#tag/Ground-Fix/operation/GetGroundFix). * The cells or access points in the request are physically spread out — for example, after a cell ID reassignment. ### MCELL produces the same result as SCELL[​](#mcell-produces-the-same-result-as-scell "Direct link to MCELL produces the same result as SCELL") Two reasons: * The neighbor cell overlaps so much with the serving cell that it does not move the estimate. * The neighbor cell is not yet in the nRF Cloud database, so only the serving cell was used. MCELL is still worth sending: it raises the odds of a valid result when the serving cell alone is unknown. ## Next steps[​](#next-steps "Direct link to Next steps") * Open the Location Services wizard in nRF Cloud to set up your organization. * Explore the [Wi-Fi nRF Cloud sample](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/wifi/nrf_cloud/README.html) for a reference device-to-cloud integration. * Try [hello.nrfcloud.com](https://hello.nrfcloud.com) for an out-of-the-box demo on the Thingy:91x. * See the [Organization Auth Tokens](/docs/platform/organization-auth-tokens.md) reference for managing and rotating tokens. * Browse the full [nRF Cloud](https://api-docs.nrfcloud.com) [ REST API reference](https://api-docs.nrfcloud.com) for all location endpoints. * Migrating from Unwired Labs? Read our [API Migration guide](/docs/legacy-nrfcloud/location-vendor-migration.md) to get started. * Need a hand? Contact [support](/docs/legacy-nrfcloud/support.md).