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

# Same app, different markets

> Verify network countries, compare markets, and align language and timezone.

Switch one Cloud Android device between markets and verify what a fresh browser request sees.

> [accordion] Setup (once)
>
> ```bash Python theme={null}
> pip install mobilerun-sdk
> export MOBILERUN_API_KEY=dr_sk_...   # API Keys page
> export DEVICE_ID=...                 # a ready device from the dashboard
> python example.py
> ```
>
> ```bash TypeScript theme={null}
> npm init -y && npm pkg set type=module
> npm install @mobilerun/sdk && npm install -D tsx
> export MOBILERUN_API_KEY=dr_sk_...   # API Keys page
> export DEVICE_ID=...                 # a ready device from the dashboard
> npx tsx example.ts
> ```

> [!NOTE]
>
> Use device Connect proxies, not task `vpnCountry`, to switch markets on Cloud Android; attaching or disconnecting can restart the device.

Each sample starts Chrome on a unique trace URL and has a task read the country (`loc=`) from the page as [typed output](https://docs.mobilerun.ai/sdk/helpers.md#typed-output). `device.waitReady()` returns once the device is ready again after a proxy change.

## Check one country

Attach a German residential proxy, check a fresh page for `DE`, then disconnect.

**Needs:** Ready Cloud Android · Chrome with first-run prompts cleared · Connect access and proxy data · `MOBILERUN_API_KEY`, `DEVICE_ID` · Python 3.9+ or Node.js · no site account · one-shot, \~1–3 min · device minutes + residential traffic.

> **MCP prompt:** On my test Cloud Android device with no proxy attached, connect a rotating residential Connect proxy in Germany. Force-stop Chrome without clearing its data, open a new network trace URL with a unique query, and read the country. Verify DE, then disconnect the proxy and wait for the device to be ready. Do not sign in.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import os
> import time
> from pydantic import BaseModel
> from mobilerun_sdk import MobilerunSDK
>
>
> class Trace(BaseModel):
>     country: str
>
>
> mobilerun = MobilerunSDK()
> device = mobilerun.devices.from_id(os.environ["DEVICE_ID"])
> if device.proxy.status().connected:
>     raise RuntimeError("Use a test device with no attached proxy")
> try:
>     device.proxy.connect(connect={"country": "de"}, smart_ip=False)
>     device.wait_ready()
>     device.stop_app("com.android.chrome")
>     url = f"https://one.one.one.one/cdn-cgi/trace?x={time.time_ns()}"
>     device.deep_link.execute_deep_link(deep_link=url, package_name="com.android.chrome")
>     task = device.run(
>         task="Read the two-letter loc= value on the page shown in Chrome",
>         output_schema=Trace,
>     )
>     country = task.wait_output().output.country
>     if country != "DE":
>         raise ValueError(f"Expected DE; page reported {country}")
>     print(f"Network country: {country}")
> finally:
>     device.proxy.disconnect()
>     device.wait_ready()
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
> import { output } from '@mobilerun/sdk/zod';
> import { z } from 'zod/v4';
>
> const mobilerun = new MobilerunSDK();
> const device = mobilerun.devices.fromId(process.env.DEVICE_ID!);
> if ((await device.proxy.status()).connected) throw new Error('Use a test device with no attached proxy');
> try {
>   await device.proxy.connect({ connect: { country: 'de' }, smartIp: false });
>   await device.waitReady();
>   await device.stopApp('com.android.chrome');
>   const url = `https://one.one.one.one/cdn-cgi/trace?x=${Date.now()}`;
>   await device.deepLink.executeDeepLink({ deepLink: url, packageName: 'com.android.chrome' });
>   const task = await device.run({
>     task: 'Read the two-letter loc= value on the page shown in Chrome',
>     outputSchema: output(z.object({ country: z.string() })),
>   });
>   const { country } = (await task.waitOutput()).output;
>   if (country !== 'DE') throw new Error(`Expected DE; page reported ${country}`);
>   console.log(`Network country: ${country}`);
> } finally {
>   await device.proxy.disconnect();
>   await device.waitReady();
> }
> ```

![Network trace showing Germany, with the IP address removed](https://docs.mobilerun.ai/images/examples/markets/l1-de.png)

Result

```text theme={null}
Network country: DE
```

## Compare several markets

Compare DE, JP and BR in `markets.json`, adding GPS coordinates for location-aware apps—GPS alone does not change the network country.

**Needs:** Same setup · location-control capability · test device with no attached proxy · no site account · one-shot, \~2–5 min · device minutes + residential traffic.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import json
> import os
> import time
> from pydantic import BaseModel
> from mobilerun_sdk import MobilerunSDK, Device
>
>
> class Trace(BaseModel):
>     country: str
>
>
> mobilerun = MobilerunSDK()
> device = mobilerun.devices.from_id(os.environ["DEVICE_ID"])
> markets = [("DE", 52.52, 13.405), ("JP", 35.6762, 139.6503), ("BR", -23.5505, -46.6333)]
> if device.proxy.status().connected:
>     raise RuntimeError("Use a test device with no attached proxy")
>
>
> def read_country(device: Device) -> str:
>     device.stop_app("com.android.chrome")
>     url = f"https://one.one.one.one/cdn-cgi/trace?x={time.time_ns()}"
>     device.deep_link.execute_deep_link(deep_link=url, package_name="com.android.chrome")
>     task = device.run(
>         task="Read the two-letter loc= value on the page shown in Chrome",
>         output_schema=Trace,
>     )
>     return task.wait_output().output.country
>
>
> rows = []
> try:
>     for country, latitude, longitude in markets:
>         device.proxy.connect(connect={"country": country.lower()}, smart_ip=False)
>         device.wait_ready()
>         device.location.set(latitude=latitude, longitude=longitude)
>         observed = read_country(device)
>         if observed != country:
>             raise ValueError(f"Expected {country}; page reported {observed}")
>         rows.append({"market": country, "network_country": observed})
> finally:
>     try:
>         device.proxy.disconnect()
>         device.wait_ready()
>     finally:
>         device.location.reset()
> with open("markets.json", "w", encoding="utf-8") as report:
>     json.dump(rows, report, indent=2)
> print("Market  Network country")
> for row in rows:
>     print(f"{row['market']:<8}{row['network_country']}")
> ```
>
> ```typescript TypeScript theme={null}
> import { writeFile } from 'node:fs/promises';
> import { MobilerunSDK, type Device } from '@mobilerun/sdk';
> import { output } from '@mobilerun/sdk/zod';
> import { z } from 'zod/v4';
>
> const mobilerun = new MobilerunSDK();
> const device = mobilerun.devices.fromId(process.env.DEVICE_ID!);
> const markets = [
>   { country: 'DE', latitude: 52.52, longitude: 13.405 },
>   { country: 'JP', latitude: 35.6762, longitude: 139.6503 },
>   { country: 'BR', latitude: -23.5505, longitude: -46.6333 },
> ];
> if ((await device.proxy.status()).connected) throw new Error('Use a test device with no attached proxy');
>
> async function readCountry(device: Device): Promise<string> {
>   await device.stopApp('com.android.chrome');
>   const url = `https://one.one.one.one/cdn-cgi/trace?x=${Date.now()}`;
>   await device.deepLink.executeDeepLink({ deepLink: url, packageName: 'com.android.chrome' });
>   const task = await device.run({
>     task: 'Read the two-letter loc= value on the page shown in Chrome',
>     outputSchema: output(z.object({ country: z.string() })),
>   });
>   return (await task.waitOutput()).output.country;
> }
>
> const rows: { market: string; network_country: string }[] = [];
> try {
>   for (const { country, latitude, longitude } of markets) {
>     await device.proxy.connect({ connect: { country: country.toLowerCase() }, smartIp: false });
>     await device.waitReady();
>     await device.location.set({ latitude, longitude });
>     const observed = await readCountry(device);
>     if (observed !== country) throw new Error(`Expected ${country}; page reported ${observed}`);
>     rows.push({ market: country, network_country: observed });
>   }
> } finally {
>   try {
>     await device.proxy.disconnect();
>     await device.waitReady();
>   } finally {
>     await device.location.reset();
>   }
> }
> await writeFile('markets.json', JSON.stringify(rows, null, 2) + '\n');
> console.log('Market  Network country');
> for (const row of rows) console.log(`${row.market.padEnd(8)}${row.network_country}`);
> ```

![Network trace showing Japan, with the IP address removed](https://docs.mobilerun.ai/images/examples/markets/l2-jp.png)

Result

```text theme={null}
Market  Network country
DE      DE
JP      JP
BR      BR
```

## Use any country with a proxy

Choose an available Connect country with `COUNTRY`, `LOCALE` and `TIMEZONE`, use Smart IP for GPS alignment, and restore language/timezone afterward.

**Needs:** Same setup · language, timezone and location controls · dedicated test device · defaults: CA, en-CA, America/Toronto · no site account · one-shot, \~1–3 min · device minutes + residential traffic.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import json
> import os
> import time
> from pydantic import BaseModel
> from mobilerun_sdk import MobilerunSDK, Device
>
>
> class Trace(BaseModel):
>     country: str
>
>
> mobilerun = MobilerunSDK()
> device = mobilerun.devices.from_id(os.environ["DEVICE_ID"])
> country = os.environ.get("COUNTRY", "CA").upper()
> locale = os.environ.get("LOCALE", "en-CA")
> timezone = os.environ.get("TIMEZONE", "America/Toronto")
> if device.proxy.status().connected:
>     raise RuntimeError("Use a test device with no attached proxy")
> original_locale = device.language.get().locale
> original_timezone = device.timezone.get().timezone
> if not original_locale or not original_timezone:
>     raise RuntimeError("Could not read original locale and timezone")
>
>
> def settle(device: Device) -> None:
>     device.wait_ready()
>     device.ui()  # a restarting device answers once its services are back
>
>
> try:
>     device.proxy.connect(connect={"country": country.lower()}, smart_ip=True)
>     settle(device)
>     device.language.set(locale=locale, restart=True)
>     settle(device)
>     device.timezone.set(timezone=timezone)
>     device.stop_app("com.android.chrome")
>     url = f"https://one.one.one.one/cdn-cgi/trace?x={time.time_ns()}"
>     device.deep_link.execute_deep_link(deep_link=url, package_name="com.android.chrome")
>     task = device.run(
>         task="Read the two-letter loc= value on the page shown in Chrome",
>         output_schema=Trace,
>     )
>     observed = task.wait_output().output.country
>     if observed != country:
>         raise ValueError(f"Expected {country}; page reported {observed}")
>     current_locale = device.language.get().locale
>     current_timezone = device.timezone.get().timezone
>     if current_locale != locale or current_timezone != timezone:
>         raise ValueError("Device locale or timezone did not match")
>     print(json.dumps({"country": observed, "locale": current_locale, "timezone": current_timezone}))
> finally:
>     try:
>         device.proxy.disconnect()
>         settle(device)
>     finally:
>         try:
>             device.language.set(locale=original_locale, restart=True)
>             settle(device)
>         finally:
>             try:
>                 device.timezone.set(timezone=original_timezone)
>             finally:
>                 device.location.reset()
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK, type Device } from '@mobilerun/sdk';
> import { output } from '@mobilerun/sdk/zod';
> import { z } from 'zod/v4';
>
> const mobilerun = new MobilerunSDK();
> const device = mobilerun.devices.fromId(process.env.DEVICE_ID!);
> const country = (process.env.COUNTRY ?? 'CA').toUpperCase();
> const locale = process.env.LOCALE ?? 'en-CA';
> const timezone = process.env.TIMEZONE ?? 'America/Toronto';
> if ((await device.proxy.status()).connected) throw new Error('Use a test device with no attached proxy');
> const originalLocale = (await device.language.get()).locale;
> const originalTimezone = (await device.timezone.get()).timezone;
> if (!originalLocale || !originalTimezone) throw new Error('Could not read original locale and timezone');
>
> async function settle(device: Device) {
>   await device.waitReady();
>   await device.ui(); // a restarting device answers once its services are back
> }
>
> try {
>   await device.proxy.connect({ connect: { country: country.toLowerCase() }, smartIp: true });
>   await settle(device);
>   await device.language.set({ locale, restart: true });
>   await settle(device);
>   await device.timezone.set({ timezone });
>   await device.stopApp('com.android.chrome');
>   const url = `https://one.one.one.one/cdn-cgi/trace?x=${Date.now()}`;
>   await device.deepLink.executeDeepLink({ deepLink: url, packageName: 'com.android.chrome' });
>   const task = await device.run({
>     task: 'Read the two-letter loc= value on the page shown in Chrome',
>     outputSchema: output(z.object({ country: z.string() })),
>   });
>   const observed = (await task.waitOutput()).output.country;
>   if (observed !== country) throw new Error(`Expected ${country}; page reported ${observed}`);
>   const currentLocale = (await device.language.get()).locale;
>   const currentTimezone = (await device.timezone.get()).timezone;
>   if (currentLocale !== locale || currentTimezone !== timezone) throw new Error('Device locale or timezone did not match');
>   console.log(JSON.stringify({ country: observed, locale: currentLocale, timezone: currentTimezone }));
> } finally {
>   try {
>     await device.proxy.disconnect();
>     await settle(device);
>   } finally {
>     try {
>       await device.language.set({ locale: originalLocale, restart: true });
>       await settle(device);
>     } finally {
>       try {
>         await device.timezone.set({ timezone: originalTimezone });
>       } finally {
>         await device.location.reset();
>       }
>     }
>   }
> }
> ```

![Network trace showing Canada, with the IP address removed](https://docs.mobilerun.ai/images/examples/markets/l3-ca.png)

Result

```json theme={null}
{"country":"CA","locale":"en-CA","timezone":"America/Toronto"}
```

## One device per market

> [!TIP]
>
> Add as many markets as you need: one device per market, all in parallel.

Map countries to distinct device IDs and run the same country check on every device in parallel.

**Needs:** Same setup on each device · `DEVICE_IDS` JSON, e.g. `{"DE":"device-id","JP":"another-device-id"}` · one-shot, \~1–3 min · device minutes + residential traffic per device.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import asyncio
> import json
> import os
> import time
> from pydantic import BaseModel
> from mobilerun_sdk import AsyncMobilerunSDK
>
>
> class Trace(BaseModel):
>     country: str
>
>
> mobilerun = AsyncMobilerunSDK()
> markets = json.loads(os.environ["DEVICE_IDS"])  # {"DE":"device-id","JP":"another-device-id"}
> if not isinstance(markets, dict) or not markets:
>     raise ValueError("DEVICE_IDS must be a nonempty country-to-device JSON object")
> if not all(isinstance(c, str) and len(c) == 2 and isinstance(d, str) and d for c, d in markets.items()):
>     raise ValueError("Use two-letter country keys and device ID strings")
> if len(set(markets.values())) != len(markets):
>     raise ValueError("Each market needs a different device")
>
>
> async def check_market(market: str, device_id: str) -> dict[str, str]:
>     country = market.upper()
>     device = mobilerun.devices.from_id(device_id)
>     await device.refresh()
>     if device.state != "ready" or (await device.proxy.status()).connected:
>         raise RuntimeError("Each test device must be ready with no attached proxy")
>     try:
>         await device.proxy.connect(connect={"country": country.lower()}, smart_ip=False)
>         await device.wait_ready()
>         await device.stop_app("com.android.chrome")
>         url = f"https://one.one.one.one/cdn-cgi/trace?x={time.time_ns()}"
>         await device.deep_link.execute_deep_link(deep_link=url, package_name="com.android.chrome")
>         task = await device.run(
>             task="Read the two-letter loc= value on the page shown in Chrome",
>             output_schema=Trace,
>         )
>         observed = (await task.wait_output()).output.country
>         if observed != country:
>             raise ValueError(f"Expected {country}; page reported {observed}")
>         return {"market": country, "network_country": observed}
>     finally:
>         await device.proxy.disconnect()
>         await device.wait_ready()
>
>
> async def main() -> None:
>     results = await asyncio.gather(
>         *(check_market(m, d) for m, d in markets.items()), return_exceptions=True
>     )
>     if any(isinstance(r, BaseException) for r in results):
>         raise RuntimeError("A market failed; all workers have finished cleanup")
>     print("Market  Network country")
>     for row in results:
>         if isinstance(row, dict):
>             print(f"{row['market']:<8}{row['network_country']}")
>
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
> import { output } from '@mobilerun/sdk/zod';
> import { z } from 'zod/v4';
>
> const mobilerun = new MobilerunSDK();
> const markets: unknown = JSON.parse(process.env.DEVICE_IDS ?? 'null'); // {"DE":"device-id","JP":"another-device-id"}
> if (!markets || typeof markets !== 'object' || Array.isArray(markets)) throw new Error('DEVICE_IDS must be a country-to-device JSON object');
> const entries = Object.entries(markets);
> if (!entries.length || entries.some(([c, d]) => c.length !== 2 || typeof d !== 'string' || !d)) throw new Error('Use country keys and device ID strings');
> if (new Set(entries.map(([, d]) => d)).size !== entries.length) throw new Error('Each market needs a different device');
>
> async function checkMarket([market, id]: [string, unknown]) {
>   const country = market.toUpperCase();
>   const device = mobilerun.devices.fromId(id as string);
>   await device.refresh();
>   if (device.state !== 'ready' || (await device.proxy.status()).connected)
>     throw new Error('Each test device must be ready with no attached proxy');
>   try {
>     await device.proxy.connect({ connect: { country: country.toLowerCase() }, smartIp: false });
>     await device.waitReady();
>     await device.stopApp('com.android.chrome');
>     const url = `https://one.one.one.one/cdn-cgi/trace?x=${Date.now()}`;
>     await device.deepLink.executeDeepLink({ deepLink: url, packageName: 'com.android.chrome' });
>     const task = await device.run({
>       task: 'Read the two-letter loc= value on the page shown in Chrome',
>       outputSchema: output(z.object({ country: z.string() })),
>     });
>     const observed = (await task.waitOutput()).output.country;
>     if (observed !== country) throw new Error(`Expected ${country}; page reported ${observed}`);
>     return { market: country, network_country: observed };
>   } finally {
>     await device.proxy.disconnect();
>     await device.waitReady();
>   }
> }
>
> const results = await Promise.allSettled(entries.map(checkMarket));
> if (results.some((result) => result.status === 'rejected')) throw new Error('A market failed; all workers have finished cleanup');
> console.log('Market  Network country');
> for (const result of results) {
>   if (result.status === 'fulfilled') console.log(`${result.value.market.padEnd(8)}${result.value.network_country}`);
> }
> ```

![Network trace showing Brazil, with the IP address removed](https://docs.mobilerun.ai/images/examples/markets/l4-br.png)

Parallel market checks

```text theme={null}
Market  Network country
DE      DE
JP      JP
BR      BR
```

## Next steps

* Replace the trace page with your app's regional content or pricing screen.
* Find supported countries in the [Connect country catalog](https://docs.mobilerun.ai/api-reference/countries/list-available-countries.md).
* Explore [proxies and Smart IP](https://docs.mobilerun.ai/proxies.md) or [read app data as JSON](https://docs.mobilerun.ai/examples/extract-data.md).

> [accordion] For AI agents
>
> * Start with Check one country on a ready test device with no attached proxy.
> * Use device proxy, deep-link and typed task output; map `DEVICE_IDS` to distinct devices for parallel checks.
> * Ask before attaching a proxy: it can restart the device and uses residential traffic.
> * Report requested versus observed countries and cleanup status.


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