Endpoints

API requests can be sent to any of the following endpoints. Developers can choose the endpoint that’s geographically closer to their servers for minimal latency.

Region 1: US East (Northern Virginia)
https://us1.unwiredlabs.com/v2/<specific_api_endpoint>

Region 2: US West (San Francisco)
https://us2.unwiredlabs.com/v2/<specific_api_endpoint>

Region 3: Europe (France)
https://eu1.unwiredlabs.com/v2/<specific_api_endpoint>

Region 4: Asia Pacific (Singapore)
https://ap1.unwiredlabs.com/v2/<specific_api_endpoint>

Geolocation

The Geolocation API helps developers locate IoT, M2M and other connected devices anywhere in the world without GPS. The device 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.

Usage

curl --request POST \
  --url https://us1.unwiredlabs.com/v2/process.php \
  --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,"signal": -51}, {"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.php",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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,\"signal\": -51}, {\"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.php"

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,\"signal\": -51}, {\"bssid\": \"d8:97:ba:c2:f0:5a\"}],\"address\": 1}"
response = requests.request("POST", url, data=payload)

print(response.text)

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/process.php",
  "method": "POST",
  "headers": {},
  "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,\"signal\": -51}, {\"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.php

Replace us1 with an endpoint that’s closer to your location.

Sandbox

Use the sandbox to send sample Geolocation requests.

Request body

A sample 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,
         "signal":-51
      },
      {
         "bssid":"d8:97:ba:c2:f0:5a"
      }
   ],
   "address":1
}

Send the following data as a POST request in the JSON format. Only the token parameter is mandatory. All others are optional.

Parameter	Description	Type
token	Your API token. If you don’t have one, get one free here!	`string`
id	ID of the device, in case you are in a per-device plan. This could be any unique ID such as IMEI, IMSI, phone number, etc.,.	`string`
radio	Radio type of the device. Supported values are ‘gsm’, ‘cdma’, ‘umts’ and ‘lte’. This field should be included for more accurate results.	`string`
mcc	Mobile Country Code of your operator’s network represented by an integer (Optional). Range: 0 to 999. A list of possible MCCs can be found here.	`integer`
mnc	Mobile Network Code of your operator’s network represented by an integer (Optional). Range: 0 to 999. On CDMA, provide the System ID or SID, with range: 1 to 32767.	`integer`
cells	An array of cell ID objects. Read more.	`array`
wifi	An array of WiFi objects visible to the device. Read more.	`array`
address	The physical address of the returned location. Read more	`integer`
fallbacks	An array of fallback options to enable or disable. Read more	`array`
ip	IP address of device. Read more	`string`
bt	Specify level of strictness to apply to Borders. Read more	`integer`

You must replace token with your personal API key.

Cells

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.
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.
Except lac and cid all other parameters mentioned below are optional.
Parameters vary depending on the radio type. Supported radio types and their corresponding parameters are:

GSM - GSM, EDGE, GPRS, 2G

Parameter	Description	Type	Accepted
lac	the Location Area Code of your operator’s network.	`integer`	`1` - `65533`
cid	Cell ID	`integer`	`0` - `65535`
radio	Radio type of the device	`string`	`gsm`
mcc	Mobile Country Code of your operator’s network	`integer`	`0` - `999`
mnc	Mobile Network Code of your operator’s network represented by an integer	`integer`	`0` - `999`
signal	Signal Strength (RSSI)	`integer`	`-113` - `-51`
asu	Arbitrary Strength Unit	`integer`	`0` - `31`
ta	Timing Advance	`integer`	`0` - `63`

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

Parameter	Description	Type	Accepted
lac	Network ID (NID)	`integer`	`1` - `65534`
cid	Base ID / Station ID	`integer`	`0` - `65535`
radio	Radio type of the device	`string`	`cdma`
mcc	Mobile Country Code of your operator’s network	`integer`	`0` - `999`
mnc	System ID (SID)	`integer`	`1` - `32767`
signal	Signal Strength of the radio, measured in dBm	`integer`	`-100` - `-75`
asu	Arbitrary Strength Unit measured by the mobile phone	`integer`	`1` - `16`

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

Parameter	Description	Type	Accepted
lac	Location Area Code of your operator’s network.	`integer`	`1` - `65533`
cid	Cell ID	`integer`	`0` - `268435455`
radio	Radio type of the device	`string`	`umts`
mcc	Mobile Country Code of your operator’s network.	`integer`	`0` - `999`
mnc	Mobile Network Code of your operator’s network.	`integer`	`0` - `999`
signal	Signal Strength (RSCP) of your operator’s network.	`integer`	`-121` - `-25`
psc	Primary Scrambling Code	`integer`	`0` - `511`
asu	Arbitrary Strength Unit measured by the mobile phone	`integer`	`-5` - `91`

LTE - LTE, 4G

Parameter	Description	Type	Accepted	Required
lac	Tracking Area Code of your operator’s network.	`integer`	`1` - `65533`	yes
cid	Cell ID	`integer`	`0` - `268435455`	yes
radio	Radio type of the device	`string`	`lte`	yes
mcc	Mobile Country Code of your operator’s network.	`integer`	`0` - `999`	yes
mnc	Mobile Network Code of your operator’s network.	`integer`	`0` - `999`	yes
signal	Signal Strength (RSRP) of the radio, measured in dBm	`integer`	`-113` - `-51`	recommended
psc	Physical Cell ID on LTE	`integer`	`0` - `503`	recommended
asu	Arbitrary Strength Unit measured by the mobile phone	`integer`	`0` - `97`
ta	Timing Advance	`integer`	`0` - `63`

WiFi

You can send a minimum of 2 and a maximum of 15 WiFi objects in 1 request.
If WiFi is not available, wifi object can be omitted all together.
In accordance with our industry’s privacy standards we require a minimum of 2 valid nearby Access Points to be sent. If your use-case allows only 1 AP, reach out to us.

Parameter	Description	Type
bssid	Basic Service Set Identifier or MAC address of the Access Point. Typical format of a MAC address is xx-xx-xx-xx-xx-xx. However, the delimiter can be any of these when sent to the API: `:` or `-` or `.`	`string`
channel	Channel the WiFi network is operating in (optional)	`integer`
frequency	Frequency the WiFi network is operating in (MHz) (optional)	`integer`
signal	Signal Strength (RSSI) (optional)	`integer`
signalToNoiseRatio	The current signal to noise ratio, measured in dB (optional)	`integer`

Fallbacks

Parameter	Description	Type	Accepted	Default
all	Enable or disable all fallbacks.	`integer`	`0` or `1`	N/A
ipf	Enable IP address fallback. Specify IP address of the device in the “ip” field if it’s different from the device making the API call.	`integer`	`0` or `1`	`0`
lacf	Enable LAC fallback. If we are unable to locate a cell, we will return an approzimate location based on nearby cells in our database.	`integer`	`0` or `1`	`1`
scf	Enable Short CID fallback. Adds support for devices that can only see 16-bit (short) CID of an UMTS 28-bit UTRAN CID.	`integer`	`0` or `1`	`1`

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.

Type	Accepted	Default
`integer`	`0` or `1` or `2`	`1`

Border Threshold

You can choose what level of strictness to apply to border checks.

Type	Accepted	Default
`integer`	`0` or `1` or `2`	`1`

strict - Only locations inside land parcels will be allowed. Value: 0
medium - Locations near known land in the range of upto 5 KM will be included. Locations may lie in a water body. Value: 1
low - Locations near known land parcels in the range of upto 15 KM will be included. Locations returned may lie in a water body. 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

The above command returns JSON structured like this:


{
"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.

Parameter	Description
status	If the request is successful, `ok` is returned. Otherwise `error` is returned
message	Any additional information from the server is returned here
balance	This represents the remaining balance on the API token. Requests that return `error` are not charged and do not affect balance.
balance_slots	This represents the remaining balance of device slots. Requests that return `error` are not charged and do not affect balance. If `-1` is returned, then observe it as an error while calculating slots balance. This element will only exist if you are on a device plan.
lat	The latitude representing the location
lon	The longitude representing the location
accuracy	The accuracy of the position is returned in meters
address	The physical address of the location
address_details	The physical address of the location broken into sub-components. Read more
aged	Shown when the location is based on a single measurement or those older than 90 days or is an LAC fallback
fallback	Shown when the location is based on a fallback. Possible options include `ipf`, `lacf`, `scf`.

Address Details

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

Errors

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

Possible return values for message when status is error by category

Authentication error

Token balance over; you have used up all your requests for today
Invalid token - get a trial token by signing up for free

Parsing error

Invalid request
No cell ID provided
No location area code provided
No country code provided
No network data provided
No valid cell IDs or LACs provided
Invalid network code (mnc)
Invalid country code (mcc)

Unsuccessful

No matches found
No matches found, please try again shortly

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.php?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.php"

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.php?token=YOUR_API_TOKEN&q=SEARCH_STRING'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/search.php?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.php?token=YOUR_API_TOKEN&q=SEARCH_STRING

Replace us1 with an endpoint that’s closer to your location.

Query Parameters

Name	Description	Required
token	Authentication Token	Yes
q	Address which we want to search for	Yes
accept-language	Preferred language order for showing search results. Read more.	Optional
limit	Integer value to limit the number of returned results	Optional
countrycodes	Limit search to a list of countries. Read more.	Optional
viewbox	The preferred area to find search results. (left, right, top, bottom)	Optional

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
  }]
}

Name	Description
status	`ok` on success; `error` on error
balance	Balance left in the account
address	Array of Address objects found for the search query. Read more

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.php?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.php"

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.php?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.unwiredlabs.com/v2/reverse.php?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.php?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE

Replace us1 with an endpoint that’s closer to your location.

Query Parameters

Name	Description	Required
token	Authentication token	Yes
lat	Latitude of the location address	Yes
lon	Longitude of the location address	Yes
zoom	Zoom value lies between `0`-`18`. Level of detail required where `0` is country and `18` is house/building	Optional
accept-language	Preferred language order for showing search results. Read more.	Optional

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
  }
}

Name	Description
status	`ok` on success; `error` on error
balance	Balance left in the account
address	Address object found for the search query. Read more.

Notes

Address Object

Name	Description
lat	Latitude of the given location (decimal)
lon	Longitude of the given location (decimal)
display_name	Matched Address name for the given location
house_number	House Number
road	Road Name
neighbourhood	Neighbourhood
suburb	Suburb
city	City name (normalized form of city, town, village, hamlet)
county	County name (normalized form of county, state_district)
country	Country name
country_code	Country code
postcode	Postal code

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:

Country code	Country
`de`	Germany
`gb`	United Kingdom
`us`	United States of America

List of accepted country codes: Officially assigned code elements

Errors

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

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

Error Message	Description
`NO_TOKEN`	The request does not contain the user’s token
`INVALID_TOKEN`	The user’s token set is not valid
`INACTIVE_TOKEN`	The user’s token is not active
`INVALID_REQUEST`	The request does not contain the required input in the specified format
`RATELIMITED_DAY`	The user has reached the daily limit allocated
`RATELIMITED_MINUTE`	The user has reached the per-minute limit allocated
`RATELIMITED_SECOND`	The user has reached the per-second limit allocated
`NO_MATCHES`	The request is valid and we could not find a proper result
`UNKNOWN_ERROR`	Due to a server error, we are unable to serve your request. You can retry this request.

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.php?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE

Replace us1 with an endpoint that’s closer to your location.

Query Parameters

<?php

$curl = curl_init('https://us1.unwiredlabs.com/v2/timezone.php?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.php"

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.php?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE'

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

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

Name	Description	Required
token	Authentication token	Yes
lat	Latitude of the location	Yes
lon	Longitude of the location	Yes

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"
  }
}

Name	Description
status	`ok` on success; `error` on error
balance	Balance left in the account
timezone	Timezone object found for the location. Read more

Timezone Response

Name	Description
short_name	Short name of the Timezone
offset_sec	The offset from `UTC` (in seconds) for the given location. Considers `DST` savings.
now_in_dst	Represents whether the zone currently observing `DST` or not
name	Timezone name of the Location

Maps

Unwired Maps offers world-wide Street and Satellite maps. Our map tiles can be rendered by most open-source libraries. We recommend that you use Mapbox’s open-source GL javascript library for web projects and their iOS and Android SDKs for mobile projects to render our map tiles. Quick start with Mapbox >

If you need to support older browsers (IE 9 and older), you should Leaflet instead. Quick start with Leaflet >

Desktop Maps with Mapbox GL

We’ve added demos & code-samples for most popular use-cases here.

Desktop Maps with Leaflet

The raster maps below are rendered by the popular and open-source LeafletJS library. We’ve included a quick-start guide which will get you started on basics, including setting up a basic map, working with markers, polylines and popups, and dealing with events. For further reading, we recommend the comprehensive LeafletJS documentation.

Before writing any code for the map, you need to do the following preparation steps on your page:

Include Leaflet CSS file in the head section of your document:
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.0.3/dist/leaflet.css" />
Include Leaflet JavaScript file:
<script src="https://unpkg.com/leaflet@1.0.3/dist/leaflet.js"></script>
Include Unwired Leaflet Plugin JavaScript file:
<script src="https://tiles.unwiredmaps.com/js/leaflet-unwired.js"></script>
Put a div element with a certain id where you want your map to be:
<div id="map"></div>
Make sure the map container has a defined height, for example by setting it in CSS:
#map { height: 180px; }

Now you’re ready to initialize the map and do some stuff with it.

Setting up the map

Let’s create a map of the center of Denver (a city in Colorado, USA) with pretty Streets tiles. First we’ll initialize the key (if you don’t have one, get a trial token by signing up for free here). Now initialize the map and set its view to our chosen geographical coordinates and a zoom level:
var mymap = L.map('mapid').setView([51.505, -0.09], 13);
By default (as we didn’t pass any options when creating the map instance), all mouse and touch interactions on the map are enabled, and it has zoom and attribution controls.
Note that setView call also returns the map object — most Leaflet methods act like this when they don’t return an explicit value, which allows convenient jQuery-like method chaining.
Next we’ll add a tile layer to add to our map, in this case it’s a Streets tile layer. Creating a tile layer usually involves setting the URL template for the tile images and the maximum zoom level of the layer:
Make sure all the code is called after the div and leaflet.js inclusion. That’s it! You have a working map now.

Markers, circles and polygons

Besides tile layers, you can easily add other things to your map, including markers, polylines, polygons, circles, and popups. Let’s add a marker:
var marker = L.marker([39.73, -104.984]).addTo(map);
Adding a circle is the same (except for specifying the radius in meters as a second argument), but lets you control how it looks by passing options as the last argument when creating the object:
Adding a polygon is as easy:

Working with popups

Popups are usually used when you want to attach some information to a particular object on a map. Our map has a very handy shortcut for this:
Try clicking on our objects. The bindPopup method attaches a popup with the specified HTML content to your marker so the popup appears when you click on the object, and the openPopup method (for markers only) immediately opens the attached popup.
You can also use popups as layers (when you need something more than attaching a popup to an object):
Here we use openOn instead of addTo because it handles automatic closing of a previously opened popup when opening a new one which is good for usability.

Dealing with events

Every time something happens in map, e.g. user clicks on a marker or map zoom changes, the corresponding object sends an event which you can subscribe to with a function. It allows you to react to user interaction:
Each object has its own set of events — see documentation for details. The first argument of the listener function is an event object — it contains useful information about the event that happened. For example, map click event object (e in the example above) has latlng property which is a location at which the click occured.
Let’s improve our example by using a popup instead of an alert:

Leaflet Further reading

For more advanced configurations and options, please refer to Leaflet’s documentation.

Mobile SDKs

For mobile platforms, there are again 2 libraries you can use:

Mapbox-gl Native for Android & iOS (recommended)
OSMDroid for Android

Mapbox-gl Native SDK

For everything other than the most basic Android apps, you should use the Mapbox SDKs. We’ve created sample apps using these SDKs for both Android & iOS show-casing use-cases popular among our customers:

Android Sample App - Demo App | Source Code
iOS Sample App - Source

OSMDroid

Gradle dependency

  repositories {
      mavenCentral()
  }

  dependencies {
      compile 'org.osmdroid:osmdroid-android:5.6.5'
  }

Set a custom map tile source to Unwired Maps

  mMapView.setTileSource(new OnlineTileSourceBase("UnwiredMaps", 0, 18, 256, "",
      new String[] {
          "https://a-tiles.unwiredmaps.com/v2/obk/r/",
          "https://b-tiles.unwiredmaps.com/v2/obk/r/",
          "https://c-tiles.unwiredmaps.com/v2/obk/r/"
      }) {

            @Override
            public String getTileURLString(MapTile aTile) {
                return getBaseUrl() + aTile.getZoomLevel() + "/"
                            + aTile.getX() + "/" + aTile.getY() + ".png"
                            + "?auth=API_ACCESS_TOKEN";
            }
  });

In case you’d like to use OSMDroid, we’ve added sample code for you on the right:

For more info and documentation, please refer to osmdroid Wiki

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

Usage

GET requests can be sent to the following URL:

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

Replace us1 with an endpoint that’s closer to your location.

<?php

$curl = curl_init('https://us1.unwiredlabs.com/v2/balance.php?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.php"

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

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

print(response.text)

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

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

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

Query Parameters

Name	Description	Required
token	Authentication Token	Yes

Response

The above command returns JSON structured like this:

{
  "status": "ok",
  "balance_geolocation": int,
  "balance_geocoding": int
}

Name	Description
status	`ok` on success; `error` on error
balance_geolocation	Remaining balance left in the account for geolocation requests
balance_geocoding	Remaining balance left in the account for geocoding requests

Errors

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

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

Error Message	Description
`INVALID_TOKEN`	The user’s token set is not valid
`INACTIVE_TOKEN`	The user’s token is not active
`UNKNOWN_ERROR`	Due to an unknown error, we are unable to serve your request
`RATELIMITED_SECOND`	The user has exceeded the 1 request per-second limit for this endpoint

Endpoints

Geolocation

Usage

Sandbox

Request body

Cells

WiFi

Fallbacks

Notes

Address

Border Threshold

Other Notes

Response

Address Details

Errors

Geocoding

Forward Geocoding

Usage

Query Parameters

Response

Reverse Geocoding

Usage

Query Parameters

Response

Notes

Address Object

Accept Language

Country Codes

Errors

Timezone

Usage

Query Parameters

Response

Timezone Response

Maps

Desktop Maps with Mapbox GL

Desktop Maps with Leaflet

Setting up the map

Markers, circles and polygons

Working with popups

Dealing with events

Leaflet Further reading

Mobile SDKs

Mapbox-gl Native SDK

OSMDroid

Balance

Usage

Query Parameters

Response

Errors

Changelog