Termux-WiFi-map
A script that comprehensively collects data on nearby Access Points (Wi-Fi) along with the location of their scanning, saves it, and allows exporting the collected data to JSON, CSV, or KML (support for points on a map).
release date: 2025-09-01
latest update: 2025-12-15
about
Termux-WiFi-map is a comprehensive tool for the Termux environment that allows you to easily build a database of Wi-Fi networks in your area for OSINT purposes. The script, written in Bash, is fully compatible with the latest versions of Termux.
The script has advanced error handling during operation, so any missing functionality/errors in Termux:API (termux-location) do not interrupt the script.
Additionally, the script is characterized by high readability and ease of use.
The script has advanced error handling during operation, so any missing functionality/errors in Termux:API (termux-location) do not interrupt the script.
Additionally, the script is characterized by high readability and ease of use.
The script is intended only for building access‑point databases for personal use and/or educational purposes. Misuse may be punishable by law. I am not responsible for how the script is used. Consult your local regulations if you need more information.
operating modes
The tool's operating modes and the parsing of accepted parameters have been implemented modularly – the first script parameter determines the mode of operation (saving, cache operations, file validation) and how the remaining parameters and options will be read.
# Usage structure:
termux-wifi-map [mode] [options]
R|-R|--run [options]
S|-S|--save [options]
C|-C|--cache [options]
V|-V|--check [options]
-h|--help
-v|--version
-i|--version-info
scan mode -R
In this mode, the script works by retrieving the location, scanning nearby Wi-Fi networks, parsing, and saving their data to its memory.
You can use the following parameters:
You can use the following parameters:
| option | description |
|---|---|
| -p | --provider [option] | choose location provider [gps|network|passive] (default: gps); gps is more accurate but slower and less reliable, network is faster but less precise |
| -d | --delay [value] | set delay between scans in continuous mode [1-3600|none] (default: 10); actual delay may vary by 1–3 seconds depending on conditions |
| -c | --countinuous | enable continuous scanning mode until manually stopped |
| -q | --quiet | minimal output mode; vibrations and scan data printing disabled |
| -v | --haptic-engine [option] | choose vibration engine [termux|bell] (default: termux); termux is reliable but slow, bell may act as sound on some systems |
| -l | --last-location | choose whether to scan networks using the saved location when GPS is unavailable (e. g. in buildings) |
| -e | --exit-on-fail | stop script on first termux-api error; useful when GPS/Wi-Fi signal is unstable |
save mode -S
In this mode, it is possible to export the previously found Access Point data to a file format of your choice.
You can use the following parameters:
You can export to the following file formats:
KML placemark icon color meaning:
You can use the following parameters:
| option | description |
|---|---|
| -n | --name [name] | output file name without extension; extension is added automatically |
| -f | --format [option] | output format: json, pjson, jsonl, csv, kml |
| -o | --override | allow overwriting the output file |
| -k | --kml-name [name] | set custom KML document name displayed in KML applications |
| format | description |
|---|---|
| JSON | classic JSON format |
| PJSON | pretty formatted JSON |
| JSONL | newline-delimited JSON |
| CSV | comma-separated values |
| KML | XML format for mapping points and routes |
| icon | meaning |
|---|---|
 |
open network |
 |
locked network [WPA/PSK] |
 |
cached location/Termux:API error |
cache mode -C
In this mode, you can work with the collected Access Point database, e.g., listing saved records, clearing the cache, searching the cache.
You can use the following parameters:
You can use the following parameters:
| option | description |
|---|---|
| -c | --count | display the number of data records |
| -l | --list | display all collected data (formatted list of known APs) |
| -j | --json | display collected data as Pretty JSON |
| -s | --search [patterns] | search for matching patterns in the database; patterns separated by commas, e.g. "Wi-Fi,AP" |
| -p | --purge | clear the entire database |
validation mode -V
In this mode, the script will check the structure of a user-selected file (JSON, Pretty JSON, JSONL, CSV, or KML) to verify correctness and the absence of errors.
You can use the following parameters:
It works with the following file formats:
You can use the following parameters:
| option | description |
|---|---|
| /path/to/file | path to the file to validate; script auto-detects file type |
| format | description |
|---|---|
| JSON | check structure and readability |
| PJSON | check structure and readability |
| JSONL | check structure and readability |
| CSV | check record count and parameter count |
| KML | check tag count, data correctness, and placemark icons |
If the file or its structure becomes corrupted, the script will attempt to guess what data the file may have contained.
However, this validation should not be trusted 100%.
However, this validation should not be trusted 100%.
other options
The script also accepts the following options:
| option | description |
|---|---|
| -h | --help | display information about usage and tool options |
| -v | --version | display the tool name and version number |
| -i | --version-info | display detailed information, metadata, and legal info about the tool |
usage examples
# Single run:
termux-wifi-map -R
# Continuous scanning with GPS location and 60s delay:
termux-wifi-map R -c -p gps -d 60
# Continuous scanning without delay in quiet mode:
termux-wifi-map --run -d none -q
# Exporting the database to the file.csv:
termux-wifi-map -S -n file -f csv
# Exporting the database to the access_points.kml with permission to override the file:
termux-wifi-map S -n access_points -f kml --override
# Listing all known APs in JSON format:
termux-wifi-map C --json
# Searching for records containing the phrases "Wi-Fi" and "AP":
termux-wifi-map --cache --search "Wi-Fi,AP"
# Validating the structure of file.jsonl:
termux-wifi-map -V ./file.jsonl
compatibility
The script is compatible with all current Termux versions and dependent packages.
It requires the installation of a small number of dependent packages (jq, termux-api, Termux:API on Android, awk).
The tool requires the termux-api package (installed via pkg/apt) and the Termux:API application (on Android).
The script works with Termux:API version 0.53.0 or higher.
It requires the installation of a small number of dependent packages (jq, termux-api, Termux:API on Android, awk).
The tool requires the termux-api package (installed via pkg/apt) and the Termux:API application (on Android).
The script works with Termux:API version 0.53.0 or higher.
Without an installed and properly configured Termux:API app and the termux-api package, the script will not work at all.
The script produces unstable output. It is not recommended to pipe its stdout into other programs or processes.
changelog
[1.0] - Initial release
This is the very first official release of Termux-WiFi-map.
It marks the initial version of the tool, providing basic WiFi scanning, data saving, and validation features.
Future updates will expand functionality and improve usability.
[2.0] - Major functionality update
This is the second release of the script which, due to the number of introduced changes, received a separate major release.
This version introduces many improvements, fixes errors and imperfections detected in the previous version and adds a range of new options and functionalities.
The most important implementations in this version include:
- Fixing errors during data parsing by jq - in some Termux and termux-api installations the termux-api command incorrectly intercepted standard streams which caused corrupted JSON to be sent to jq;
- Ability to choose a haptic engine - the user can select the vibration engine (termux-api or system bell) through appropriate CLI parameters;
- Ability to list saved Access Points in raw JSON form - the previous formatted output generated for a very long time for large AP databases;
- Ability to search the collected database - the user can search for specific phrases or strings in the database;
- Ability to export specific searches - the user can export to one of the available formats those APs that were previously found.
[2.1] - Functionality update
This update adds an option to use the previously known location if a location update fails. Useful, among others, when scanning in buildings.
license
This project is licensed under GPL v3.0. You are free to use, modify, and distribute the script under the same license, provided that any distributed version, modified or unmodified, includes this license and source code availability. Any derivative works must also be released under GPL v3.0.