AIBit-Discover Open Source Projects AIBit-Discover Open Source Projects

Spoof Apple Network Location (gs-loc) on iOS: Full Guide for Surge, QX, Loon & Stash

Learn how to modify Apple's network location service (gs-loc) to spoof your iOS device's location using proxy tools like Surge, Quantumult X, Loon, and Stash.

Spoof Apple Network Location (gs-loc) on iOS: Full Guide for Surge, QX, Loon & Stash

Apple's network location service (gs-loc) determines your device's approximate location based on nearby Wi-Fi access points and cellular towers. This is distinct from GPS-based location and is used when GPS signals are weak or unavailable. The open-source project Yu9191/wloc provides a clever way to intercept and modify the responses from gs-loc.apple.com, effectively spoofing your network location on iOS devices.

This guide covers everything you need to know: how it works, how to set it up with various proxy tools, and how to use the companion shortcut for one-tap location switching.

Why Spoof Network Location?

Spoofing network location is useful for:

  • Testing location-based apps without physically moving.
  • Bypassing geo-restrictions that rely on network location (not just IP).
  • Privacy: preventing apps from knowing your real location when GPS is off.

Unlike GPS spoofing (which requires jailbreaking or special hardware), this method works on stock iOS devices with a proxy tool installed.

How It Works

The project consists of two main scripts:

  1. wloc.js — Intercepts responses from /clls/wloc (the Apple location endpoint), parses the protobuf response, and replaces the coordinates with user-defined values.
  2. wloc-settings.js — Intercepts requests to /wloc-settings/save and writes the desired coordinates into persistent storage ($persistentStore).

When you use the web-based picker (or the shortcut), it sends a request to gs-loc.apple.com/wloc-settings/save?lon=x&lat=y. The proxy module intercepts this and stores the coordinates. On the next network location request, wloc.js reads these stored coordinates and patches the protobuf response before it reaches the app.

Setup Instructions

Prerequisites

  • A proxy tool: Surge, Quantumult X, Loon, Stash, or Shadowrocket.
  • MITM (Man-in-the-Middle) certificate installed and trusted for gs-loc.apple.com and gs-loc-cn.apple.com.
  • The proxy must be active (VPN icon visible).

Step 1: Subscribe to the Module

Choose your tool and subscribe to the corresponding module URL:

Tool Module URL
Surge https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.sgmodule
Quantumult X https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.conf
Loon https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.lpx
Stash https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride
Shadowrocket https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.module

For Egern, you can use the Surge module directly.

Step 2: Enable MITM

In your proxy tool, enable MITM and add gs-loc.apple.com and gs-loc-cn.apple.com to the MITM hostnames list. Install the generated CA certificate on your iOS device and trust it (Settings > General > About > Certificate Trust Settings).

Step 3: Choose a Location

You have two options:

Option A: Use the Web Picker (Manual)

Open the public worker page: https://wloc-spoofer.wloc.workers.dev/ (or your self-deployed instance). Search for a location, long-press on the map to drop a pin, then tap "Save to Device." The coordinates will be stored in the proxy's persistent storage.

Option B: Use the Shortcut (Recommended)

Install the two shortcuts:

To set a location: Open Apple Maps or Amap (Gaode), long-press a point, tap Share, then select the "wloc Set Location" shortcut. The shortcut extracts coordinates (handling GCJ-02 to WGS84 conversion via a worker) and sends them to the proxy.

Step 4: Verify

Open an app that uses network location (e.g., Weather, Maps) and check if the spoofed location appears. If not, ensure the proxy is active and MITM is working.

iOS 26+ Cache Issues

Starting with iOS 26, Apple introduced aggressive caching in locationd. The system may reuse cached location data even after the module modifies the WLOC response. If you don't see changes:

  1. Restart your device — This clears the locationd cache. Toggling Airplane Mode or Location Services alone won't work.
  2. Recommended workflow:
    • Set the desired location via the shortcut or web picker.
    • Enable Airplane Mode, turn off Location Services, then restart.
    • After restart, disable Airplane Mode (keep Wi-Fi off), connect to your proxy (VPN icon appears), then enable Location Services.
    • Open Maps to verify.

Restoring Real Location

To revert to your real network location:

  • Method 1: Disable or remove the module. The script stops intercepting requests, and the system uses real data. On iOS 26+, restart the device to clear the cache.
  • Method 2: Clear the persistent storage data. The script enters "passthrough mode" when no custom coordinates are stored and the module parameters are at defaults. Run the following in your proxy tool's script editor:
    • Surge: $persistentStore.write(null, "wloc_settings")
    • Quantumult X: $prefs.removeValueForKey("wloc_settings")
    • Loon: $persistentStore.write(null, "wloc_settings")

Then restart the device.

Self-Deploying the Worker

The public worker has usage limits. For reliability, deploy your own instance on Cloudflare Workers or Pages:

Workers (One-Click)

Deploy to Cloudflare Workers

Workers (Manual)

git clone https://github.com/Yu9191/wloc.git
cd wloc/worker
npm install
npx wrangler login
npm run deploy

Pages (Manual)

git clone https://github.com/Yu9191/wloc.git
cd wloc/worker
npm install
npx wrangler pages deploy dist --project-name <your-project-name>

After deployment, update the shortcut's worker URL to your own.

Configuration Parameters

Parameter Description Default
longitude Target longitude (web picker overrides) null (passthrough)
latitude Target latitude (web picker overrides) null (passthrough)
accuracy Accuracy in meters 25
logLevel Logging level info

Priority: Web picker storage > Module parameters > Default values.

Privacy Considerations

The worker (/api/parse) is a pure relay: it receives a map link, follows redirects, extracts coordinates, converts GCJ-02 to WGS84 if needed, and returns JSON. It does not log, cache, or store any data. If you're concerned, deploy your own instance using the open-source code.

Limitations

  • Only modifies network location (Wi-Fi/cell tower based), not GPS. If GPS is strong, iOS may prefer GPS data.
  • Works best indoors where GPS is weak.
  • The web picker must be accessed through the proxy (Safari must route through the proxy tool) for the save request to be intercepted.

Credits

With this setup, you can easily spoof your iOS device's network location for testing, privacy, or geo-unblocking. The combination of proxy modules and shortcuts makes it as simple as sharing a map pin.

Source

Yu9191/wloc: 修改 Apple 网络定位（gs-loc）返回坐标 · 支持 Surge / Quantumult X / Loon / Stash · 快捷指令一键设置/恢复定位