> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/headless-browser/di-li-wei-zhi-yu-dai-li-xuan-ze.md).

# 地理位置与代理选择

直接将地理位置和代理路由参数添加到 WebSocket 连接 URL，将自动化无头浏览器会话路由到目标地理区域，并控制代理 IP 的使用。

## 地理位置参数

您可以使用三个主要查询参数按国家、州或城市定位特定地理位置。

### 国家

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_cc</code></td><td>2 位国家代码（例如， <code>US</code>, <code>DE</code>, <code>FR</code>）。如果未指定国家/地区，将根据可用性自动分配。</td></tr></tbody></table>

```
wss://USER:PASS@ubc.oxylabs.io?p_cc=US
```

### 城市

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_city</code></td><td>使用小写的城市名称（例如， <code>berlin</code>, <code>los_angeles</code>）。还必须同时指定以下任一项： <code>p_cc</code> 或 <code>p_state</code>.</td></tr></tbody></table>

```
wss://USER:PASS@ubc.oxylabs.io?p_cc=US&p_city=new_york
```

{% hint style="info" %}
城市级定位采用 *尽力而为的优先级*。如果住宅代理池中没有请求的精确位置可用代理，则会自动回退到国家范围。
{% endhint %}

### 州（仅限美国）

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_state</code></td><td>以小写形式填写美国州名（例如， <code>texas</code>, <code>ohio</code>）。查看完整的  <a href="https://content.gitbook.com/content/BQ7Zf9paoN3FTeGcyfY1/blobs/cVjpiu1GKicluiVIT9og/us_states.txt">支持的州列表</a>.</td></tr></tbody></table>

```
wss://USER:PASS@ubc.oxylabs.io?p_state=texas&p_city=houston
```

{% hint style="info" %}
**注意：** 如果 `p_state` 和 `p_cc` 两者都指定， `p_state` 将优先，并且 `p_cc` 将被忽略。
{% endhint %}

## 代理选择（粘性代理）

默认情况下，代理网关会为每个唯一的浏览器连接会话分配一个新的出口 IP。或者，您可以通过添加以下参数，在连续的浏览器连接尝试中固定一个特定的住宅出口 IP： `proxy_resi_ses_id` 和 `proxy_resi_ses_time` 参数的访问权限。

<table><thead><tr><th width="181">参数</th><th width="479">描述</th><th width="83">类型</th></tr></thead><tbody><tr><td><code>proxy_resi_ses_id</code></td><td>由 3 到 36 个字符组成的字母数字会话跟踪器名称。</td><td>字符串</td></tr><tr><td><code>proxy_resi_ses_time</code></td><td>保持固定的住宅代理出口 IP 的分钟数。最少 1 分钟，最多 1440 分钟（24 小时）。</td><td>整数</td></tr></tbody></table>

```bash
# Example: Pin a US-based IP for a 60 minutes
wss://USER:PASS@ubc.oxylabs.io?p_cc=US&proxy_resi_ses_id=unique_job_id_101&proxy_resi_ses_time=60
```

{% hint style="warning" %}
要在连续连接中保持完全相同的出口 IP，您必须为以下两项传递相同的值： `proxy_resi_ses_id` 和 `proxy_resi_ses_time` 并在后续每个 URL 字符串中保持一致。
{% endhint %}

## 代码示例

以下示例展示如何构造同时应用地理定位和粘性住宅代理 IP 约束的连接字符串。

{% tabs %}
{% tab title="Python（Playwright）" %}

```python
from playwright.sync_api import sync_playwright

username = "USERNAME_abc12"
password = "PASSWORD"
endpoint = "ubc.oxylabs.io"

# 定位纽约市并将住宅 IP 固定 30 分钟
geolocation = "p_cc=US&p_city=new_york"
sticky_proxy = "proxy_resi_ses_id=scrape_session_404&proxy_resi_ses_time=30"
browser_url = f"wss://{username}:{password}@{endpoint}?{geolocation}&{sticky_proxy}"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto("https://ip.oxylabs.io/location")
    print(page.title())
    browser.close()
```

{% endtab %}

{% tab title="JavaScript（Playwright）" %}

```javascript
import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";

// Target Texas state and pin the residential IP for 60 minutes
const geolocation = "p_state=texas&p_city=houston";
const sticky_proxy = "proxy_resi_ses_id=scrape_session_404&proxy_resi_ses_time=60";
const browserUrl = `wss://${username}:${password}@${endpoint}?${geolocation}&${sticky_proxy}`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const page = await browser.newPage();
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();
```

{% endtab %}

{% tab title="JavaScript（Puppeteer）" %}

```javascript
import puppeteer from 'puppeteer';

(async () => {
    const username = 'USERNAME';
    const password = 'PASSWORD';
    const endpoint = 'ubc.oxylabs.io';
    
    // Target Texas state and pin the residential IP for 60 minutes
    const geolocation = "p_state=texas&p_city=houston";
    const sticky_proxy = "proxy_resi_ses_id=scrape_session_404&proxy_resi_ses_time=60";
    const browserUrl = `wss://${username}:${password}@${endpoint}?${geolocation}&${sticky_proxy}`;

    const browser = await puppeteer.connect({
        browserWSEndpoint: browserUrl
    });
    const page = await browser.newPage();
    await page.goto('https://example.com');
    await browser.close();
})();
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/cn/headless-browser/di-li-wei-zhi-yu-dai-li-xuan-ze.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.