API Documentation

By sending data about WiFi access points and Cell towers near a mobile device,
you can locate it anywhere, anytime.

Sandbox Documentation Examples

Start with a free developer token.

API Sandbox


LocationAPI will return a location if you provide Cell Towers, WiFi APs near a device. View the API documentation here.

Request:
Response:
Location:

Usage

Requests are sent to any of the following endpoints:

Request body

Send the following data as a POST request in the 'JSON' format. (These fields are mandatory)
  • token - Your API token. If you don't have one, get one free here!
  • radio - Radio type of the device. Supported values are 'gsm', 'cdma', 'umts' and 'lte'. This field should be included for more accurate results.
  • 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.
  • 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.
  • cells - An array of cell ID objects. You can send 1 to 7 cell ID objects. The first cell ID 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.
    Parameters vary depending on the radio type:

    GSM - GSM, EDGE, GPRS, 2G

    • radio - Radio type of the device (Optional). Type: string; Value: gsm
    • lac - the Location Area Code of your operator's network. Type: integer; Range: 1 to 65533
    • cid - the Cell ID. Type: integer; Range: 0 to 65535
    • mcc - Mobile Country Code of your operator's network (Optional). Type: integer; Range: 0 to 999
    • mnc - Mobile Network Code of your operator's network represented by an integer (Optional). Type: integer; Range: 0 to 999.
    • signal - the Signal strength (RSSI) of the radio, measured in dBm (Optional). Type: integer; Range: -51 to -113
    • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: 0 to 31
    • tA - the Timing Advance value (Optional). Type: integer; Range: 0 to 63

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

    • radio - Radio type of the device (Optional). Type: string; Value: cdma
    • lac - the Network ID (NID). Type: integer; Range: 1 to 65534
    • cid - the Base ID (BID) or Station ID (SID). Type: integer; Range: 0 to 65535
    • mcc - Mobile Country Code of your operator's network (Optional). Type: integer; Range: 0 to 999
    • mnc - the System ID (SID). Type: integer; Range: 1 to 32767
    • signal - the Signal strength of the radio, measured in dBm (Optional). Type: integer; Range: -75 to -100
    • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: 1 to 16

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

    • radio - Radio type of the device (Optional). Type: string; Value: umts
    • lac - the Location Area Code of your operator's network. Type: integer; Range: 1 to 65533
    • cid - the Cell ID. Type: integer; Range: 0 to 268435455
    • mcc - Mobile Country Code of your operator's network (Optional). Type: integer; Range: 0 to 999
    • mnc - Mobile Network Code of your operator's network represented by an integer (Optional). Type: integer; Range: 0 to 999.
    • signal - the Signal strength (RSCP) of the radio, measured in dBm (Optional). Type: integer; Range: -25 to -121
    • psc - the Primary scrambling code (Optional). Type: integer; Range: 0 to 511
    • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: -5 to 91

    LTE - LTE, 4G

    • radio - Radio type of the device (Optional). Type: string; Value: lte
    • lac - the Tracking Area Code of your operator's network. Type: integer; Range: 1 to 65533
    • cid - the Cell ID. Type: integer; Range: 0 to 268435455
    • mcc - Mobile Country Code of your operator's network (Optional). Type: integer; Range: 0 to 999
    • mnc - Mobile Network Code of your operator's network represented by an integer (Optional). Type: integer; Range: 0 to 999.
    • signal - Signal strength (RSRP) of the radio, measured in dBm (Optional). Type: integer; Range: -45 to -137
    • tA - Timing Advance value (Optional). Type: integer; Range: 0 to 63
    • psc - Physical Cell ID on LTE (Optional). Type: integer; Range: 0 to 503
    • asu - the Arbitrary Strength Unit measured by the mobile phone (Optional). Type: integer; Range: 0 to 97
  • id (optional) - 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.,.
  • address (optional) - The physical address of the returned location. Pass a value of 1 (default) to return address, 2 to return address components separately and 0 to suppress it. If we do not have an address for a location, the API will return Not available. Type: integer; Values: 0 1 2; Default: 1
  • wifi (optional) - An array of WiFi objects visible to the device. You can send a minimum of 0 and a maximum of 15 WiFi objects in 1 request.
    • bssid - Base Service Set ID 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: :-.
    • channel - Channel the WiFi network is operating in (optional)
    • frequency - Frequency the WiFi network is operating in, measured in MHz (optional)
    • signal - Signal strength of the WiFi network, measured in dBm (optional). Type: integer; Range: -51 to -113
    • signalToNoiseRatio - The current signal to noise ratio, measured in dB (optional)
  • fallbacks (optional) - An array of fallback options to enable or disable.
    • all - Enable all available fall-backs.
    • 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.
    • lacf - Enable LAC fallback. If we are unable to locate a cell, we will return an approximate location based on nearby cells in our database. Enabled by default.
    • scf - Enable Short CID fallback. Adds support for devices that can only see 16-bit (short) CID of an UMTS 28-bit UTRAN CID. Enabled by default.
  • ip (optional) - If IP fallback is enabled, specify IP address of the device here. Defaults to IP address of device making the API call. Both IPv4 and IPv6 are supported.
  • bt (optional) - Choose what level of strictness to apply to border checks. Type: integer; Values: 0 1 2; Default: 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 (default)
    • 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
Notes:
  • Don't use leading zeroes in any of the above values without encapsulating that value in quotes, as it is invalid JSON and will return "Invalid Request".
  • 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.
{
    "token": "your_API_token",
    "radio": "gsm",
    "mcc": 310,
    "mnc": 410,
    "cells": [{
        "cid": 17811,
        "lac": 7033,
        "signal": -60,
        "tA": 13
    }, {
        "cid": 17812,
        "lac": 7033
    }, {
        "cid": 18513,
        "lac": 7033
    }],
    "wifi": [{
        "bssid": "00:17:c5:cd:ca:aa",
        "channel": 11,
        "frequency": 2412,
        "signal": -51
    }, {
        "bssid": "d8:97:ba:c2:f0:5a"
    }],
    "address": 1
}

Response body

The response will be a JSON object.
  • 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, such as:
    • house_number
    • road
    • area
    • locality
    • district
    • county
    • city
    • state
    • country
    • country_code
    • postal_code
    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
  • 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

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

Here's a successful output in JSON format:

{
    "status": "ok",
    "balance": 11,
    "lat": 39.568732,
    "lon": -105.002939,
    "accuracy": 732,
    "address": "Southpark Lane, Littleton, Arapahoe County, Colorado, 80120, United States of America"
    "address_detail": {
         "county": "Arapahoe County",
         "city": "Littleton",
         "state": "Colorado",
         "country": "United States of America",
         "country_code": "US",
         "postal_code": "80120"
     }
}

Here's an unsuccessful output:

{
    "status": "error",
    "message": "Invalid request",
    "balance": "0",
}

Example scripts