|
| 1 | +--- |
| 2 | +title: "Browser Location" |
| 3 | +description: "Align a browser session's timezone and locale with its proxy geography or set explicit overrides" |
| 4 | +--- |
| 5 | + |
| 6 | +KERNEL selects one timezone and formatting locale for each browser session. By default, it resolves each field from the browser's effective proxy geography and falls back to the browser's region while resolution is pending or unavailable. |
| 7 | + |
| 8 | +The setting applies across browser contexts, pages, frames, workers, `Intl`, `navigator.language`, `navigator.languages`, and future `Accept-Language` headers. Updating it doesn't restart Chromium or reload pages. |
| 9 | + |
| 10 | +<Note> |
| 11 | +Location controls timezone and language behavior. It doesn't set geolocation coordinates, grant geolocation permission, change the system clock, translate browser UI, or guarantee a bot-detection outcome. |
| 12 | +</Note> |
| 13 | + |
| 14 | +## Set location when creating a browser |
| 15 | + |
| 16 | +Set either field independently. Omit a field to let KERNEL select it automatically. |
| 17 | + |
| 18 | +<CodeGroup> |
| 19 | +```typescript TypeScript |
| 20 | +import Kernel from '@onkernel/sdk'; |
| 21 | + |
| 22 | +const kernel = new Kernel(); |
| 23 | +const browser = await kernel.browsers.create({ |
| 24 | + proxy: { name: 'berlin-checkout' }, |
| 25 | + location: { |
| 26 | + timezone: 'Europe/Berlin', |
| 27 | + locale: 'de-DE', |
| 28 | + }, |
| 29 | +}); |
| 30 | + |
| 31 | +console.log(browser.location); |
| 32 | +``` |
| 33 | + |
| 34 | +```python Python |
| 35 | +from kernel import Kernel |
| 36 | + |
| 37 | +kernel = Kernel() |
| 38 | +browser = kernel.browsers.create( |
| 39 | + proxy={"name": "berlin-checkout"}, |
| 40 | + location={ |
| 41 | + "timezone": "Europe/Berlin", |
| 42 | + "locale": "de-DE", |
| 43 | + }, |
| 44 | +) |
| 45 | + |
| 46 | +print(browser.location) |
| 47 | +``` |
| 48 | +</CodeGroup> |
| 49 | + |
| 50 | +`timezone` accepts supported IANA identifiers such as `America/Los_Angeles`. `locale` accepts canonical BCP 47 tags such as `en-US` or `de-DE`. KERNEL validates the complete request before changing the session. |
| 51 | + |
| 52 | +## Update a running browser |
| 53 | + |
| 54 | +Use `browsers.update()` to set an override without restarting Chromium: |
| 55 | + |
| 56 | +<CodeGroup> |
| 57 | +```typescript TypeScript |
| 58 | +const browser = await kernel.browsers.update('01j8m3w6q2d7av9n5k4f1p8c', { |
| 59 | + location: { |
| 60 | + timezone: 'America/Los_Angeles', |
| 61 | + locale: 'en-US', |
| 62 | + }, |
| 63 | +}); |
| 64 | +``` |
| 65 | + |
| 66 | +```python Python |
| 67 | +browser = kernel.browsers.update( |
| 68 | + "01j8m3w6q2d7av9n5k4f1p8c", |
| 69 | + location={ |
| 70 | + "timezone": "America/Los_Angeles", |
| 71 | + "locale": "en-US", |
| 72 | + }, |
| 73 | +) |
| 74 | +``` |
| 75 | +</CodeGroup> |
| 76 | + |
| 77 | +PATCH semantics are field-specific: |
| 78 | + |
| 79 | +- omit `location` or one of its fields to leave that field unchanged |
| 80 | +- set a string to create or replace a session override |
| 81 | +- set a field to `null` in TypeScript or `None` in Python to clear that override and resume automatic selection |
| 82 | + |
| 83 | +<CodeGroup> |
| 84 | +```typescript TypeScript |
| 85 | +const browser = await kernel.browsers.update('01j8m3w6q2d7av9n5k4f1p8c', { |
| 86 | + location: { |
| 87 | + timezone: null, |
| 88 | + }, |
| 89 | +}); |
| 90 | +``` |
| 91 | + |
| 92 | +```python Python |
| 93 | +browser = kernel.browsers.update( |
| 94 | + "01j8m3w6q2d7av9n5k4f1p8c", |
| 95 | + location={"timezone": None}, |
| 96 | +) |
| 97 | +``` |
| 98 | +</CodeGroup> |
| 99 | + |
| 100 | +Clearing one field doesn't clear the other. Explicit overrides also survive proxy changes for the rest of that session. |
| 101 | + |
| 102 | +## Read effective location |
| 103 | + |
| 104 | +Browser responses include the effective values, per-field provenance, and convergence state: |
| 105 | + |
| 106 | +```json |
| 107 | +{ |
| 108 | + "location": { |
| 109 | + "timezone": "Europe/Berlin", |
| 110 | + "locale": "de-DE", |
| 111 | + "timezone_source": "proxy_metadata", |
| 112 | + "locale_source": "proxy_metadata", |
| 113 | + "pending": false |
| 114 | + } |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +`timezone_source` and `locale_source` can be `override`, `proxy_metadata`, `geoip`, `exit_ip`, or `metro`. KERNEL resolves the fields independently, so their sources can differ. |
| 119 | + |
| 120 | +When `pending` is `true`, the API has accepted the desired policy but the running browser hasn't finished converging. Browser creation and proxy updates don't wait for external geography discovery. KERNEL keeps the current values during a delayed or failed lookup and applies a valid late result in the background. |
| 121 | + |
| 122 | +## Runtime behavior |
| 123 | + |
| 124 | +- New pages, frames, workers, and network contexts start with the latest applied defaults. |
| 125 | +- Existing pages and workers receive the update without a reload. |
| 126 | +- Existing `Intl` formatter objects and application-level caches can retain values captured before the update. Create a new formatter when you need the latest default. |
| 127 | +- Future requests use the updated language preference. Requests already in flight aren't rewritten. |
| 128 | +- Customer CDP emulation remains separate from the session default and can temporarily override what a particular target reports. |
| 129 | +- Location overrides last only for the browser session. Profiles don't save them. |
| 130 | + |
| 131 | +For rotating residential and mobile proxies, KERNEL resolves location when the proxy is attached or explicitly changed. It doesn't chase silent exit-IP rotation, and one discovery request doesn't represent destination-specific routes for every website. |
0 commit comments