I Built a Wi-Fi BSSID Locator GUI That Plots the Result on a Real Map

I wanted a desktop tool that could take a Wi-Fi BSSID, query Apple's geolocation service, and show the result immediately on a map.

Not a browser workflow. Not a loose script that prints coordinates and leaves the rest to me. A small GUI that does the lookup, renders the location, and gives me a clean next step.

That is exactly what this repo does.

What the repo actually does

The app takes a MAC address in XX:XX:XX:XX:XX:XX format, validates it, sends the BSSID through Apple's Wi-Fi location endpoint, decodes the protobuf response, and turns that into a visible point on a map.

From there it does the practical things you actually want in a desktop tool:

• show the latitude and longitude
• render the point inside the app
• let you copy the coordinates
• open the same result in Google Maps or OpenStreetMap

The repo keeps that path in one place instead of scattering the logic across multiple scripts.

The request path that matters

The core lookup logic is short enough to understand, but real enough to be useful.

def lookup_location(mac: str) -> Union[Tuple[float, float], str]:
    if not re.match(r"^[0-9A-Fa-f]{2}(:[0-9A-Fa-f]{2}){5}$", mac):
        return "Invalid MAC address format. Use XX:XX:XX:XX:XX:XX"

    data_bssid = f"\x12\x13\n\x11{mac.lower()}\x18\x00\x20\x01"
    data = (
        "\x00\x01\x00\x05en_US\x00\x13com.apple.locationd\x00\x0a"
        "8.1.12B411\x00\x00\x00\x01\x00\x00\x00"
        + chr(len(data_bssid))
        + data_bssid
    )

    resp = requests.post(
        "https://gs-loc.apple.com/clls/wloc",
        headers=headers,
        data=data,
        timeout=15,
    )

    bssid_response = BSSIDResp()
    bssid_response.ParseFromString(resp.content[10:])

That is the part worth reading first.

It does three useful things cleanly:

• rejects bad input before sending the request
• builds the binary payload Apple expects
• decodes the response into coordinates instead of leaving you with raw bytes

Why the map path is better than a plain coordinate dump

The lookup alone is not the whole value.

The repo also makes the result readable. It can render the point with OpenStreetMap by default, and it can switch to Google Static Maps when a valid API key is present. That fallback matters because it keeps the tool usable without forcing one map provider.

The GUI also gives you the small usability wins that make the app feel finished instead of improvised:

• zoom control
• in-app map preview
• copy-to-clipboard action
• direct open in Google Maps
• direct open in OpenStreetMap

Run it

pip install -r requirements.txt
pip install pillow
python apple_wifi_locator_gui.py

The extra pillow install is worth calling out because the GUI imports PIL for image handling.

Once it is running, enter a BSSID, press Lookup, and the app will either show the mapped result or tell you clearly why it could not resolve it.

Read this file first

Start with apple_wifi_locator_gui.py.

That file contains the request construction, response parsing, map rendering logic, and the actual Tkinter workflow. The supporting protobuf files in helpers/ matter, but the main Python file is where the repo becomes understandable fast.

Bottom line

This is a good repo shape because it does the full job end to end:

• validate the input
• perform the lookup
• decode the result
• render the map
• give the user immediate actions after the lookup

That is much better than a repo that stops at “here are the coordinates.”

If you work on AI tooling, developer productivity, Python tooling, desktop utilities, or systems automation, connect with me on LinkedIn.

Canonical source: GitHub repository