WebsiteDashboard
Geolocation

Getting Started

A four-step walkthrough for integrating the Geolocation API, from sending cell data to handling low-confidence results.

Integrating the Geolocation API comes down to three steps: send it what the device can see, read the location back, and decide what to do if the result isn't confident enough. Here's a walkthrough using a typical IoT tracker with a 2G (GSM) modem, which can see one serving cell tower and two neighbouring cells.

Pick a region and get a token

Sign up for a free token at my.unwiredlabs.com, then pick the region closest to your servers - us1 or eu1.

Send what the device can see

POST this request as JSON to https://<region>.unwiredlabs.com/v2/process. You only need to send the cells the device actually reports - a 2G tracker doesn't have WiFi or GPS, so this request only needs token, radio and cells:

{
  "token": "your_API_token",
  "radio": "gsm",
  "cells": [
    {"lac": 7033, "cid": 17811, "mcc": 310, "mnc": 410, "radio": "gsm"},
    {"lac": 7033, "cid": 17812, "mcc": 310, "mnc": 410, "radio": "gsm"},
    {"lac": 7033, "cid": 18923, "mcc": 310, "mnc": 410, "radio": "gsm"}
  ]
}

The first cell object should be the serving cell (the tower the device is connected to); the rest are neighbours. Always include radio on each cell - it's needed to correctly interpret values like cid and lac, which are read differently depending on radio type. See Cells for the full parameter list, including optional signal and ta values that improve accuracy if your modem exposes them.

If you're not sure where these values come from on your device, most GSM/2G modules expose them directly:

FieldTypically comes from
radioThe network type the modem is registered on (e.g. gsm, umts, lte) - usually available from the modem/OS alongside the network registration info
mcc / mncThe network operator's codes, often decoded from the device's IMSI or reported directly by the modem/OS
lacThe Location/Tracking Area Code, available via standard AT commands (e.g. AT+CREG? / AT+CGREG?) or your OS's cell-info API
cidThe Cell ID, reported alongside lac from the same source

Read the response

The API returns the location it calculated, along with a few fields that tell you how much to trust it:

{
  "status": "ok",
  "balance": 4999,
  "lat": 39.56764454,
  "lon": -105.00728197,
  "accuracy": 1200
}

accuracy and fallback together tell you how much to trust a result. A result with fallback present is based on nearby cells or networks rather than the ones reported, so treat it as less precise even if accuracy looks reasonable.

Decide what to do with a low-confidence result

If you're seeing fallback often, or accuracy is worse than you need:

  • Send more neighbouring cells if your device can see them - more visible cells generally means better accuracy.
  • Consider enabling an additional fallback like lacf if getting some result matters more than precision for your use case.
  • If nothing is available, No matches found is returned rather than a bad location - see Errors.

Best Practices

  • Send every visible cell or WiFi network, not just the strongest one. More visible networks generally means better accuracy, up to the limits of 7 cells and 15 WiFi objects per request.
  • Handle rate limits and server errors differently. Back off and retry on Rate Limited Second. Don't retry Token balance over... until your balance resets - retrying won't help. Internal server error is safe to retry, ideally with a short delay.
  • Turn on fallbacks deliberately, not by default. Fallbacks trade accuracy for a higher chance of getting a result - see Fallbacks for what each option does before enabling it for your use case.
  • Keep tokens server-side. See Authentication for guidance on handling tokens in public-facing apps.

On this page

1Pick a region and get a token2Send what the device can see3Read the response4Decide what to do with a low-confidence resultBest Practices