A cross‑platform Tkinter app for searching WiGLE (Wi‑Fi, Bluetooth, and Cellular), visualizing results on a map (with a draw‑your‑own bounding box), and exporting JSON‑driven CSV/KML. Includes right‑click context menus, “send to detail” shortcuts, batch detail runs from a text file, and an MCC/MNC lookup.
Why this matters: All exports are generated from the raw JSON responses (not the UI table), so your CSV headers and KML attributes reflect the full dataset across paginated pages.
- Features
- Screens & Tabs
- Installation
- Getting WiGLE API Credentials
- Running the App
- Using the Map & Bounding Boxes
- Exports (JSON → CSV/KML)
- Batch Detail Runs
- Tips, Limits, and Troubleshooting
- Screenshots
- FAQ
- Contributing
- License
- Wi‑Fi / Bluetooth / Cell basic searches with form fields, country dropdowns, and map bounding‑box tools.
- Right‑click context menu on results: copy ID/Name/Lat/Lon, or “Send to Detail” (auto‑fills detail tab).
- Detail tabs for Wi‑Fi/Cell and Bluetooth with batch file processing (
Browse…to load a text file). - Exports from raw JSON:
- Toggle JSON / CSV / KML independently.
- CSV headers are the union of all keys across pages.
- KML includes ExtendedData attributes for all keys.
- Automatic pagination using
searchAfter(when supported by the WiGLE endpoint). - Per‑run output folders with clean, consistent filenames.
- MCC/MNC lookup with normalization and CSV export.
- Credential manager (Settings → WiGLE Credentials) stores your API username/token in a local JSON file.
- Dark‑mode friendly layout and status pane.
- Form inputs for SSID/BSSID filters, country, and optional bounding box (map).
- Results table with right‑click copy and “Send to Detail” to pre‑fill the Wi‑Fi/Cell Detail tab.
- Export toggles (JSON/CSV/KML) affect this tab’s searches.
- Search for Bluetooth devices by name/MAC (and country if supported).
- Right‑click results to copy values or “Send to Detail” (Bluetooth Detail tab).
- Search cellular towers/operators with MCC/MNC filters and country limit.
- Supports
searchAfterpagination when available. - Right‑click → copy → send to detail.
- Single or batch detail lookups.
- Browse… to import a text file of IDs (e.g., BSSIDs, network IDs) and run them sequentially.
- Per‑run folder creation; all exports pulled from JSON, not the UI table.
- Single or batch Bluetooth detail lookups.
- Mirrors the behavior of the Wi‑Fi/Cell Detail tab for batch processing and exports.
- Enter MCC or MCC/MNC (wildcards supported where relevant).
- Normalizes common formats (e.g.,
mccmncvsmcc-mnc) and exports results to CSV.
- WiGLE Credentials: store API username and token into
~/.wigle_gui/credentials.json. - Export Options: toggle JSON, CSV, KML behavior (e.g., keep JSON pages, remove after CSV/KML, etc.).
- Paths: choose default output directory.
Works on Windows, macOS, and Linux with Python 3.10+.
-
Clone this repository:
git clone https://github.com/<your-org>/<your-repo>.git cd <your-repo>
-
Create & activate a virtualenv (recommended):
python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate
-
Install dependencies:
pip install -r requirements.txt
-
OS notes:
- Windows: no extra steps typically required.
- macOS: if you see SSL/cert errors with Tkinter/requests, run the “Install Certificates.command” that ships with python.org builds, or
pip install certifi. - Linux (Debian/Ubuntu): ensure Tk is available:
sudo apt-get update sudo apt-get install -y python3-tk
- Log into your WiGLE account and generate an API token.
- In the app, open Settings → WiGLE Credentials.
- Enter your username and API token; they’re stored locally at:
~/.wigle_gui/credentials.jsonYou can edit or delete this file anytime.
python wigleGUI.py- The main window opens in dark‑mode friendly colors.
- Pick a tab, set filters, draw a bounding box if needed, and click Search.
- Watch the Status pane for progress, page counts, and export info.
- Pan/Zoom the map to your area of interest.
- Use the draw rectangle tool to set the bounding box.
- The app will apply the rectangle’s min/max lat/lon to supported searches.
- Clear or redraw the box to adjust your search area.
- Enable JSON, CSV, and/or KML via the export toggles (top/right or Settings).
- The app always works from the raw JSON pages:
- CSV: builds a union of keys across all pages so no fields are lost.
- KML: puts all key/value pairs into ExtendedData (click a placemark to view attributes).
- JSON pages can be kept for auditing or removed automatically after CSV/KML generation (your choice in Settings).
Each run creates a clearly‑named output folder with a unique token:
<output-root>/
wifi-basic-<timestamp-or-id>/
wifi-basic-<id>-page_1.json
wifi-basic-<id>-page_2.json
wifi-basic-<id>.csv
wifi-basic-<id>.kml
The same convention is used for bluetooth-basic, cell-basic, and the detail tabs.
- In Wi‑Fi/Cell Detail or Bluetooth Detail, click Browse… to select a text file.
- Provide one identifier per line (e.g., BSSID, network ID, BT MAC).
- The app runs them sequentially, writes per‑run exports, and shows a final summary dialog (e.g., “Created X CSVs / Y KMLs”).
- The selected file path is displayed under the input to make it obvious which batch is running.
Batch file example:
aa:bb:cc:dd:ee:ff
11:22:33:44:55:66
77:88:99:aa:bb:cc
- Rate limits: WiGLE enforces request limits—use bounding boxes and filters to scope queries.
- Zero results:
- Check your filters (country, tech type, bbox).
- Try a larger bounding box or fewer filters.
- Pagination: The app uses
searchAfter(when available) to pull all pages automatically. - Map tiles: If tiles don’t load, verify you have internet access or a permissive network.
- CSV headers: Because headers are the union of keys across pages, expect many columns for rich datasets.
- KML size: Large runs → large KMLs. Consider filtering or splitting searches.
- macOS SSL: If you see
certificate verify failed, run the Install Certificates.command (bundled with python.org installs) or installcertifi.
Bluetooth Basic
Wifi Basic
Cell Basic
BT Detail
Wifi/Cell Detail
MCC-MNC Detail
Q: Where are my WiGLE credentials stored?
A: In a local JSON file at ~/.wigle_gui/credentials.json. You can edit or delete it anytime.
Q: Why export from JSON instead of the table I see on screen?
A: The UI table may truncate or omit fields. Exporting from raw JSON guarantees you capture all available fields from each page, which become CSV columns and KML attributes.
Q: Can I keep the JSON pages for auditing?
A: Yes. In Settings, enable “Keep JSON pages after export”. Otherwise, pages are deleted after CSV/KML are generated.
Q: How do batch runs work?
A: Prepare a text file with one ID per line (BSSID, network ID, or BT MAC). Use Browse… on the Detail tab to select it. The app iterates through each, exporting JSON/CSV/KML per run and shows a final count dialog.
Q: I’m seeing newline characters (\\n) in the Status pane—what gives?
A: The Status pane shows raw progress strings. Exports are unaffected. If you prefer cleaner status text, reduce verbosity in Settings or clear between runs; we trim common newline artifacts in recent builds.
Q: Will this exceed WiGLE rate limits?
A: It tries to be polite, but large batch/detail jobs can hit limits. Use country/bounding box filters and consider pausing between runs if needed.
Q: Does the map work offline?
A: Map tiles require internet. You can still run searches and exports without tiles, but drawing a bbox needs the map to be visible.
Q: My KML won’t open in Google Earth—file is huge.
A: Very large datasets produce very large KMLs. Try filtering more narrowly or splitting the run.
Issues and PRs are welcome! Please include:
- OS and Python version
- Steps to reproduce (inputs, tab, filters)
- Logs from the Status pane (copy/paste) and any stack traces
Apache-2.0