christianrowlands/wavedigger

Source: https://github.com/christianrowlands/wavedigger

WaveDigger

Dig into wireless signals to discover their physical locations. WaveDigger helps you find Wi-Fi access points by their BSSID (MAC address) and cell towers (LTE and 5G NR) by their network parameters. Built with Next.js, TypeScript, and deck.gl for interactive map visualization.

A hosted version can be found at https://wavedigger.networksurvey.app.

Features

• BSSID Search: Enter a BSSID to find its approximate location
• Input Validation: Automatic formatting and validation of BSSID input
  • Supports formats: AA:BB:CC:DD:EE:FF, AA-BB-CC-DD-EE-FF, AABBCCDDEEFF
• Cell Tower Search: Look up LTE towers (MCC, MNC, TAC, Cell ID) or 5G NR towers (MCC, MNC, TAC, NCI). NR searches return the target cell plus surrounding NR cells in the same cluster.
• Interactive Map: Visualize results on a deck.gl-powered map
• Search History: Track recent searches for quick access
• Responsive Design: Works on desktop and mobile devices

Acknowledgments

🙏 This project would not be possible without the incredible work done by the apple-corelocation-experiments team.

WaveDigger is built upon their research and reverse engineering of Apple’s location services API. Specifically, we use:

• Their protobuf definitions for Apple’s WLOC API
• Documentation of the API endpoints and request/response formats
• Understanding of coordinate encoding and API behavior
• The initial bytes prefix required for valid requests

Their work in understanding and documenting Apple’s undocumented location services has made it possible for projects like WaveDigger to exist. Please check out their repository for the original research and additional tools for working with Apple’s location services.

Getting Started

Prerequisites

• Node.js 24+ and npm

Installation

1. Install dependencies:

npm install

1. (Optional) Add a Mapbox token for enhanced map tiles:
   • Get a token from Mapbox
   • Add it to .env.local:

   NEXT_PUBLIC_MAPBOX_TOKEN=your_token_here
   

Running the Development Server

npm run dev

Open http://localhost:3000 to view the application.

Technical Details

Architecture

• Frontend: Next.js 15 with TypeScript
• Map Visualization: deck.gl with react-map-gl
• Styling: Tailwind CSS
• API: Next.js API routes

Real Apple WLOC API

The application uses Apple’s real WLOC API to query BSSID locations. This implementation is based on the research and protobuf definitions from the apple-corelocation-experiments project.

The API implementation:

• Uses protobuf for communication with Apple’s servers
• Sends requests to https://gs-loc.apple.com/clls/wloc
• Handles coordinate conversion (Apple uses int64 with 8 decimal places)
• Supports both default and China region endpoints

Testing with Real BSSIDs

To test the app:

1. Find a real Wi-Fi BSSID (MAC address) from your router or access point
2. Enter it in any supported format
3. The app will query Apple’s database and show the location if found

Note: Not all BSSIDs are in Apple’s database. Newly deployed or private access points may not have location data.

Features Roadmap

• Export Results: Download search results as JSON/CSV
• TAC-cluster view: Browse every tower in a TAC without needing a specific Cell ID or NCI

License

WaveDigger is licensed under the GNU Affero General Public License v3.0. If you run a modified version of this software as a network service, the AGPL requires you to make your modified source code available to users of that service.