PHPackages                             lounisbou/cell-location - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. lounisbou/cell-location

ActiveLibrary[Utility & Helpers](/categories/utility)

lounisbou/cell-location
=======================

CellLocation uses API to retrieve estimation of the position of a mobile within a cell's coverage area. It can uses triangulation and enclosing circle algorithms to estimate the possible position of a device based on data from multiple cell towers.

v1.0.0(1y ago)121MITPHPPHP ^8.1

Since Sep 10Pushed 1y ago1 watchersCompare

[ Source](https://github.com/LounisBou/cell-location)[ Packagist](https://packagist.org/packages/lounisbou/cell-location)[ RSS](/packages/lounisbou-cell-location/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (3)Versions (4)Used By (0)

Cell Location API Integration
=============================

[](#cell-location-api-integration)

This project provides a service to determine the location (latitude and longitude) based on mobile cell tower information (MCC, MNC, LAC, CellID) using various APIs, such as:

- [OpenCellID](https://www.opencellid.org)
- [UnwiredLabs](https://unwiredlabs.com)
- [Google Maps Geolocation API](https://developers.google.com/maps/documentation/geolocation/overview)

It can uses **triangulation** and **enclosing circle algorithms** to estimate the possible position of a device based on data from multiple cell towers.

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Running Tests](#running-tests)
- [Future Improvements](#future-improvements)
- [Contributing](#contributing)
- [License](#license)

---

Installation
------------

[](#installation)

### Prerequisites

[](#prerequisites)

- PHP 8.0 or higher
- Composer (dependency management)
- An API key from OpenCellID, UnwiredLabs, and/or Google Maps Geolocation API

### Clone the repository

[](#clone-the-repository)

```
git clone https://github.com/LounisBou/CellLocation.git
cd CellLocation
```

### Install dependencies

[](#install-dependencies)

```
composer install
```

Configuration
-------------

[](#configuration)

Before using the project, you need to configure environment variables for API keys. You can do this by creating a `.env` file in the project root.

### Example `.env` file

[](#example-env-file)

```
OPENCELLID_API_KEY=your-opencellid-api-key
UNWIREDLABS_API_KEY=your-unwiredlabs-api-key
GOOGLE_API_KEY=your-google-maps-api-key
```

### Loading Environment Variables

[](#loading-environment-variables)

The project uses the **Symfony Dotenv** component to load environment variables. These environment variables are automatically loaded via the `Pest.php` file during tests or when running the project.

### Regenerating Autoloader

[](#regenerating-autoloader)

Ensure your classes are autoloaded by Composer. If you add or modify any classes, make sure to run:

```
composer dump-autoload
```

Usage
-----

[](#usage)

This project allows you to fetch the location from different services by simply providing cell tower information like MCC, MNC, LAC, and CellID.

### Example Usage

[](#example-usage)

#### Key Concepts

[](#key-concepts)

- **Cell Data**:

    - `CellData` stores the information of the device's interaction with the cell towers such as **MNC**, **MCC**, **LAC**, and **CellID**.
- **Cell Location**:

    - `CellLocation` objects store the physical location of the **cell antenna**, defined by **latitude**, **longitude**, and **accuracy** (distance range where the device might be relative to the tower).
- **Triangulation**:

    - Using data from multiple towers, the program estimates a device's position by calculating the intersection of circles defined by the cell tower locations and accuracy.
    - **Each circle** is centered at a **CellLocation**'s latitude and longitude, with a radius equal to the accuracy (distance to the device).
- **Intersection of Circles**:

    - The algorithm finds the intersection zone of the circles, calculates the **centroid** of the intersection, and uses the maximum distance between the centroid and the edges of the intersection zone to define the result possible position as a circle.
- **Smallest Enclosing Circle**:

    - The algorithm determines the smallest enclosing circle that intersects parts of all input circles. This circle's **center** represents the estimated device location, and the **radius** defines the zone of possible locations.
- **Enclosing Circle Algorithm**:

    - This algorithm calculates the smallest circle that encloses the intersection zone of all cell coverage areas.
    - `Center` geometric center of the intersection zone.
    - `Radius` distance from the center to the farthest point within the intersection zone.

#### Get CellLocation from CellData

[](#get-celllocation-from-celldata)

```