> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulated Location

> Set or clear the GPS location reported by iOS Simulator and Android Emulator sessions.

Give a session a fixed GPS position so that apps using Core Location, the
Android location APIs, `expo-location`, or a web page's Geolocation API see that
point. It works on iOS Simulator and Android Emulator through the CLI, the
TypeScript SDK, and the REST API.

On iOS the host runs `simctl location set`; on Android it sends `geo fix` to the
emulator console. The call returns once the device has accepted the fix.

## Use the CLI

```bash iOS theme={null}
runcloud ios location set "$IOS_SESSION_ID" --latitude 59.3293 --longitude 18.0686 --json
runcloud ios location clear "$IOS_SESSION_ID" --json
```

```bash Android theme={null}
runcloud android location set "$ANDROID_SESSION_ID" --latitude 59.3293 --longitude 18.0686 --json
runcloud android location clear "$ANDROID_SESSION_ID" --json
```

Negative coordinates work as written: `--latitude -33.8568 --longitude 151.2153`.

## Use the TypeScript SDK

```ts theme={null}
import { Client } from "@run-cloud/sdk";

const cloud = new Client({ apiKey: process.env.RUN_CLOUD_API_KEY! });

const set = await cloud.ios.setLocation(sessionId, { latitude: 59.3293, longitude: 18.0686 });
console.log(set.location); // { latitude: 59.3293, longitude: 18.0686 }

await cloud.android.setLocation(androidSessionId, { latitude: 40.7128, longitude: -74.006 });
await cloud.simulators.clearLocation(androidSessionId, { platform: "android" });
```

`setLocation` checks the coordinates before it sends anything, and throws a
`TypeError` if they are out of range.

## Use the REST API

```bash theme={null}
curl -X POST "https://api.run.cloud/run-cloud/ios/$IOS_SESSION_ID/location" \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 59.3293, "longitude": 18.0686}'

curl -X DELETE "https://api.run.cloud/run-cloud/ios/$IOS_SESSION_ID/location" \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY"
```

Replace `ios` with `android` for an emulator session. A successful reply:

```json theme={null}
{
  "ok": true,
  "platform": "ios",
  "sessionId": "…",
  "device": "…",
  "leaseId": "…",
  "cleared": false,
  "location": { "latitude": 59.3293, "longitude": 18.0686 }
}
```

## Clearing

| Platform | After `DELETE …/location` |
| - | - |
| iOS | No simulated location; `location` is `null`. |
| Android | The emulator default fix (Googleplex, 37.4219983, -122.084), which `location` reports. |

## Behavior

* The location stays set until you change or clear it, or until the session ends.
* The app still needs location permission. Grant it in the app's prompt, or
  through Settings on the device.
* Setting a location does not change the time zone, locale, or the IP-based
  location that web services infer.

## Errors

Failures return `ok: false`, `action: "location"`, and `error.code`:

| Code | HTTP | Meaning |
| - | - | - |
| `invalid_location` | 400 | Latitude is outside -90 to 90, longitude outside -180 to 180, or a value is not a number. |
| `active_session_not_found` | 404 | The session is unknown, released, or belongs to another account. |
| `location_unsupported` | 422 | This device cannot set a location. |
| `location_failed` | 502 | The device rejected the command. Retry. |
| `location_timeout` | 504 | The device did not confirm in time. Retry. |
| `simulator_unavailable`, `location_transport_error`, `location_invalid_response` | 502/503 | The simulator host could not be reached or answered unexpectedly. Retry. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.