JUHE API Marketplace
Comprehensive Documentation

API Documentation

Everything you need to integrate and use our APIs effectively with guides, references, and examples

Cellid Geolocation API

5 min read

How to Get a Device's Location Using Cell Tower and WiFi Signals

As developers, we're often asked to provide location data. While GPS is the go-to solution, it's not always available or practical, especially for low-power IoT devices or apps running indoors. This is where Cell Tower and WiFi Geolocation becomes an essential tool in your toolkit.

This tutorial will guide you through the process of obtaining a device's location using cellular network information. We will cover what the key data points mean, how to conceptually retrieve them from a device, and how to use them with the Cellid Geolocation API to get a latitude, longitude, and accuracy radius.

Step 1: Understanding the Core Data Points

Unlike an IP lookup, a Cell ID lookup requires specific information from the device's radio modem. Understanding these parameters is the most critical part of the process.

  • mcc (Mobile Country Code): A three-digit code that uniquely identifies a country. (e.g., 310 for USA, 460 for China).
  • mnc (Mobile Network Code): A 2 or 3-digit code that identifies the mobile network operator within a country. (e.g., 260 for T-Mobile in the US).
  • lac (Location Area Code): Identifies a group of base stations within a network. When a device moves from one LAC to another, it must perform a location update.
  • cid (Cell ID): The unique ID of the specific cell tower (or sector of a tower) that the device is currently communicating with.
  • radio: The radio technology being used (e.g., gsm, wcdma, lte). This helps the API narrow down the correct tower database.

For higher accuracy, the API can also accept an array of nearby WiFi access points (wifiAccessPoints), each with its macAddress and signalStrength.

Step 2: How to Get Cell Information from a Device (Conceptual)

The exact method for retrieving this data depends entirely on the device's platform and hardware.

  • Disclaimer: This is a conceptual guide. Always refer to the official platform documentation for the most accurate and up-to-date implementation details.
  • On Android: You would typically use the TelephonyManager class. Methods like getNetworkOperator() can give you the MCC and MNC. The getAllCellInfo() method returns a list of CellInfo objects, from which you can extract CellIdentityLte, CellIdentityGsm, etc., to get the LAC, CID, and other required parameters.
  • On IoT/Embedded Devices: For custom hardware using a cellular module (like those from Quectel or SIMCom), you interact with the modem using an AT command set. For example, the AT+CREG? command (Network Registration Report) often returns the current LAC and CID. You must consult your specific modem's AT command manual.

Step 3: Making the API Call: A Python Example

Once you have retrieved the cell tower data from your device, you send it to the API. Here is a clear Python example using the requests library.

import requests
import json

def get_location_from_cell_tower(api_key, cell_data):
    """
    Fetches geolocation data from the Cellid Geolocation API.

    :param api_key: Your API key from hub.juheapi.com
    :param cell_data: A dictionary containing cell tower info.
    :return: The JSON response from the API or None on error.
    """
    api_url = "https://hub.juheapi.com/cellid/v1/query"

    # The request payload combines your key and the cell tower data
    payload = {
        "key": api_key,
        **cell_data
    }

    try:
        # This API typically uses a POST request for the payload
        response = requests.post(api_url, json=payload, timeout=10)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()

    except requests.exceptions.RequestException as e:
        print(f"API request failed: {e}")
        return None

# --- Example Usage ---
API_KEY = "YOUR_API_KEY"  # Replace with your key

# Example data retrieved from a device in the USA on T-Mobile's network
example_cell_data = {
    "radio": "lte",
    "mcc": 310,
    "mnc": 260,
    "lac": 12345,
    "cid": 67890
}

api_response = get_location_from_cell_tower(API_KEY, example_cell_data)

if api_response and api_response.get("code") == "OK":
    location_data = api_response.get("data")
    if location_data:
        print("Successfully retrieved location:")
        print(json.dumps(location_data, indent=2))

        # Extract the key data points
        lat = location_data.get("lat")
        lon = location_data.get("lon")
        accuracy = location_data.get("range") # Accuracy in meters

        print(f"\nCoordinates: {lat}, {lon}")
        print(f"Estimated Accuracy: Within {accuracy} meters.")
else:
    print("Failed to retrieve location.")
    if api_response:
        print(f"Reason: {api_response.get('msg')}")

Step 4: Interpreting the Response

The three most important fields in the response are:

  • lat (Latitude) and lon (Longitude): The calculated geographic coordinates of the device.
  • range (Accuracy Radius): This is a crucial field. Unlike GPS, which gives a precise point, Cell ID geolocation provides an approximation. The range value, given in meters, tells you the radius of a circle around the lat/lon point where the device is likely located. A smaller range means higher accuracy (typically achieved in dense urban areas with many towers or with supplemental WiFi data).

Conclusion

You now understand the fundamental data points for cell tower geolocation and how to use them with our API to get a reliable device location, even when GPS is out of the picture. This powerful technique unlocks new possibilities for low-power IoT and reliable mobile applications.

Ready to start building? Grab your free API key from hub.juheapi.com and dive into the full API Documentation for advanced parameters like WiFi-based lookups.