xweiba/location-spoofer: an iOS location testing tool that runs a Go proxy on the device

What xweiba/location-spoofer actually does

The project targets a narrow problem: you want to see how an iOS app behaves when the device reports a different location, without editing that app. It is aimed at developers and QA engineers doing location service research, software testing and verification on devices they own or are authorised to use, and the README states this scope explicitly.

What it is not matters as much. It is not an Android tool, not a desktop or browser location changer, and not a general packet capture utility. In APP mode the proxy only handles the Apple location service requests and environment verification requests that the project defines, as the README puts it. There is no remote control service and no telemetry, and coordinates are not uploaded to a project server. The repository's top-level entries include App/, Core/, Shared/, Resources/, Config/, Scripts/, Tests/, ThirdParty/ and docs/, which matches a native iOS app with a Go component rather than a script collection.

The practical audience is small but real: someone with an iPhone, a Mac, Xcode, XcodeGen and Go 1.23 or newer, testing an app they are allowed to test. If that is not you, most of the rest of this article will not apply.

Two modes, two very different trust models

Location Spoofer offers two runtime modes, and the difference is where the interception happens.

APP mode runs a local Go proxy (the README calls the binary wloccore) inside the device. The current Wi-Fi network is given a manual HTTP proxy pointing at it. A local CA generated by the app must be installed and trusted, and the proxy handles the defined Apple location service requests before the system and apps read the location result. The README is direct about the design reason: a free self-signing environment may not support Network Extension, so this mode deliberately avoids a VPN component. It also means APP mode covers only the current Wi-Fi network. Cellular is out.

Third-party proxy mode does the opposite. The app never starts its Go proxy and never uses its own CA. The app is responsible for map selection, favourites, coordinate sync and clearing; the third-party client owns the proxy or VPN, the MITM setup, the certificates and the rule execution. Whether Wi-Fi, 4G or 5G is covered depends on that client. A consequence the README flags: after the app is closed, the configuration inside the third-party client may still be active.

The README warns against enabling both at once, because two proxy chains interfere with each other. That is a real operational constraint, not a stylistic note.

The wloc-settings/save contract third-party clients must implement

In third-party proxy mode the app does not push coordinates into the client through any private API. It issues a GET request to a fixed URL, and the client is expected to intercept it locally:

https://gs-loc.apple.com/wloc-settings/save

Three operations are defined by query parameters. `action=query` checks whether the module is connected and reads back the stored coordinates. `lon=<WGS-84 longitude>&lat=<WGS-84 latitude>&acc=<accuracy>` saves the current selection. `action=clear` deletes the saved test coordinates.

The interception script must return HTTP 200 with JSON. On success it echoes the coordinates:

{
  "success": true,
  "longitude": 113.0,
  "latitude": 22.0,
  "accuracy": 25
}

On failure it returns `{"success": false, "error": "..."}`. The README notes one specific case: a query with no saved coordinates can return `{"success":false,"error":"no saved coordinates"}`, which the app interprets as the module being connected but virtual location not enabled. On a successful save, the longitude and latitude in the response must match the WGS-84 coordinates in the request.

Adapting a new client means more than that endpoint. The README lists five steps: add the HTTP request script for the save URL, persist coordinates and accuracy in the client's own storage, enable HTTPS decryption for `gs-loc.apple.com` and `gs-loc-cn.apple.com`, intercept the `gs-loc(-cn).apple.com/clls/wloc` response and rewrite the WLOC response from the same persisted data, and ship a subscribable module file that passes query, save, clear and location restore on a real device. The app only validates the HTTP status, JSON shape and coordinate read-back. It does not manage the client's certificates, MITM, VPN or proxy state.

Installing it and picking a first test location

The README gives four installation routes: your own Apple Developer signing environment, a personal self-signing tool, the unsigned IPA in the project Releases, or building from source on macOS. There is no App Store distribution, and the README states the project cannot be built directly on Windows.

For the self-signing route, the README names the release asset `PaopaoLocationSpoofer-unsigned.ipa` and points to Impactor for the signing step. On iOS 16 and later you enable Developer Mode first under Settings, Privacy and Security, then restart and confirm; iOS 15 has no such switch. A free Apple ID signature typically lasts 7 days before it must be re-signed.

Building from source needs macOS, Xcode, Xcode Command Line Tools, XcodeGen and Go 1.23 or newer. The README gives this sequence:

git clone https://github.com/xweiba/location-spoofer.git
cd location-spoofer

./build.sh

The build script produces an unsigned IPA at `dist/PaopaoLocationSpoofer-unsigned.ipa`, which you then sign and deploy yourself. The Makefile exposes the same pipeline as targets, and the build and contract test path is:

make ipa-unsigned
make test

`make ipa-unsigned` depends on the `core` target, which runs `./Scripts/build-core.sh` to build the Go proxy before packaging. `make test` runs `./Tests/run_all_contract_tests.sh`. There is also a `make verify-ipa IPA=/absolute/path/to/signed.ipa` target, which requires the IPA variable and calls `./Scripts/verify-ipa.sh --signed`.

On first launch the README describes a fixed order: choose APP mode or third-party proxy mode, follow the in-app guidance for that mode, run environment detection, then search, tap or drag on the map to choose a test location, enable it, and verify the result in the target test environment. Restoring the real location differs by mode. In APP mode you stop the test location, turn off the manual HTTP proxy on the current Wi-Fi, and follow the in-app prompt to refresh the location environment. In third-party mode you clear the WLOC coordinates in the app, disable the module or proxy in the client, and restore HTTPS decryption and proxy settings as that client requires. If the old position persists, the README attributes it to location caching and suggests waiting, or restarting the device and checking again.

Coordinate handling: WGS-84, GCJ-02 and a MapKit gap

The project stores two coordinate representations. WGS-84 is the international standard and is what gets written to WLOC. GCJ-02 is the domestic map standard used where a Chinese map coordinate is needed. The current selection shows both, and each can be copied separately.

The interesting part is how the app decides which one MapKit is currently returning. MapKit has no public API that reports whether it is giving you GCJ-02 or WGS-84, so the project probes with fixed anchor points, then does controlled refreshes during a session based on blue dot changes and user actions. The coordinate write boundary stores the full WGS-84 and GCJ-02 pair, and picks the right field at use time, which avoids repeated conversion drift.

That is a workable answer to an API gap, but it is a heuristic. The README itself lists as a limitation that MapKit's coordinate return standard may vary with system version, region and location environment. A fixed-anchor probe can be right in one configuration and wrong in another, and the app cannot tell you which case you are in. Treat coordinate accuracy as something to verify per environment rather than a guarantee.

Where it breaks: iOS 27 beta 6, caching and client coverage

The largest limitation is stated at the top of the README as an important warning: starting with iOS 27 beta 6, the system blocks MITM interception of `gs-loc.apple.com`. On that version and later betas the project cannot be used at all until an adaptation appears. If you are on a current beta, stop here.

Beyond that, the README lists several limits. iOS system version changes can affect location service behaviour. System location is cached, so a switched position does not necessarily take effect immediately. Third-party client compatibility and rule behaviour must be verified per client. Not every app uses the same location API, and not every app or service accepts test coordinates. Behaviour is not guaranteed to be consistent across network environments, device models and iOS versions.

The client support table is honest about maturity. Shadowrocket is listed as currently used for real-device testing with an in-app tutorial. Surge, Quantumult X, Loon, Stash and Egern all have configurations provided but are marked as not yet fully verified, with community configurations still being collected. Egern uses the Surge module. So of six named clients, one is described as tested.

There is also a category mismatch worth naming. People searching for a location spoofer often want a joystick to walk a character around, or an Android or PC tool. This project has neither. It sets a coordinate and rewrites location service responses for testing. Nothing in the README describes route simulation or movement.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-11. Releases are recent and follow each other closely: v1.0.5 on 2026-08-10, v1.0.6 on 2026-09-01 and v1.0.7 on 2026-09-11. The project is moving.

Upgrade cost is concentrated in two places. First, the iOS version. The iOS 27 beta 6 block is an external constraint, so a fix depends on finding a new interception path rather than on a routine release. Second, third-party client modules. The README notes that modules and scripts are now hosted in this repository, and that the original `Yu9191/wloc` repository has been deleted, kept only as an acknowledgement and no longer a runtime dependency. Anyone who followed older instructions pointing at that repository has to re-import from here.

On licensing, the repository's top-level entries do not include a licence file, and the project does not state a licence in the README. That is a gap you have to resolve yourself before redistributing anything, and it is not a question this article can answer. Separately, the README's own boundary notes are worth reading before you file an issue: do not post real locations, credentials, CA private keys or full sensitive logs publicly. The app-generated CA private key lives in the device Keychain, and logs stay in the app group container with roughly three days of retention.

Editorial conclusion

Adopt it if you are testing your own iOS app against different coordinates on a device you control, and you are willing to install a local CA or configure a proxy client. Do not adopt it if you need Android, PC or browser location changes, if you expect a joystick-style movement simulator, or if you are on iOS 27 beta 6 or later, where Apple blocks MITM interception of gs-loc.apple.com and the project does not work. Before trusting it, verify three things: that your iOS version is supported, that the environment detection passes in your chosen mode, and that the app you are testing actually reads the Apple location service responses this tool rewrites. The repository has no licence file in its top-level entries, so confirm the terms before any use beyond private testing.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. xweiba/location-spoofer on GitHub