WaveDigger: Pinpointing Wireless Signals in Physical Space

WaveDigger is a specialized tool designed to translate wireless signal identifiers into geographic coordinates. By leveraging Apple's public Wireless Positioning System (WPS), users can uncover the physical locations of Wi-Fi access points and cellular infrastructure.

WaveDigger Logo

The project is developed using Next.js, TypeScript, and deck.gl to provide a high-performance, interactive mapping experience. You can access the live deployment at: https://wavedigger.networksurvey.app.

🚀 Core Capabilities

WaveDigger provides two primary methods for signal geolocation:

1. BSSID Geolocation

Users can input a Wi-Fi MAC address (BSSID) to find its approximate location. The tool features intelligent input validation that automatically formats the following patterns:

AA:BB:CC:DD:EE:FF
AA-BB-CC-DD-EE-FF
AABBCCDDEEFF

2. Cellular Tower Lookup

The application can locate LTE and 5G NR towers based on specific network parameters.

Signal Type	Required Parameters	Result Detail
LTE	MCC, MNC, TAC, Cell ID	Specific tower location
5G NR	MCC, MNC, TAC, NCI	Target cell + surrounding cluster cells

Additional Highlights

Interactive Visualization: Powered by deck.gl for fluid map rendering.
Search History: A local log of recent queries for rapid retrieval.
Responsive UI: Fully optimized for both mobile and desktop browsers.

🛠 Technical Architecture

WaveDigger acts as a bridge between the user and Apple's proprietary location services.

The Tech Stack

Frontend: Next.js 15 & TypeScript
Styling: Tailwind CSS
Mapping: react-map-gl and deck.gl
Backend: Next.js API routes acting as a proxy

Deep Dive: The Apple WLOC API

The application communicates with https://gs-loc.apple.com/clls/wloc using protobufs. A critical aspect of this integration is the coordinate handling. Apple transmits coordinates as int64 values with a precision of 8 decimal places.

Mathematically, the conversion from the API's integer format to a standard decimal coordinate is: $\text{Decimal Coordinate} = \frac{\text{API Integer Value}}{10^8}$

The system is versatile enough to support both the standard global endpoints and specific endpoints for the China region.

📖 Getting Started

Prerequisites

Node.js: Version 24+
Package Manager: npm

Installation & Setup

Clone the repository and install the necessary modules:
```
npm install
```
(Optional) To improve map tile quality, obtain a Mapbox token and add it to your .env.local file:
```
NEXT_PUBLIC_MAPBOX_TOKEN=your_token_here
```
Launch the development environment:
```
npm run dev
```
Navigate to http://localhost:3000 in your browser.

🧪 Testing & Limitations

To verify the application, locate a valid BSSID from your own wireless router. Enter the address in any supported format to see if Apple has indexed it.

[!IMPORTANT] ~~Every BSSID will be found.~~ Not all access points are present in Apple's database. Private or very recently installed hardware may not yield results.

🙏 Acknowledgments

WaveDigger stands on the shoulders of giants. This project is fundamentally based on the reverse engineering and research conducted by the apple-corelocation-experiments team.

Specifically, WaveDigger utilizes their:

Protobuf definitions for the WLOC API.

Detailed documentation of request/response formats.

Insights into coordinate encoding and the required initial byte prefixes for valid requests.

🗺 Future Roadmap

Data Export: Ability to save search results as .json or .csv.
TAC-Cluster View: A feature to browse all towers within a specific Tracking Area Code (TAC) without needing a specific Cell ID.

⚖️ Licensing

This software is released under the GNU Affero General Public License v3.0 (AGPL-3.0).

Note: If you host a modified version of WaveDigger as a network service, you are legally required to make your modified source code available to the users of that service.