WiFi geolocation is a niche but critical piece of OSINT, often requiring juggling multiple databases and APIs to pinpoint physical locations from WiFi identifiers. geowifi tackles this pain point by querying seven public WiFi geolocation services in one go, aggregating results into JSON or interactive HTML maps. It’s a Python CLI tool designed for passive reconnaissance, meaning it never probes networks but relies solely on public data sources.
what geowifi does and how it works
At its core, geowifi is a Python-based OSINT reconnaissance tool that resolves WiFi BSSID (MAC addresses) or SSID (network names) into geographic coordinates. It queries seven different public WiFi geolocation databases: Wigle, Apple, Google, Milnikov, WifiDB, Combain, and Freifunk Carte. These services each maintain their own repositories of WiFi access point locations collected from various sources.
The tool aggregates responses from these sources and unifies them into a single JSON output or an interactive HTML map for easy visualization. This multi-source approach helps improve accuracy and coverage compared to relying on any single database.
Under the hood, geowifi handles the distinct authentication mechanisms required by some APIs: Wigle uses Basic Auth, Google and Combain require API keys. These credentials are centrally managed in a YAML configuration file, simplifying management and reuse.
The project is implemented purely in Python and operates as a command-line interface (CLI) tool. It also supports running within Docker containers, which eases deployment and environment setup.
An additional feature is a vendor lookup module that resolves MAC address prefixes (OUI) to their manufacturer names. This adds context to the raw BSSID data, useful in OSINT workflows.
technical strengths and design tradeoffs
What sets geowifi apart is its role as an aggregator of multiple WiFi geolocation data sources, all wrapped into a single tool with unified output formats. This consolidation saves time and effort for practitioners who otherwise need to query each database separately.
The codebase is structured to abstract each API behind a dedicated module or client class, making it easier to maintain and add support for additional services. The YAML-based configuration for API keys and credentials is a pragmatic choice, balancing flexibility with simplicity.
Handling diverse API authentication schemes in one place avoids scattering credential management across the codebase. This is a neat design for DX (developer experience), especially for a tool that integrates multiple external dependencies.
The interactive HTML map output is a practical touch, enabling quick visual inspection of geolocation results without needing external GIS tools.
However, the tool’s accuracy and utility are fundamentally constrained by the coverage and freshness of the underlying public databases. These databases can be incomplete or outdated in many regions.
The reliance on API keys for Google and Combain means users must obtain and manage these separately, which could be a setup hurdle for casual users.
Because geowifi operates passively without sending probe requests, it cannot discover new or hidden WiFi access points. It’s strictly limited to what’s already reported in public databases.
The code is Python-based, which is a solid choice for rapid development and ease of use, but it may not be the best fit for very high-volume or real-time workflows where compiled languages might offer performance benefits.
quick start
The project README provides clear installation instructions covering both local Python environment setup and Docker usage.
Start by cloning the repository and moving into its folder:
git clone https://github.com/GONZOsint/geowifi
cd ./geowifi/
For a local Python setup, create and activate a virtual environment and install dependencies:
virtualenv geowifi
source geowifi/bin/activate
python3 -m pip install -r requirements.txt
Alternatively, you can build the Docker image:
docker build -t geowifi:latest .
Run the Docker image without arguments to see the default behavior:
docker run --rm geowifi:latest
You can search by BSSID or SSID with the following commands:
docker run --rm geowifi:latest -s bssid <input>
docker run --rm geowifi:latest -s ssid <input>
This CLI usage is straightforward and suits typical OSINT workflows.
verdict
geowifi is a focused tool that addresses a specific pain point in WiFi geolocation OSINT: querying multiple databases simultaneously and consolidating results. It’s well suited for analysts and penetration testers who need passive geolocation data from WiFi identifiers without active probing.
Its Python codebase and Docker support make it accessible and easy to integrate into existing OSINT toolchains.
The main limitations to keep in mind are the reliance on public databases of variable quality and the need to manage API keys for some services. It’s not designed for active or real-time discovery, nor does it replace dedicated commercial geolocation services.
Overall, geowifi’s multi-source aggregation with unified output and vendor lookup functionality make it a practical tool for anyone working with WiFi OSINT data, provided they understand its passive nature and data source constraints.
# Sample YAML config snippet for API keys
wigle:
username: your_wigle_username
password: your_wigle_password
google:
api_key: your_google_api_key
combain:
api_key: your_combain_api_key
This central configuration shows how you manage credentials for multiple APIs in one place, simplifying setup and maintenance.
Related Articles
- LocationSimulator: system-level iOS location spoofing without jailbreak — LocationSimulator injects mock GPS coordinates into iOS devices via DeveloperDiskImage, enabling location spoofing witho
- X-osint: a modular Python CLI framework orchestrating multiple OSINT APIs — X-osint is a Python CLI tool aggregating OSINT data from multiple external APIs with a modular menu-driven interface, de
- GeoPulse: A lightweight self-hosted platform for GPS data to movement timeline transformation — GeoPulse turns raw GPS data from multiple sources into searchable timelines of stays and trips using automatic trip dete
- Trail Mate: Offline GPS and Dual LoRa Mesh Firmware for ESP32 Devices — Trail Mate is an embedded C firmware for ESP32 devices offering offline GPS navigation and dual LoRa mesh networking. It
→ GitHub Repo: GONZOsint/geowifi ⭐ 1,331 · Python