Request

Top-level Geolocation request parameters, fallback options, address and border-threshold settings.

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.

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
}

Parameter	Description	Type	Required
token	Your API token. If you don't have one, get one free here!	`string`	yes
id	ID of the device, in case you are in a per-device plan. This could be any unique string such as an IMEI, IMSI, phone number or a hash of any of the previous values, etc. Maximum accepted length is 20 chars, and values should only be alphanumeric (a-z, 0-9)	`string`	no
radio	Radio type of the device. Supported values are `gsm`, `cdma`, `umts`, `lte`, `nbiot` and `nr`. Always include this for accurate results - values like `cid` and `lac` are interpreted differently depending on radio type, so an omitted or wrong `radio` can lead to a misread cell. See Cells for per-cell usage.	`string`	no
mcc	Mobile Country Code of your operator's network represented by an integer. Range: 0 to 999. An updated list of MCCs can be found here.	`integer`	no
mnc	Mobile Network Code of your operator's network represented by an integer. Range: 0 to 999. On CDMA, provide the System ID or SID, with range: 1 to 32767.	`integer`	no
cells	An array of cell ID objects visible to the device. Read more.	`array`	no
wifi	An array of WiFi objects visible to the device. Read more.	`array`	no
ip	IP address of device. Read more	`string`	no
gps	An array of `gps` objects that contains GPS information about where the request data was scanned. Read more	`array`	no
gps_sandbox	Must be set to 0 to submit data and 1 to test in sandbox. Defaults to 1.	`integer`	no
geolocation	Must be used along with `gps` object. When set to 0, response will not include any location information and requests are not charged and do not affect balance. Defaults to 1.	`integer`	no
address	The physical address of the returned location. Read more	`integer`	no
accept-language	Preferred language order for showing address results. Read more	`string`	no
fallbacks	An array of fallback options to enable or disable. Lets the API return a coarser location instead of failing outright when it can't locate the reported cells or networks directly. Read more	`array`	no
bt	Controls how strictly locations are validated against geographic boundaries. Read more	`integer`	no
metadata	Additional information about the request or response, if any, is returned if set to 1. Defaults to 0. Read more	`integer`	no

You must replace token with your personal API key.

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.

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	Setting this to `1` enables LAC fallback. If we are unable to locate a cell, we will return an approximate location based on nearby cells that share the same LAC / TAC in our database. Setting this to `2` will return only a fallback location even if a more accurate location exists.	`integer`	`0` to `2`	`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`

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

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

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

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

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

All validation modes have limitations and may return locations outside expected boundaries. The strict mode minimizes this but cannot eliminate it entirely, while medium and low modes use progressively larger buffer zones.

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.

Fallbacks

Notes

Address

Border Threshold

Other Notes

On this page