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).
language: Bash
release date: 2025-09-01
latest update: 2026-03-09
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.
instalation
To install the script, perform the following steps:
# Clone repository
git clone https://github.com/BuriXon-code/Termux-WiFi-map
# Enter durectory and change permissions
cd Termux-WiFi-map
chmod +x termux-wifi-map
# Move executable to $PATH
cp termux-wifi-map "$PREFIX/bin"
Previous versions of the script can be found in the OLD directory in the GitHub repository.
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.
Running the script without parameters switches it to interactive mode, where you can set the target mode and parameters using an easy-to-use selection menu.
The first parameter D enables debug mode, in which every script operation is displayed along with a verbal message about its progress. Disabled by default. Useful for troubleshooting non-standard script execution errors.
# Usage structure:
termux-wifi-map [D] [mode] [options]
R|-R|--run [options]
S|-S|--save [options]
C|-C|--cache [options]
V|-V|--check [options]
A|-A|--alias [options]
D|-D|--debug
N|-N|--nobanner
-h|--help
-v|--version
-i|--version-info
The first parameter D enables debug mode, in which every script operation is displayed along with a verbal message about its progress. Disabled by default. Useful for troubleshooting non-standard script execution errors.
interactive mode
This option eliminates the need to remember and type very long CLI commands for quick, one-time actions.
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 [0-3600s] (default 10s); 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) |
| -t | --timeout [value] | set the timeout for location retrieval [1-3600s] (default: 10s) |
| -e | --exit-on-fail | stop script on first termux-api error; useful when GPS/Wi-Fi signal is unstable |
Choosing the appropriate location provider can often be crucial: GPS works better where accuracy is important and the signal is strong and stable, while the network provider works better where GPS signal is unavailable, at the cost of measurement accuracy.
The --timeout parameter specifies how much time will be spent retrieving the location from termux-api: after this time, the script will either repeatedly try to restart the API, exit the script, or use the last remembered location (user’s choice).
The vibration engine allows you to decide whether generated vibrations should be Android vibrations triggered by termux-vibrate or Termux vibrations from the UNIX Bell character: termux-vibrate vibrates regardless of whether the app is in the background or foreground but takes longer, slowing down the script, while Bell executes very quickly but on some installations may also produce sound.
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:
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 |
The simplest way to open an exported KML file is to use the command termux-open file.kml with the Google Earth app installed.
KML placemark icon color meaning:
| 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 |
Listing data in a formatted view is nice and readable, but very slow. Displaying it as JSON is much faster.
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%.
alias mode -A
In this mode, you manage shortcuts and links to commands and parameters. The purpose is to allow creating your own parameters that simplify the use of the script and help avoid having to type long CLI commands.
You can use the following parameters:
You can use the following parameters:
| option | description |
|---|---|
| -a | --add [name] [options] | add a new alias with the given name and parameters |
| -l | --list [name] | list all saved aliases or only those containing the given pattern in the name along with their content/function |
| -e | --edit [name] | edit the selected alias in the default text editor |
| -d | --delete [name] | delete the selected alias |
| -r | --run [name] | run the selected existing alias |
| -b | --bin [name] | create a new symlink for the script in $PATH |
| -u | --unbin [name] | remove the created script symlink from $PATH |
When used without a parameter, it will run in interactive mode (aliases only; links are not supported).
For the script to create a symlink, it must be located in the $PREFIX/bin/ directory.
The symlink creation option creates actual items on the disk.
The symlink creation option creates actual items on the disk.
other options
The script also accepts the following options:
| option | description |
|---|---|
| D | -D | --debug | displays precise information about the execution of each command |
| N | -N | --nobanner | disables the banner display at startup |
| -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 |
| [aliasname] | run created alias (if exists) |
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"
# Create new loop-run alias
termux-wifi-map A -a run -c -d 0 -l
# Use alias
termux-wifi-map A run
termux-wifi-map run
# Create new script symlink
termux-wifi-map A -b wifimap
# Use symlink
wifimap -i
# 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.
[2.2] - Functionality update
This version introduces many improvements and simplifications for the user. The most important ones include:
- An option to interactively select the operating mode without the need to enter long CLI parameters;
- An option to create dynamic aliases/shortcuts for options, allowing you to avoid typing long CLI parameters;
- The ability to set a custom timeout for location retrieval from termux-api (useful when GPS signal is unstable);
- Added debugging options (first parameter: D).
[2.3] - Fixed one minor bug:
- Slight line shifting during interactive export to KML.
[2.4] - Fixed two reported bugs:
- Problem parsing args wifi -A <aliasname> for non-existent aliasname.
- -v | --version option started an infinite loop.
- Additionally: Checking if the alias aliasname is readable.
[2.5] - Added 'nobanner' option:
- An option has been added to disable the banner display on startup.
[2.6] - Fiz banner:
- Removed the delay between banner animation frames. The banner now renders faster.
[2.6.1] - Fix URL open:
- Minor change for opening project page.
[2.7] - Fix KML exporting:
- Fixed a user-noted bug where ANSI cleanup sequences were being written to the file during resize during export. A file descriptor change was necessary.
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.