Introduction

Unwired Labs' Geolocation API locates IoT, M2M and other connected devices from visible cell towers and WiFi networks, without needing GPS.

Authentication

Each request to Unwired's APIs needs to be authenticated with an access token.

We recommend calling these APIs from your server backend rather than from public-facing code such as JavaScript running in a browser or a mobile app, since access tokens used this way are visible to anyone inspecting the request and currently have no referrer or IP restriction to limit their use elsewhere. If you need to call an API directly from a public-facing client, proxy the request through your own backend so the token itself is never exposed. Generate access tokens on your User Dashboard, create a separate token for each application, label them accordingly - e.g. "my server" - and reissue these tokens frequently to prevent misuse.

Endpoints

Unwired Labs' APIs are hosted in two regions, each with its own base URL. Choose the region that's geographically closer to your servers for minimal latency, then send requests to the endpoint for the specific API you're calling - see Available Endpoints below.

Regions

Region 1: United States (Northern Virginia)
https://us1.unwiredlabs.com

Region 2: Europe (Germany)
https://eu1.unwiredlabs.com

Available Endpoints

Replace <region> below with us1 or eu1.

Geolocation

The Geolocation API helps developers locate IoT, M2M and other connected devices anywhere in the world without GPS. The device or client first sends the API data about which Cellular networks and WiFi networks it can see nearby. The API then uses Unwired Labs' large datasets of Cell towers, WiFi networks backed by numerous algorithms to calculate and return the device's location.

Getting Started

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.

1. 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.

2. 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:

3. 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.

4. 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.

Usage

curl --request POST \
  --url https://us1.unwiredlabs.com/v2/process \
  --header 'Content-Type: application/json' \
  --data '{"token": "your_API_token","radio": "gsm","mcc": 310,"mnc": 410,"cells": [{"lac": 7033,"cid": 17811}],"wifi": [{"bssid": "00:17:c5:cd:ca:aa","channel": 11,"frequency": 2412}, {"bssid": "d8:97:ba:c2:f0:5a"}],"address": 1}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://us1.unwiredlabs.com/v2/process",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json"
  ),
  CURLOPT_POSTFIELDS => "{\"token\": \"your_API_token\",\"radio\": \"gsm\",\"mcc\": 310,\"mnc\": 410,\"cells\": [{\"lac\": 7033,\"cid\": 17811}],\"wifi\": [{\"bssid\": \"00:17:c5:cd:ca:aa\",\"channel\": 11,\"frequency\": 2412}, {\"bssid\": \"d8:97:ba:c2:f0:5a\"}],\"address\": 1}",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.unwiredlabs.com/v2/process"

payload = {
    "token": "your_API_token",
    "radio": "gsm",
    "mcc": 310,
    "mnc": 410,
    "cells": [{"lac": 7033, "cid": 17811}],
    "wifi": [
        {"bssid": "00:17:c5:cd:ca:aa", "channel": 11, "frequency": 2412},
        {"bssid": "d8:97:ba:c2:f0:5a"}
    ],
    "address": 1
}
response = requests.post(url, json=payload)

print(response.text)

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/process",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "processData": false,
  "data": "{\"token\": \"your_API_token\",\"radio\": \"gsm\",\"mcc\": 310,\"mnc\": 410,\"cells\": [{\"lac\": 7033,\"cid\": 17811}],\"wifi\": [{\"bssid\": \"00:17:c5:cd:ca:aa\",\"channel\": 11,\"frequency\": 2412}, {\"bssid\": \"d8:97:ba:c2:f0:5a\"}],\"address\": 1}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

POST requests can be sent to the following URL:

https://us1.unwiredlabs.com/v2/process

Replace us1 with a region that's closer to your location.

Sandbox

Use the sandbox to send sample Geolocation requests.

Request

A sample JSON request body

{
   "token":"your_API_token",
   "radio":"gsm",
   "mcc":310,
   "mnc":410,
   "cells":[
      {
         "lac":7033,
         "cid":17811
      }
   ],
   "wifi":[
      {
         "bssid":"00:17:c5:cd:ca:aa",
         "channel":11,
         "frequency":2412
      },
      {
         "bssid":"d8:97:ba:c2:f0:5a"
      }
   ],
   "address":1
}

Send the following data as a POST request in the JSON format. The token parameter is always mandatory. At least one of cells, wifi, gps or ip (with ipf fallback enabled) must also be provided so the API has data to locate against - see Cells, WiFi, GPS and Fallbacks for the requirements specific to each.

Cells

Each cells object contains information about a single Cell Tower.

• If you choose to include cells in your request, you can send 1 to 7 cell ID objects. If your device supports scanning for more than 7 cell objects, reach out to us and we'll increase this limit on your account. If more than the allowed limit are sent, only the first 7 cells will be considered.
• The first cell object has to be that of the serving cell, i.e. the tower the device is connected to. The others are neighbouring cell objects that are visible to the device.
• cid should be included on every cell object - without it, that cell is dropped from the request. Always include radio too - cid and lac are interpreted differently per radio type, so an omitted or incorrect radio can lead to a misread cell, especially for newer radio types like LTE and NR whose cid ranges overlap with others. All other parameters mentioned below are optional or recommended, as noted in the tables below.
• Parameters vary depending on the radio type. Supported radio types and their corresponding parameters are:
  
  
  

GSM - GSM, EDGE, GPRS, 2G

CDMA - 1xRTT, CDMA, eHRPD, EVDO_0, EVDO_A, EVDO_B, IS95A, IS95B

UMTS - UMTS, HSPA, HSDPA, HSPA+, HSUPA, WCDMA, 3G

LTE - LTE, 4G, CAT-M

NB-IoT (Private Beta)

New Radio - NR, 5G (Public BETA)

WiFi

Each wifi object contains information about a single WiFi Access Point.

Note: WiFi positioning is enabled for eligible deployments based on region and intended use.

• If you choose to include WiFi in your request, you must send a minimum of 2 and a maximum of 15 WiFi objects in 1 request. If more than 15 WiFi objects are sent, only the first 15 will be considered.

• If WiFi is not available, the wifi object can be omitted altogether.

• In accordance with our industry's privacy standards, when WiFi data is included, we require a minimum of 2 valid nearby Access Points to be sent.

Fallbacks

When the API can't locate the specific cells or networks a device reports, fallbacks let it return a coarser location instead of failing outright - using signals like nearby cells sharing the same LAC/TAC, or the device's IP address. They trade some accuracy for a higher chance of getting a result at all.

There are additional fallbacks and validations available for specific use-cases. Please drop our team a note to explore these.

GPS

Sample request with the gps object

{
    "cells": [{"lac": 7033, "cid": 17811, "radio": "gsm", "mcc": 310, "mnc": 410}],
    "wifi": [{"bssid": "00:17:c5:cd:ca:aa"}],
    "gps": [{
        "source": "gps",
        "lat": 39.56764858,
        "lon": -105.0073312,
        "accuracy": 30.0,
        "altitude": 100.0,
        "altitude_accuracy": 50.0,
        "speed": 10.2,
        "heading": 35.5,
        "timestamp": 1480510819000
    }],
    "gps_sandbox": 1,
    "geolocation": 0
}

Each gps object contains GPS location information about when and where the data in the request body was observed.

• You may send multiple gps objects if the device or client has multiple GPS locations.

• Always include "geolocation": 0 to the request body while contributing to ensure such requests are not charged and do not affect balance.

• Contact us before you begin sending gps data since this feature has to be enabled manually.

Notes

Address

The physical address of the returned location. Pass a value of 1 (default) to return address, 2 to return address components - street, city, postcode, etc - separately and 0 to suppress it. If we do not have an address for a location, the API will return Not available.

Border Threshold

The API validates location results against geographic boundaries. The border threshold parameter allows you to control how strictly this validation is applied:

• strict - Applies the strictest validation. Uses conservative filtering that may exclude some valid locations near boundaries (typically within a few hundred meters), which can result in more "No matches found" responses in these areas. Value: 0

• medium - Allows locations within approximately 5 KM buffer zone. Some returned locations may be in water bodies. Value: 1

• low - Allows locations within approximately 15 KM buffer zone. Some returned locations may be in water bodies. Value: 2

Other Notes

• Don't use leading zeroes in any of the numerical values without encapsulating that value in quotes, as it is invalid JSON and the request will be discarded with INVALID_REQUEST error.

• Use double quotes (") not single quotes (') to encapsulate strings as per JSON standards.

• The fields mcc, mnc are not mandatory at the top level and will be overridden by values provided in the cells objects.

• If the request contains only a CDMA element and doesn't have an MCC, the field mcc can be omitted. The field radio is mandatory. Set it to cdma.

• If the device has multiple radios or SIM cards, you can include radio, mcc, mnc in each cell object.

Response

Sample JSON response:

{
"status":"ok",
"balance":0,
"lat":39.56764454,
"lon":-105.00728197,
"accuracy":10,
"address":"High Line Canal Trail, Littleton, Douglas County, Colorado, 80129, United States of America"
}

The response will be a JSON object and may contain the following elements. Every location is calculated from our large, continuously-updated database of cell and WiFi observations - use the accuracy and fallback fields below to gauge confidence in a given result.

Address Detail

The API only returns components that have valid values for a location. Component town is normalized to city to make things simple. For more granular control, please use our Geocoding service - LocationIQ.

Components that would be returned are:

• area

• locality

• district

• county

• city

• state

• country

• country_code

• postal_code

Metadata

Sample response with the metadata object

{
    "status": "ok",
    "balance": 266647,
    "lat": 39.56764858,
    "lon": -105.00733121,
    "accuracy": 120,
    "metadata": {
        "gps": {
            "status": "ok",
            "gps_sandbox": 0
        }
    }
}

When metadata is enabled, the Geolocation API returns additional information about the request or response. For example, when a gps object is sent in the request, the API response will look similar to the one on your right.

Errors

{
   "status": "error",
   "message": "error_message",
   "balance": 0
}

When the API encounters errors, it responds with one of the following exact error messages in the message field:

• Token balance over; you have used up all your requests for today
• Invalid token
• No slots available
• Inactive device
• WiFi access not enabled
• Invalid request
• No matches found
• Internal server error
• Rate Limited Second

Error Details

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.

Geocoding

Forward Geocoding

Forward Geocoding is when you need to convert addresses (like a street address) into geographic coordinates (like latitude and longitude). You can then use these coordinates to do a number of things such as place markers on a map, calculate the distance between your office and those coordinates, send a drone over to that location, and so on.

Usage

<?php

$curl = curl_init('https://us1.unwiredlabs.com/v2/search?token=YOUR_API_TOKEN&q=SEARCH_STRING');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.unwiredlabs.com/v2/search"

data = {
    'token': 'YOUR_API_TOKEN',
    'q': 'SEARCH_STRING'
}

response = requests.get(url, params=data)

print(response.text)

curl --request GET \
  --url 'https://us1.unwiredlabs.com/v2/search?token=YOUR_API_TOKEN&q=SEARCH_STRING'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/search?token=YOUR_API_TOKEN&q=SEARCH_STRING",
  "method": "GET"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

GET requests can be sent to the following URL:

https://us1.unwiredlabs.com/v2/search?token=YOUR_API_TOKEN&q=SEARCH_STRING

Replace us1 with a region that's closer to your location.

Query Parameters

Response

The above command returns JSON structured like this:

{
  "status": "ok",
  "balance": 5000,
  "address": [{
    "lat": "40.6892474",
    "lon": "-74.0445404280149",
    "display_name": "Statue of Liberty, Hudson River Waterfront Walkway, Jersey City, Hudson County, New Jersey, 10004, United States of America",
    "road": "Hudson River Waterfront Walkway",
    "county" : "Hudson County",
    "city": "Jersey City",
    "state": "New Jersey",
    "country": "United States of America",
    "country_code": "US",
    "postal_code": 10004
  }, {
    "lat": "41.3438648",
    "lon": "-86.3111653",
    "display_name": "Statue of Liberty, Rue Guynemer, Odéon, 6e, Paris, Île-de-France, 75006, France",
    "road": "Rue Guynemer",
    "city": "Île-de-France",
    "state": "Paris",
    "country":"France",
    "country_code" : "FR",
    "postal_code": 75006
  }]
}

Reverse Geocoding

Reverse geocoding is the process of converting geographic coordinates into a human-readable address.

Usage

<?php

$curl = curl_init('https://us1.unwiredlabs.com/v2/reverse?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.unwiredlabs.com/v2/reverse"

data = {
    'token': 'YOUR_API_TOKEN',
    'lat': 'LATITUDE',
    'lon': 'LONGITUDE'
}

response = requests.get(url, params=data)

print(response.text)

curl --request GET \
  --url 'https://us1.unwiredlabs.com/v2/reverse?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/reverse?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE",
  "method": "GET"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

GET requests can be sent to the following URL:

https://us1.unwiredlabs.com/v2/reverse?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE

Replace us1 with a region that's closer to your location.

Query Parameters

Response

The above command returns JSON structured like this:

{
  "status": "ok",
  "balance": 5000,
  "address": {
    "lat": "41.3438648",
    "lon": "-86.3111653",    
    "display_name": "Southpark Lane, Littleton, Arapahoe County, Colorado, 80120, United States of America",
    "road": "Southpark Lane",
    "county": "Arapahoe County",
    "city": "Denver-Aurora-Lakewood",
    "state": "Colorado",
    "country": "United States of America",
    "country_code" : "US",
    "postal_code": 80120
  }
}

Notes

Address Object

Accept Language

Preferred language order for showing search results, overrides the value specified in the Accept-Language HTTP header. Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.

• List of Accept-Language codes: List of ISO 639-1 codes
• Use ISO 639-1 Code (2 characters). If the language is not available, use ISO 639-2 Code (3 characters) from here
• Default: en

Country Codes

Limit search results to a specific country (or a list of countries). Should be the ISO 3166-1 alpha-2 code. Here is a sample:

• List of accepted country codes: Officially assigned code elements

Errors

{
  "status": "error",
  "message": "Error message"
}

When certain types of errors are encountered, the API responds with one of the following error messages:

Timezone

The Unwired Labs TimeZone API provides time offset data for locations on the surface of the earth.

Usage

GET requests can be sent to the following URL:

https://us1.unwiredlabs.com/v2/timezone?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE

Replace us1 with a region that's closer to your location.

Query Parameters

<?php

$curl = curl_init('https://us1.unwiredlabs.com/v2/timezone?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.unwiredlabs.com/v2/timezone"

data = {
    'token': 'YOUR_API_TOKEN',
    'lat': 'LATITUDE',
    'lon': 'LONGITUDE'
}

response = requests.get(url, params=data)

print(response.text)

curl --request GET \
  --url 'https://us1.unwiredlabs.com/v2/timezone?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/timezone?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE",
  "method": "GET"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Response

The above command returns JSON structured like this:

{
  "status": "ok",
  "balance": 5000,
  "timezone": {
    "name": "Asia/Kolkata",
    "now_in_dst": 0,
    "offset_sec": 19800,
    "short_name": "IST"
  }
}

Timezone Response

Errors

{
  "status": "error",
  "message": "Error message"
}

When certain types of errors are encountered, the API responds with the following error messages:

Maps

LocationIQ Maps - an offering from Unwired Labs - offers beautiful and customizable map tiles to visualize location data on your websites and apps.

Static Maps

LocationIQ Static maps - an offering from Unwired Labs - are standalone images (in JPG or PNG format) that can be displayed on web and mobile devices without the aid of a mapping library or API. Our Static Maps API returns an image in response to an HTTP request. For each request, you can specify the map's location, size of the image, zoom level, type of map. You can also place markers or draw paths at locations on the map.

Balance

The Balance API provides a count of request credits left in the user's account for the day. Balance is reset at midnight UTC everyday (00:00 UTC).

For device accounts, this endpoint also returns the number of available device slots.

Usage

GET requests can be sent to the following URL. To prevent abuse, this endpoint is rate limited at 1 request per second.

https://us1.unwiredlabs.com/v2/balance?token=YOUR_API_TOKEN

Replace us1 with a region that's closer to your location.

<?php

$curl = curl_init('https://us1.unwiredlabs.com/v2/balance?token=YOUR_API_TOKEN');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo 'cURL Error #:' . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.unwiredlabs.com/v2/balance"

data = {
    'token': 'YOUR_API_TOKEN',
}

response = requests.get(url, params=data)

print(response.text)

curl --request GET \
  --url 'https://us1.unwiredlabs.com/v2/balance?token=YOUR_API_TOKEN'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/balance?token=YOUR_API_TOKEN",
  "method": "GET"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Query Parameters

Response

The above command returns JSON structured like this:

{
  "status": "ok",
  "balance_geolocation": 4500,
  "balance_geocoding": 4500,
  "balance_slots": -1
}

Errors

  {
    "status": "error",
    "message": "Error message"
  }

When certain types of errors are encountered, our API responds with the following error messages: