📡💘🌎 | geowifi

Search WiFi geolocation data by BSSID and SSID on different public databases.

💾 Databases

Wigle	Apple	Google	Milnikov
WifiDB	Combain	Freifunk Carte	❌ (Discontinued) OpenWifi

---

✔️Prerequisites

• Python3.
• In order to display emojis on Windows, it is recommended to install the new Windows terminal.

---

🔑 APIs and configuration file

The tool has a configuration file in the gw_utils folder called config.yaml. Each of the configuration parameters and how to obtain the necessary information is explained below:

• wigle_auth:

In order to use the Wigle service it is necessary to obtain an API and configure the gw_utils/config.yaml file replacing the value of the "wigle_auth" parameter for the "Encoded for use" data provided by Wigle.

• google_api:

In order to use the Google Geolocation Services it is necessary to obtain an API and configure the gw_utils/config.yaml file replacing the value of the "google_api" parameter for the "API" provided. Google provides $200 of free monthly usage.

• combain_api:

In order to use the Combain API it is necessary to obtain an API and configure the gw_utils/config.yaml file replacing the value of the "combain_api" parameter for the "API" provided. Combain provides a free trial and paid plans.

• no-ssl-verify:

Option to enable or disable the SSL verification process on requests.

---

🛠️ Installation

Start by cloning locally the GitHub repo then enter into the geowifi folder. git must be present on your system

git clone https://github.com/GONZOsint/geowifi
cd ./geowifi/

Alternative is to use https://github.com/GONZOsint/geowifi/archive/refs/heads/main.zip then unzip the downloaded file.

Use local Python

Note: Use the package manager pip to install requirements.

virtualenv geowifi
source geowifi/bin/activate
python3 -m pip install -r requirements.txt

Docker

# Using docker
docker build -t geowifi:latest .

Docker Compose

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

---

🔎 Usage

usage: geowifi.py [-h] [-s {bssid,ssid}] [-o {map,json}] identifier

Search for information about a network with a specific BSSID or SSID.

positional arguments:
  identifier            The BSSID or SSID of the network to search for.

options:
  -h, --help            show this help message and exit
  -s {bssid,ssid}, --search-by {bssid,ssid}
                        Specifies whether to search by BSSID or SSID (default: bssid)
  -o {map,json}, --output-format {map,json}
                        Specifies the output format for the search results (default: map)

• Search by BSSID:

python3 geowifi.py -s bssid <input>

• Search by SSID:

python3 geowifi.py -s ssid <input>

It is possible to export the results in json format using the -o json parameter and show the locations on html map using -o map.

🐳 Docker usage

docker run --rm geowifi:latest

• Search by BSSID:

docker run --rm geowifi:latest -s bssid <input>

• Search by SSID:

docker run --rm geowifi:latest -s ssid <input>

🗺️ Map output example

💾 Json output example

[
  {
    "module": "google", 
    "bssid": "C8:XX:XX:XX:5E:45", 
    "latitude": 33.571844, 
    "longitude": -1XX.XXXXX97
  }, 
  {
    "module": "combain", 
    "error": "Not enough witooth"}, 
  {
    "module": "mylnikov", 
    "error": "Object was not found"
  },
  {
    "module": "vendor_check", 
    "vendor": "Cisco-Linksys, LLC"}, 
  {
    "module": "apple", 
    "bssid": "C8:XX:XX:XX:5E:45", 
    "latitude": 33.57198715, 
    "longitude": -1XX.XXXXX12}, 
  {
    "module": "wigle", 
    "bssid": "C8:XX:XX:XX:5E:45", 
    "ssid": "Vertigo", 
    "latitude": 33.60998154, 
    "longitude": -1XX.XXXXX22}, 
  {
    "module": "wifidb", 
    "bssid": "C8:XX:XX:XX:5E:45", 
    "ssid": "Vertigo", 
    "latitude": 33.6109, 
    "longitude": -1XX.XXXXX533
  }
]

---

📢 Mentions

• This project uses some of the research and code used at iSniff-GPS.
• Thanks to Micah Hoffman for his attention and answers to my questions.
• Thanks to kennbro for lending me his scrupulous eyes to give me feedback.

🔌 API Usage

The application now provides a RESTful API interface for querying WiFi geolocation data.

API Endpoints

Search WiFi Location

POST http://localhost:8000/search

Request body:

{
    "identifier": "00:11:22:33:44:55",  // BSSID or SSID
    "search_type": "bssid"              // "bssid" or "ssid"
}

Example using curl:

# Search by BSSID
curl -X POST "http://localhost:8000/search" \
     -H "Content-Type: application/json" \
     -d '{"identifier": "00:11:22:33:44:55", "search_type": "bssid"}'

# Search by SSID
curl -X POST "http://localhost:8000/search" \
     -H "Content-Type: application/json" \
     -d '{"identifier": "MyWiFi", "search_type": "ssid"}'

Example using Python:

import requests

# Search by BSSID
response = requests.post(
    "http://localhost:8000/search",
    json={
        "identifier": "00:11:22:33:44:55",
        "search_type": "bssid"
    }
)
print(response.json())

Response format:

{
    "results": [
        {
            "module": "google",        // Google Geolocation Services
            "bssid": "XX:XX:XX:XX:XX:XX",
            "latitude": 33.571844,
            "longitude": -112.123456
        },
        {
            "module": "apple",         // Apple Location Services
            "bssid": "XX:XX:XX:XX:XX:XX",
            "latitude": 33.57198715,
            "longitude": -112.123456
        },
        {
            "module": "wigle",         // Wigle Community Database
            "bssid": "XX:XX:XX:XX:XX:XX",
            "ssid": "NetworkName",     // Only Wigle provides SSID
            "latitude": 33.60998154,
            "longitude": -112.123456
        },
        {
            "module": "vendor_check",  // MAC Address Vendor Information
            "vendor": "Vendor Name"
        },
        {
            "module": "combain",       // Combain Positioning Service
            "error": "Error message"   // Example of error response
        }
    ]
}

Running the API Server

# Start the API server
python api.py

# Or using uvicorn directly
uvicorn api:app --reload

Using Docker:

# Build and run with Docker
docker build -t geowifi-api .
docker run -p 8000:8000 geowifi-api

# Or using Docker Compose (recommended)
docker-compose up -d    # Start the service
docker-compose logs -f  # View logs
docker-compose down    # Stop the service

Additional Features

• Interactive API documentation available at http://localhost:8000/docs
• Health check endpoint: GET http://localhost:8000/health
• Input validation and error handling
• Async request processing

Data Sources Priority

The results are returned from multiple data sources (modules), each with different reliability levels:

1. Google (google):

   • Google Geolocation Services
   • Highest accuracy when API key is valid
   • Requires valid API key

2. Apple (apple):

   • Apple Location Services
   • High accuracy
   • Based on iOS devices data

3. Wigle (wigle):

   • Community-driven WiFi database
   • Includes SSID information
   • Accuracy varies based on community contributions
   • Requires API key

4. Combain (combain):

   • Commercial positioning service
   • Requires paid API key

5. Mylnikov (mylnikov):

   • Open-source WiFi location database
   • No API key required

6. Vendor Check (vendor_check):

   • Not a location source
   • Provides manufacturer information for the MAC address

Location Accuracy

When multiple sources return location data:

1. Prefer Google/Apple data when available
2. Compare coordinates from different sources
3. Consider Wigle data as supplementary information
4. Use vendor information to validate device context